packerlschupfer/nova-voyager_firmware

# Nova Voyager 开源固件 **Teknatool Nova Voyager DVR** 钻床 HMI 控制器 (GD32F303RCT6, ST7920 16×4 LCD, FreeRTOS) 的开源替代固件。

Idle — target 1500 RPM, no depth target	Drilling at 1487 RPM, 32% load, 12.4 mm
Tapping with Depth+LoadInc+Quill triggers active	Menu: per-trigger configuration

## 与原始 Teknatool 固件的差异 | 方面 | 原版 (R2P06x CG) | 本固件 | |--------|----------------------|----------------| | 许可证 | 封闭，专有 | GPL-3.0 | | 源码 | 不公开 | 公开，完全文档化 | | 冷启动 | ~5 s | ~1.7 s | | 软启动 | ~0.5 s | ~0.25 s | | LCD 模式 | 图形模式 — 动画 logo，图标 | **仅文本** — 见下方说明 | | 攻丝 | 单一模式 | 6 种**可组合**触发器 + 手动踏板 | | 脚踏板输入 | 在 `X11` 上暴露了接口但**未使用** | 作为 PC3 输入驱动 — 实现免提断屑和反向覆盖（参见[脚踏板部分](#foot-pedal--optional-hardware-addition)） | | 硬件 E-Stop | 通过 UART 进行软件排队 | 在任何队列之前的直接 GPIO 切断 (PD4) | | 调度器 | 裸机 | FreeRTOS，5 个任务，带每任务心跳看门狗 | | 固件更新 | 仅限供应商工具 | 标准 USB DFU（配合配套 bootloader） | | 终端用户诊断 | 无 | 串行控制台：98 条命令，实时状态，栈/堆监视器 | | MCB 协议 | 未文档化 | 已在 `docs/MOTOR_PROTOCOL.md` 中文档化 | | 安全联锁 | 固定 | 防护罩 / 脚踏板 / 深度检查可单独配置 | **为什么是纯文本 LCD？** 原始固件以图形模式驱动 ST7920 用于启动动画和图标。我们特意保持纯文本模式：代码更简洁，启动更快，无闪烁，易于扩展。图形模式的驱动代码保留在仓库（`src/lcd_graphics*.c`，`src/gfx_*.c`）中，供任何想要恢复图标的用户使用 — 反向工程笔记另请参阅 `docs/ST7920_*.md`。 ## 快速开始 ``` # 构建生产固件 (120 MHz, optimized) pio run -e nova_voyager # 通过 ST-Link 烧录 (fast — 假定已通过先前的烧录解锁了 flash) ./flash_firmware.sh quick # 从 OEM 固件首次安装 (slow — 解锁 flash 保护) ./flash_firmware.sh custom # 恢复 OEM 固件 (重新锁定 flash 保护) ./flash_firmware.sh original ``` 配套 USB DFU bootloader： [Packerlschupfer/nova-voyager_bootloader](https://github.com/Packerlschupfer/nova-voyager_bootloader)。 ## 硬件 | | | |---|---| | MCU | GD32F303RCT6 (ARM Cortex-M4F, 120 MHz, 256 KB flash, 48 KB RAM) | | 显示屏 | ST7920 16×4 字符 LCD，8 位并行 | | 电机链路 | USART3 @ 9600 波特率 连接 MCB (开关磁阻电机控制器) | | 输入 | 旋转编码器 + 7 个按钮 (EXTI)，脚踏板 | | 传感器 | 深度 (ADC)，防护开关，E-Stop | | Bootloader | DFU 位于 `0x08000000` (12 KB)，应用程序位于 `0x08003000` (244 KB) | ### 引脚映射（关键信号） | 信号 | 引脚 | 备注 | |--------|-----|-------| | LCD 数据总线 | PA0–PA7 | 8 位并行 | | LCD RS / RW / E | PB0 / PB1 / PB2 | 控制线 | | 编码器 A / B / 按钮 | PC13 / PC14 / PC15 | 4 计数/棘爪，按钮 = 粗/细切换 | | E-Stop | PC0 | 高电平有效 — 连接到直接 GPIO 切断路径 | | 防护开关 | PC2 | 高电平有效 (断开 = 高电平) | | 脚踏板 | PC3 | 低电平有效 (X11 接口 — 见下文) | | 深度 ADC | PC1 | ADC1 通道 11 | | 电机 UART | PB10 / PB11 | TX / RX | | 调试 UART | PA9 / PA10 | TX / RX，9600 波特率 | ## 脚踏板 — 可选硬件加装 脚踏板完全由用户自行选择 — 没有它所有功能也能正常工作，并且可以在 `菜单 → 攻丝 → 踏板` 中禁用踏板触发器。 ### 所需部件（参考构建） 这是我们使用的部件 — 任何同等规格的替代品均可。 | 部件 | 规格 | 位置 | |------|------|-------| | 脚踏开关 | **TFS-1** 瞬时 SPST，常开触点 | 位于操作员脚下 | | 面板插座 | **GX12 2 针** (航空样式螺钉锁紧) | 面板安装在机壳上，位于卡盘防护罩连接器的对面 | | 内部线缆 | **JST PH 2.54mm 3 针** 连接到 HMI 板的 `X11` 接口 | 面板插座和 PCB 之间的机箱内部 | | 两段短线缆 | ≥ 22 AWG，长度随意 | 所有接头处均需做应力释放 — 这是踏板，会被踩踏 | 3 个 JST 引脚中仅使用了 2 个（信号 + GND）。`X11` 上的第三个引脚悬空。输入为参考 `GND` 的 `PC3`，**低电平有效** — 当线路被拉低到地时，固件读取为“已按下”。内部上拉电阻意味着空闲状态的踏板（触点断开）无需任何外部电阻即可读取为“已释放”。 ### 接线 ``` foot chassis panel HMI board jack ┌─────┐ ┌─────────┐ ┌─────────────┐ │TFS-1│ ─── 2 ──────┤ GX12 ├── 2 ──────────┤ X11 (JST PH │ │ NO │ wire │ 2-pin │ wire │ 3-pin): │ │ SPST│ │ panel │ │ PC3 — sig │ │ │ │ jack │ │ GND │ └─────┘ └─────────┘ │ N/C │ └─────────────┘ <— external —> <— bulkhead —> <— internal —> ``` 任一触点方向均可 — 固件在软件中（~20 ms）对线路进行消抖处理，并在 `task_ui.c` 中读取电平。 ### 踏板的功能 可在菜单中根据攻丝模式进行配置，典型用途包括： - **`Pedal` 触发器（手动）** — 断屑：按住切削，松开反转；或定时 `CHIP_BREAK` 模式，每次按下触发短暂的换向脉冲。 - **`Quill` 触发器覆盖** — 踏板可以覆盖主轴方向的自动反转（例如，在切削过程中强制反转，或在每次按下时切换方向）。参见 `include/config.h` 中的 `quill_pedal_mode_t`。 - **所有触发器** — 踏板可与六个自动触发器中的任何一个组合；如果两者同时触发，踏板优先（最高优先级）。 如果已连接踏板但您在特定操作期间不想使用它，请在菜单中保持 **`Pedal`** 触发器未选中状态，它在电气上将被忽略。 ## LCD 布局 ``` 0 1500 ← actual RPM (left) target RPM (right) 0% IDL --- --- ← load%, state, depth tgt, tap mode/direction T: D: 0.0 ← target depth (T:) current depth (D:) SPD TAP DEP MOD ← F-key labels (F1..F4) ``` 状态码：`IDL` 空闲 · `RUN` 钻孔中 · `TAP` 攻丝中 · `ERR` 错误。 ## 攻丝系统 六种**可组合**触发器。启用任意子集；触发时最高优先级的触发器胜出。 | 代码 | 触发器 | 监视内容 | 用例 | |:----:|---------|-----------------|----------| | `D` | 深度 | 主轴深度传感器 | 在目标深度停止 / 反转 | | `I` | 负载增加 | KR (负载 %) 尖峰 | 盲孔 / 过度阻力 | | `S` | 负载打滑 | CV (指令速度) 过冲 | 通孔出口检测 | | `C` | 离合器打滑 | 负载平台期 | 扭矩限制器 / 离合器接合 | | `Q` | 主轴 | 主轴方向改变 | 主轴抬起时自动反转 | | `K` | 啄击 | 定时正/反转循环 | 丝锥排屑 | | `P` | 踏板 | 脚踏板状态 | 手动覆盖 (断屑 / 保持) | 显示字符串 `TAP:DISQ` 表示 深度 + 负载增加 + 打滑 + 主轴 均处于活动状态。 优先级排序：**踏板 > 主轴 > 深度 > 负载 > 啄击**。

