从零基础到能自己实现、调试、选型、补偿激光振镜系统的中文学习库。
覆盖四层：协议（XY2-100 / XY3-100）· 光学（5 轴振镜里的每一片镜片）· 硬件实现（FPGA / MCU）· 五轴与补偿（
q ↔ T运动学、标定、5D 补偿矩阵）
入口 → 🏠 开始这里.md；分类检索 → 🗂 按主题导航.md（Obsidian 打开即用；GitHub 上点此进入）
按学习顺序编号 —— 先建立直觉，再吃协议，然后动手，最后进光学、五轴补偿与资料。
| 目录 | 内容 | 篇数 |
|---|---|---|
00-入门篇/ |
振镜是什么、为什么需要数字协议、术语表、新手 10 个常见误区、6 周学习路线图 | 5 |
01-协议篇/ |
XY2-100 / XY2-100E、物理层与其他协议对比；按协议分组 | 8 |
02-硬件实现篇/ |
FPGA / MCU / 差分驱动，以及振镜电机、伺服反馈和 Z 轴执行机构专题 | 9 + 代码 |
03-调试与排错篇/ |
示波器测量方法、逻辑分析仪抓包、11 类故障速查、图形失真与标定 | 4 |
04-光学篇/ ⭐ |
光路架构 / 镜片与光学元件 / 光学计算与选型；原有镜片库与工具保留 | 17 + 工具 |
05-五轴与补偿篇/ ⭐ |
系统架构 / 运动学模型 / 标定与误差补偿；4+1 仿真代码完整保留 | 10 + 仿真平台 |
06-Zemax光学设计与仿真/ |
OpticStudio 光路建模、分析指标、ZOS-API 自动化路线（待软件实测） | 3 |
07-资源库/ |
官方文档、课程、开源项目、论文；24 份调研按协议/光学/五轴分类 | 4 + 24 |
08-速查卡/ |
协议一页纸、引脚接线速查、公式速查、光学速查卡、光学选型一页纸、五轴补偿速查卡（打印贴桌上那种） | 6 |
99-附件与下载/ |
图片、可运行脚本、链接完整性检查工具；厂商 PDF 与抓取缓存不入库，见 THIRD-PARTY.md | — |
笔记里的参数标注来源，可追溯到厂商文档； 标注 💡 的是工程经验解释，会明确说明"非规范原文"。 光学篇与五轴补偿篇中厂商未公开的指标（场镜平场性、镜片动平衡工艺、 precSYS 内部五轴拓扑、AOI 实测方案等）一律写明"未找到公开来源"，没有编造填充。
2026-10 分类整理：按主题细分 XY2-100、振镜本体、镜片知识库、五轴补偿与 Zemax 专题。 完整目录见
🗂 按主题导航.md；各章节链接已同步调整。
⚠️ 「5 轴振镜」在业界不是标准化术语——至少 5 种互不兼容的用法，采购前必须问清。 详见04-光学篇/光路与系统架构/00-光路总览：从 3 轴到 5 轴.md。
主要两支（除了都叫 5 轴，几乎没有共同点）：
| 进动派：SCANLAB precSYS | 变焦派：RAYLASE AM-MODULE III 类 | |
|---|---|---|
| 5 个轴 | x, y, z 焦点定位 + a, b 入射角 | X/Y 扫描 + Z 调焦 + 2 轴光学变焦 |
| 干什么用 | 控入射角 → 决定孔形（正锥/倒锥/零锥度） | 改光斑大小 |
| 场镜 | ❌ 固定物镜 f=75 mm | ✅ F-θ 场镜 |
| 幅面 | Ø2.5 mm | 100+ mm |
| 亮点 | ≤650 Hz（39 000 rpm） 环切，纯振镜无旋转光学件 | 幅面大，光斑可调 |
① 进动派光路（precSYS）：
激光器 → ⑪光束调理[扩束0.25–4× + 位置调节 + λ/2 + λ/4]
→ ⑫五轴扫描(x,y,z,a,b) → ⑬分束镜 → ⑭物镜(f=75mm)
→ ⑮保护玻璃 → ⑯加工气喷嘴 → 工件
⑬旁路 → ⑰光束位置测量（自动精细调节闭环）
② 变焦派光路（后置场镜，打标机最常见）：
① 激光器/光纤 → ② 准直镜 → ③ 变焦扩束镜组(M1 M2) → ④ 折转镜
→ ⑤ X 振镜(M3) → ⑥ Y 振镜(M4) → ⑦ 动态聚焦镜组(M5) → ⑧ F-θ 场镜
→ ⑨ 保护镜 → ⑩ 工件
另有 pre-scan（前置聚焦）架构：聚焦镜组放在振镜之前，不需要 F-θ 场镜 （RAYLASE AM-MODULE III / AXIALSCAN、SCANLAB varioSCAN II PR 型）。 三条架构的对比见光学篇第 3 节。
- 📖 进动派专题：
04-光学篇/光路与系统架构/16-precSYS 五轴微加工：进动架构与镜片.md - 📖 图文详解：
04-光学篇/光路与系统架构/00-光路总览：从 3 轴到 5 轴.md - 🖼️ 光路图（变焦派）：
99-附件与下载/图片/5轴振镜光路图.svg - ⚡ 接口层面的硬约束（变焦派适用）：XY2-100 只有 3 路（X/Y/Z），原生带不了 5 轴；
单线多轴只有 RL3-100（6 轴） 与 XY3-100（DB25 版 5 轴）。
⚠️ 但进动派走的是 Ethernet/EtherCAT + XML 作业，5 个轴由厂商内部闭环，压根不用 XY2-100。
⚠️ 协议对了、光路选对了，机器照样打不准 —— 因为真实机有安装误差、轴倾斜、 角度零偏、焦距误差。补偿就是把误差算出来、反着加回去。
05-五轴与补偿篇/ 是一条可运行的完整链路：
标定数据 → 补偿矩阵 → 逆运动学
calibration compensation kinematics
↑ │
└────── model.forward() ───┘ ★ 唯一真值来源
| 自由度 | 含义 |
|---|---|
q = [q₁,q₂,q₃,q₄,qf] |
四面振镜转角 + 末级光程 / Z5 直线位移 |
T = [X, Y, Z, α, β] |
焦点位置 + 两个方向分量角 |
| 关键数字（515 nm 标准档，仿真） | 值 |
|---|---|
| 补偿前 / 后 位置 RMSE | 64.87 µm → 0.002 µm（99.997%） |
| 补偿前 / 后 姿态 RMSE | 230.6 µrad → 0.003 µrad（99.999%） |
| 补偿矩阵 | 21×5 二阶多项式系数（1 常数 + 5 一次 + 15 二次） |
| 标称点雅可比奇异值 | [2.6994, 2.1889, 1.0007, 0.0504, 0.0429]，秩 5 |
| 标定采样存活率 | 5.7%（≈17.5 条候选留 1 条） |
⚠️ 这些是仿真量，不是设备精度。 模型只含确定性误差，不含噪声、伺服滞后、 热漂移与寿命；α/β（相对工件表面的入射角）现有公开资料给不出实测方案。
- 📖 章节入口：
05-五轴与补偿篇/系统架构/00-五轴补偿总览.md - 📖 装配与校核边界：
05-五轴与补偿篇/系统架构/08-precSYS五轴装配与校核边界.md - ⚡ 速查卡：
08-速查卡/06-五轴补偿速查卡.md
cd 02-硬件实现篇/代码
python xy2_encode.py selftest # 自检（编码 / 校验 / 中心值）
python xy2_encode.py encode 0 # 编码：算出 20 位帧
python xy2_encode.py decode 0x30000 # 反解一个帧
python xy2_encode.py table # 常用值对照表
python xy2_encode.py wave 0 # ASCII 波形（对着示波器看）
python cycle_accurate_model.py # 逐周期行为验证（7 项检查，已通过）cd 04-光学篇/代码
python optics_calc.py selftest # 自检 14 项（公式系数对不对）
python optics_calc.py spot 1064 160 10 # 算聚焦光斑与焦深
python optics_calc.py lens 1064 110 50 # 反推该选多大焦距的场镜
python optics_calc.py expand 3 12 # 算需要多大扩束倍率
python optics_calc.py collimate 50 0.12 100 # 光纤准直后的光束参数
python optics_calc.py power 1000 50 # 功率密度（比 LIDT 用）
python optics_calc.py curvature 160 200 # 场曲与离焦量估算
python optics_calc.py table 1064 # 常用场镜参数对照表自检里包含一条交叉验证：用公式反算厂商经验值 （JHC：10 mm 光斑 + F160 → 约 33 μm），算出 31.2 μm，偏差 <6%。
FPGA RTL（Verilog-2001，可综合）：
| 文件 | 说明 |
|---|---|
02-硬件实现篇/代码/xy2_100_tx.v |
发送器，附设计要点与踩坑记录 |
02-硬件实现篇/代码/tb_xy2_100_tx.v |
self-checking testbench（装 iverilog 可跑） |
Python + FastAPI + Three.js 的数字孪生，含契约测试：
cd 05-五轴与补偿篇/代码
启动网页.bat # 一键：建 venv → 装依赖 → 起服务 → 开浏览器
.\.venv\Scripts\python -m pytest # 全部契约测试
.\.venv\Scripts\five-axis-galvo # http://127.0.0.1:8000| 入口 | 说明 |
|---|---|
05-五轴与补偿篇/代码/导读.html |
可视化项目导读（双击打开，离线可读） |
05-五轴与补偿篇/代码/README.md |
平台完整技术文档 |
05-五轴与补偿篇/代码/docs/ |
4+1 模型说明、装配依据、资料索引 |
05-五轴与补偿篇/代码/src/five_axis_galvo/ |
模型 / 逆解 / 标定 / 补偿 / 验证 |
05-五轴与补偿篇/代码/tests/ |
契约测试（装配、逆解、补偿、4+1、遮挡等） |
平台不含动力学：650 Hz、伺服响应、滞后、热漂移、寿命均未建模； 也没有硬件发送功能 —— 只算到"该发哪条指令"。要真发，回
02-硬件实现篇/。
- XY3-100 与 XY2-100 的 CLK/SYNC 引脚是互换的——同一根 DB25，第 1/2 脚定义相反， 接上完全不动，但每条线量起来"都有信号"。而 XY3-100 标准原文却写着 "Same pinout as XY2-100(E), no hardware changes needed"，这句话只在数据线上成立。
- 校验位覆盖 19 位，不是 16 位。
P = XOR(控制字 001, D15…D0)—— 控制字含一个1，只算 16 位数据位会得到相反的结果。 两个流行开源库（georgemihaila/xy2-100、OPAL）都犯了这个错。 - 电气层是 RS-422，不是 LVDS——厂商推荐器件 AM26LS31 / UA9638 摆幅 ±2 V，LVDS 只有 ±350 mV。
- 厂商不公开"带宽"，且引脚不兼容——"带宽"是从时域指标反推的，量级约 0.5–1.3 kHz， 不是网传的 1–10 kHz；X/Y 引脚厂商间可能互换，RAYLASE ±15 V vs SCANLAB +30 V，接错可能烧设备。
- 聚焦光斑有两个公式，系数差 44% ⭐ 光学篇新增。
d = 1.83·λf·M²/D（厂商标称口径）vsd = 4λfM²/(πD)（未截断理想高斯）。 拿后者去质疑厂商手册"算错了"，是新手常见误判。 - 场镜焦距有 ±1.5% 制造公差 ⭐ 光学篇新增。 机械行程不能按名义值卡死，否则装不上或焦面不对。
- 机械行程 ≠ 工作域 ⭐ 五轴补偿篇新增。 转角上限写着 ±3.75°，但受 φ2.5 mm 视场限制，单轴实际只能用 0.6°~1.1°； 超过约 0.5° 就出域，2.0° 时直接打不到镜面。
α/β、AOI、RotZ 是三个不同的量 ⭐ 五轴补偿篇新增。α/β是方向的两个分量角，AOI 是相对工件法线的单一入射角，RotZ 是方位角 （垂直入射时无定义）。混用会让误差图和验收判据全部失效。- 仿真残差趋近 0 ≠ 实机精度高 ⭐ 五轴补偿篇新增。 补偿后位置 RMSE 0.002 µm 是无噪声确定性模型的自洽结果； 实机的噪声、重复性、伺服滞后、热漂移、寿命一个都没建模。
本仓库只收录原创内容。厂商 PDF 手册、网页抓取缓存、GPL 系第三方源码 因版权与许可证兼容性不入库，但每一份都在 THIRD-PARTY.md 里列了来源、许可证与获取途径，笔记中的参数依然能回到原文查证。
五轴补偿篇引用的三份厂商资料（precSYS 手册、CalWizard 手册、BeamMap2 白皮书） 与 precSYS 手册截图同样不入库，已按本库约定放进被忽略的
99-附件与下载/pdf/，出处登记在 THIRD-PARTY.md。
里面唯一入库的第三方代码是 XY2Galvo-rp2040（BSD-3-Clause，已保留其 LICENSE）。
- 笔记与文档（
*.md）：CC BY 4.0，见 LICENSE - 自写代码（
02-硬件实现篇/代码/、04-光学篇/代码/、05-五轴与补偿篇/代码/下的.v/.py/.js）：MIT
本库用于学习与沟通。协议参数以你手上那台设备的厂商手册为准； 涉及电气接线、电源引脚与激光安全的内容，动手前务必核对手册， 接错可能损坏设备，激光可能伤人。
本仓库原名 xy2-100-galvo-protocol-notes。2026-02 扩充为覆盖
协议 + 光学 + 硬件 + 调试的完整振镜学习库后，更名为 galvo-notes。
旧链接会自动重定向到新地址。
2026-09 融合了原 five-axis-galvo-5d-compensation 仓库的
五轴振镜 5D 补偿内容（运动学、标定、补偿矩阵、4+1 架构、装配校核、落地路线，
以及可运行的 Python + FastAPI + Three.js 仿真平台），
并把顶层目录重排为按学习顺序的连续编号（04-资源库 → 07-资源库、
05-光学篇 → 04-光学篇、07-速查卡 → 08-速查卡，05 号段给五轴与补偿篇）。