示例组合

- **深度 + 主轴** — 主轴抬起时自动反转，到达目标深度时硬停止 - **负载增加 + 负载打滑** — 同时涵盖盲孔和通孔场景 - **主轴 + 踏板** — 自动主轴跟随加上手动覆盖 - **深度 + 负载 + 主轴** — 最大范围安全保障：任一条件满足即触发

## 架构 5 个 FreeRTOS 任务通过队列 + 状态互斥锁进行协调： | 任务 | 优先级 | 栈 | 频率 | 角色 | |------|:---:|:-----:|:---:|------| | Main | 1 | 256 W | ~100 Hz | 事件队列，控制台，看门狗 | | Depth | 2 | 96 W | 50 Hz | ADC 主轴传感器 | | UI | 2 | 128 W | 50 Hz | 按钮，编码器，LCD | | Tapping | 3 | 160 W | 20 Hz | 攻丝状态机 | | Motor | 4 | 192 W | 2/20 Hz | UART 连接 MCB (自适应：空闲 vs. 运行中) | 每任务心跳看门狗：主循环仅当所有任务最近都更新了其心跳*且*事件队列未饱和时，才喂 IWDG。 三层电机栈： ``` task_motor.c FreeRTOS coordination └─ motor.c High-level API (start/stop/setSpeed/...) └─ motor_protocol.c Packet build/parse └─ motor_uart.c USART3 hardware abstraction ``` ## 串行控制台 以 9600 波特率连接 (PA9/PA10)。共有 98 条命令可用。最常用的： | 命令 | 作用 | |---------|--------------| | `HELP` | 列出所有命令 | | `STATUS` | 系统状态，队列，溢出计数器 | | `STACK` | 每任务的 FreeRTOS 栈高水位标记 | | `DEPTH` | 实时深度传感器读数 | | `GUARD` | 防护罩 / 踏板 / E-Stop GPIO 状态 | | `GF` | 查询 MCB 标志 | | `CV` | 查询 MCB 当前速度 | | `TAP` | 显示 / 配置攻丝触发器 | | `RESET` / `COLDBOOT` | 软件复位 (软复位 / 冷启动模拟) | | `DFU` | 重启进入 USB DFU bootloader | | `SAVE` | 将设置持久化保存到 flash | ## 安全性 - **硬件 E-Stop** — 在任何排队命令之前直接 GPIO 写入 PD4 (电机使能)。不会因任务卡死或队列满而延迟。 - **防护罩联锁** — 防护罩打开时电机拒绝启动；运行中打开防护罩时自动停止。可配置。 - **看门狗** — IWDG ~3 秒，仅当所有任务存活且事件队列正在排空时才喂狗。队列饱和被视为停顿。 - **乐观状态写入** — `motor_running` 在启动时立即设置，因此编码器速度更新路径永远不会被陈旧的标志所门控。 - **设置 flash 写入保护** — `settings_save()` 在电机运行时拒绝写入 flash（flash 擦除会阻塞 CPU 约 20 ms）。 ## 项目状态 - 所有主要功能均已实现；固件已在日常使用中 - **81 个本地单元测试**（80 个通过，1 个已记录的跳过 — 需要动态 UART mock） - 生产构建中 **0** 个编译器警告 - 占用约 **~33% flash** / **~23% RAM**（留有充足余量） 可能的后续工作（均不紧急）： - 动画图形模式（驱动已就绪，仅未启用） - 用于外部日志记录的蓝牙/串行遥测 - 基于编码器的步进/方向支持，用于 CNC 风格的操作 ## 许可证 GNU通用公共许可证 v3.0 — 见 [LICENSE](LICENSE)。 本固件由社区进行逆向工程。**无保修。** 您需自担风险在自己的硬件上运行它。 ## 鸣谢 逆向工程和开发基于对原始 Teknatool 固件（R2P05x、R2P06e、R2P06k 变体）的独立分析，并结合了 MCB 协议的逻辑分析仪抓包结果以及大量耐心的实验。感谢车床/钻床社区分享他们的笔记和观察。

标签：CNC控制, FreeRTOS, GD32F303, GPIO控制, GPL-3.0, HMI人机界面, PKINIT, ST7920, USB DFU, 云资产清单, 制造执行系统, 协议逆向, 固件替换, 客户端加密, 嵌入式开发, 工业控制系统, 工控协议分析, 工控安全, 开源固件, 机电控制, 硬件E-Stop, 硬件黑客, 自动化控制, 逆向工程, 钻床控制