OPEN SOURCE DEEP DIVE
YHorizon-JM:可完整复刻的 57 mm 非商用关节电机
57 mm、约300 g的非商用关节电机,公开机械、驱动、FOC固件与CAN协议;双编码器恢复约3.875圈输出位置,但第一版缺少完整保护与通信超时。
YHorizon-JM 是一个把机械、驱动板、固件、通信协议和上位机工具一起公开的关节执行器样机。它不是只展示外观的模型,也不是把现成舵机塞进外壳的改装件:57 mm 直径、52 mm 厚、约 300 g 的壳体内包含 WK4310 无刷电机、8:1 行星减速器、双编码器、三相功率级和控制板。项目最值得看的地方,不是参数表上的 6 Nm 峰值,而是从磁编码器读数到 CAN 帧、从电流采样窗口到位置环减速曲线,每一层都能在仓库里找到对应实现。
项目定位:一套可以追到源码的执行器样机
仓库地址为 YHorizon-Robot/YHorizon-JM。当前代码对应第一版样机,主控仍是 GD32F303,总线仍是最高 1 Mbps 的经典控制器局域网。作者没有把后续规划写成现成功能:改用 GD32C113、支持 CAN FD、多轴同步、完整故障保护和力矩反馈,都明确留在未来工作里。这个版本更适合作为机械装配、磁场定向控制、CAN 设备协议和桌面级测试平台的参考,而不是拿来做未经改造的量产关节。
| 层面 | 公开内容 | 复刻时需要关注的重点 |
|---|---|---|
| 机械 | 装配体 STEP、CNC 零件、齿轮图纸、零件与外购件清单 | 轴承配合、行星架、输出盘同轴度,以及螺纹孔在自家加工条件下的偏差 |
| 硬件 | 立创 EDA Pro 源工程、原理图、Gerber、元器件清单 | 功率级散热、母线电压范围、低边采样网络和 SWD 烧录接口 |
| 固件 | GD32F303 控制代码、SVPWM、编码器、电流环、状态机、标定 | WK4310 的相电阻与相电感必须和实际电机匹配 |
| 软件 | CAN 协议文档、Python 打包解析、命令行与图形界面上位机 | 位置和速度均为输出轴口径,命令通道必须与当前模式一致 |
这种“全栈公开”减少了接口猜测,却没有降低装配门槛。项目说明明确要求准备压力机、乐泰螺纹胶或固持胶、内六角扳手、小十字螺丝刀和 0.8 mm 刺破式端子线。CNC 零件也不保证与作者加工结果完全一致,孔位与配合应按实物修配。对一套包含行星齿轮、轴承和磁编码器的样机来说,这些提醒不是附属说明,而是复刻能否稳定运行的前提。
机械结构与参数边界
当前样品的外形是 57 mm 直径、52 mm 厚度,质量约 300 g。电机采用 14 对极的 WK4310,后接 8:1 行星减速器,因此输出轴速度是电机轴速度的八分之一,理论输出力矩则是扣除传动损耗后的电机力矩八倍。仓库给出 3 Nm 连续、6 Nm 峰值和最高 48 V 供电,但没有把电机的连续热能力、驱动器温升、减速器寿命和壳体散热整合成完整的热裕量曲线。能输出某个峰值力矩,不等于能在任意环境温度下长期反复输出。
机械目录的价值在于能完整追踪零件关系,而不只是提供一份外观参考。顶层装配体位于 mechanical/asm/YHorizon-JM-asm.STEP,CNC 零件按输出端盖、下端盖、后壳、电机输出盘、外齿圈支架和行星保持架拆分,齿轮图纸则放在 mechanical/gears/。这意味着复刻者可以检查齿数、保持架、输出盘和轴承位是否互相闭合,而不是只看一张爆炸图。
这类小型关节最容易出问题的地方通常不是电机是否能转,而是装配后的摩擦、偏心、轴向预紧和编码器同轴度。行星齿轮的背隙、保持架刚性、输出盘跳动以及磁铁与编码器的间距,都会改变控制环看到的机械负载。固件里的电流环只能处理电磁响应,无法识别一个装配过紧的轴承。因此,机械复刻后应先做空载低速、低母线电压测试,再逐步检查温升、噪声、回差和位置重复性,不能直接套用高增益位置参数。
双编码器如何恢复多圈绝对位置
第一版使用两颗 MT6701 磁编码器,并通过 30 齿与 31 齿的游标组合恢复电机轴的多圈位置。单个磁编码器只给出电机轴一圈内的绝对角度;减速器输出一圈对应电机轴八圈,所以如果只记住单圈角度,输出轴经过整圈后会丢失正确分支。30/31 齿的齿数互质,使两组角度残差在 31 个电机轴圈内保持唯一,之后才重新开始循环。
实现位于 firmware/Foc/foc_vernier.c。代码先把两个编码器的原始计数归一化,再计算 residual = frac(v + (30/31)u),将残差量化到 31 个候选区段,并通过容差检查拒绝明显不一致的读数。得到的电机轴绝对角乘以 0.125 后成为输出轴位置。31 个电机轴圈除以 8,对应约 3.875 个输出轴圈;超过这个范围后,游标组合本身会出现分支歧义,固件再依靠连续运动时的增量位置进行延拓。
| 量 | 实现值 | 含义 |
|---|---|---|
| 编码器 | 双 MT6701 | 一颗读取电机轴主角度,另一颗读取与 31 齿轮关联的辅助角度 |
| 齿数 | 30 与 31 | 互质,形成 31 个可区分区段 |
| 多圈范围 | 31 个电机轴圈 | 约 3.875 个输出轴圈后进入下一轮绝对区间 |
| 速度估计 | 500 Hz 二阶低通 | 对电角度差分后转换为机械角速度,降低量化噪声 |
| 丢帧处理 | 按上一速度预测 | 单次读取失败时用预测角度推进,避免控制周期立刻跳变 |
这里有两个容易忽略的限制。第一,绝对位置恢复的讨论首先发生在电机轴,输出轴数值只是除以减速比后的结果;第二,固件不是“永远绝对”的无上限记录器,它用游标提供 31 个电机轴圈的绝对种子,再用连续增量跨越游标循环。如果系统断电后输出轴被外力转出可恢复范围,或者装配时两个编码器的零位关系改变,就必须重新标定。
控制板与电流采样
控制核心为 GD32F303CCT6,系统时钟 112 MHz。三相桥由 FD6288 驱动,PWM 频率为 20 kHz,外环控制频率为 4 kHz。电流环的目标带宽是 500 Hz。代码把 WK4310 的线电压相电阻 10.32 Ω、线电感 4.76 mH 各取一半,得到星形等效的相电阻与相电感,再用带宽计算 PI 增益。这个细节很重要:使用不同电机却没有重新测量参数时,电流环可能高增益振荡,也可能响应过慢。
第一版采用低边分流采样。两相各使用 1 mΩ 分流电阻,电流检测放大倍数为 20。ADC 使用 1.5 周期采样,采样触发必须落在下桥臂打开的短暂窗口内。配置中记录的死区约为 98 ns,采样触发还留出约 112 个定时器时钟周期的等待时间。上电时会连续采集 32 个样本,求两相零电流偏置;如果采样失败,则回落到 2048 的中间值。母线电压通过分压网络检测,代码每 5 ms 轮询一次,并用测量值调整电流 PI 的前馈归一化。
| 项目 | 当前实现 | 工程意义 |
|---|---|---|
| 控制与功率器件 | GD32F303CCT6、FD6288 | 主频 112 MHz,三相半桥输出 |
| 调制与周期 | 20 kHz PWM,4 kHz 外环 | 每个外环周期包含五个 PWM 周期 |
| 电流采样 | 1 mΩ、20 倍、1.5 周期 | 只能在下桥臂导通窗口内有效测量 |
| 电流环带宽 | 500 Hz | 根据实际电机的电阻与电感计算 PI |
| 保护与测量 | 母线检测、电流偏置、单一切标定故障 | 尚无温度、过流、过压、堵转等完整保护 |
低边采样对时序非常敏感。占空比接近满调制、死区较长或采样窗口被压缩时,ADC 可能捕捉不到真实下桥臂电流。仓库声明“在 V_LIMIT 下可以工作”,但这并不等于在所有母线电压、温度和占空比组合下都得到验证。复刻者应先用示波器检查采样触发与桥臂电流窗口,再相信固件里的电流数值。
默认内环为电流模式,CFG_INNER_LOOP_VOLTAGE 是编译期回退选项。只要电机电阻和电感与 WK4310 不同,就不能把默认 PI 参数当成通用值。电压模式也不意味着更安全:它绕过了电流闭环,外环命令将直接改变交轴电压。切换内环后,原有速度和位置增益的含义与尺度会变化,必须重新整定。
从电流环到三种外环
固件在 20 kHz PWM 中断中读取主编码器、计算电角度、更新电流 PI、执行逆帕克变换和空间矢量调制。4 kHz 控制中断则维护游标多圈位置、输出轴位置与速度,并计算力矩命令。电流模式中,外环输出的 t_ref 会映射为交轴电流参考:Iq_ref = t_ref × I_LIMIT / V_LIMIT。当前配置为 5 A 与 0.5 pu,因此 t_ref = 0.5 对应 5 A,指令实际可达范围约为正负 5 A。
协议文档把比例写成默认 10 A/pu,数学上来自 5 A 除以 0.5 pu;但输出端同时把 t_ref 钳位在正负 0.5 pu,所以有效电流命令是正负 5 A,而不是正负 10 A。这个区别不只是文字问题:上位机若按 10 A/pu 把电流值直接换算成无量纲命令,就可能低估实际命令幅度。更清楚的说法应当是“1 pu 的理论换算为 10 A,但当前配置的可达范围为正负 0.5 pu”。
| 模式 | 外环计算 | 关键参数与行为 |
|---|---|---|
| 运动模式 | t_ref = Kd × 速度误差 + Kp × 位置误差 + 前馈 | 增益写入随机,属于刚度与阻尼式控制;前馈被限制在正负 1 pu,最终力矩命令仍被钳位 |
| 速度模式 | 速度误差经过 PI,积分与输出均受 0.5 pu 限制 | 参数以输出轴速度定义,命令与反馈单位均为弧度每秒 |
| 位置模式 | 位置 PID 产生速度参考,再由速度 PI 产生力矩命令 | 远距离使用平方根减速限制,接近目标后混合到位置 PID;内环饱和时冻结位置积分 |
位置模式不是简单的一次比例控制。代码先根据最大速度和默认加速度计算受约束的接近速度,在距目标较远时使用 sqrt(2 × a × |误差|) 形态的速度轮廓,接近目标后逐渐过渡到位置 PID。速度环内层仍使用速度模式参数,并对饱和情况做了条件抗积分饱和。对于初次复刻,建议先让 Kp、Ki、Kd 都保持保守,观察输出轴在空载和轻载下的阶跃响应,再增加参数。
所有位置、速度和力矩反馈都以输出轴口径解释。运动反馈里的 t_ref 是当前力矩命令,不是测得力矩。当前硬件没有相电流到输出力矩的工厂标定,也没有力矩传感器,因此不能把反馈字段当作真实负载力矩。协议也没有独立的“实际 Iq”字段;上位机若要检查电流,只能通过调试接口或扩展协议补充遥测。
CAN V1.0:严格、有限且没有看门狗
通信层使用经典 CAN 2.0,标准 11 位标识符,固定 8 字节数据,默认 1 Mbps,节点标识范围为 1 到 63。协议把实时命令、增益、管理、反馈、状态和标定进度分到不同标识符段。运动、速度、位置命令分别使用 0x100、0x140、0x1C0 加节点号,反馈使用 0x300 加节点号。所有数值均为小端编码。
| 步骤 | 主机动作 | 设备响应或限制 |
|---|---|---|
| 上电 | 等待标定或读取状态 | 成功进入运行,失败进入故障;没有单独的使能命令 |
| 选择模式 | 发送 SET_CONTROL_MODE | 清除积分和力矩命令,必须再发送匹配模式的实时帧 |
| 设置增益 | 向 0x180 段发送对应模式参数 | 非法模式或本应为零的参数非零时拒绝,旧参数保留 |
| 实时控制 | 按模式发送运动、速度或位置帧 | 每轮接收只应用最后一条有效实时帧,并回报 0x300 |
| 停止 | 发送零速度或保持当前位置,或断电 | 协议没有命令超时,失去主机后最后一条命令会继续生效 |
没有命令超时是这套固件最需要重视的行为之一。CAN 总线短暂断线、上位机崩溃或控制循环停止后,电机不会自动归零;它会保持最后一次有效命令,直到同模式新命令、模式切换、标定、故障或断电到来。对桌面测试台,这意味着必须准备硬件急停和独立断电手段;对整机,这意味着上层软件必须把通信心跳、看门狗和硬件保护纳入系统设计,不能假设关节自己会刹车。
协议也没有 ENABLE 或 DISABLE。管理命令表里只接受设置零位、清除标定故障、启动标定、切换模式、修改节点号、保存用户参数、读取状态和读取增益。未知命令,包括旧版工具包中可能存在的使能编号,都会返回 INVALID_COMMAND。这减少了状态机的模糊性,但也意味着接入者必须按实际实现的 V1.0 协议处理,而不能照搬其他关节厂商的习惯。
同一接收循环中出现多条实时帧时,只有最后一条有效帧会被应用到控制状态。这样可避免控制循环追赶历史命令,但也意味着高频发送并不能形成队列;中间命令不会逐条执行。模式不匹配的实时帧会被静默丢弃,不返回错误。因此,上位机应在切换模式后等待确认,再用新模式的帧开始控制,并把反馈超时视为必须由系统层处理的故障。
标定、零位与故障恢复
编码器标定是阻塞式流程。主机发送 START_ENCODER_CALIBRATION 后,设备先确认进入标定状态,然后主循环被占用数秒。标定先进行对齐和预检查,再以低速正反方向各旋转约四个电周期,采集电角度与机械角度的偏差,估计极对数、方向与电气偏移,最后写入非易失存储。期间每约 50 ms 发送一次进度,阶段变化时还会立即发送一帧。标定完成后,接收队列里残留的实时命令会被清空。
标定失败会进入故障状态并置位标定故障位。当前唯一实际使用的故障位是 bit10。CLEAR_FAULT 只清除这一项,并不会恢复控制能力:清障后状态回到运行,但 PWM 仍关闭,必须重新标定才能继续运动。这个设计避免了“按一下清障就立即带载运行”的危险,但也要求上层明确区分“状态显示运行”和“输出已经安全使能”。
保存用户参数、设置节点号和零位也会短暂停止 CAN,以便写 Flash,再重新启动控制器。节点号可在 1 到 63 之间修改;板上按钮也能进入节点号编辑,LED 用长闪与短闪表示十位和个位。零位和速度、位置增益可以保存,运动模式增益只保存在随机存储器中。固件没有独立的温度测量、过流比较器、过压保护、堵转检测和主动故障广播,状态字段中的温度目前固定为零。这些空白必须在外围系统中补齐。
复刻、烧录与上位机
固件使用 arm-none-eabi-gcc、CMake 和 Ninja 构建,目标文件为 firmware/build/gd32f303/YHorizon-JM.elf。仓库提供 Linux 与 Windows 的环境安装、构建和烧录脚本。调试探针采用 CMSIS-DAP 加 SWD;官方 OpenOCD 通常没有 GD32F30x 驱动,脚本因此回落到兼容配置文件,并明确不做整片擦除。复刻时应先确认芯片容量、启动文件和链接脚本与实物一致,再执行烧录。
Python 上位机位于 sdk/python/,使用 python-can 访问 SocketCAN 或串行 CAN 适配器。命令行工具可以设置运动增益、按固定频率发送位置、速度与前馈命令,并解析反馈、确认、状态和标定进度。协议解析模块还提供从 t_ref 换算交轴电流或交轴电压的辅助函数。第一次上电建议只监听,确认状态、母线电压和错误码,再发送增益和低幅命令。
真正需要警惕的工程缺口
这个项目最有价值的部分,也正是它最需要被谨慎使用的部分。仓库给出了可复刻的硬件与软件链条,但第一版仍有明显的保护缺口:没有测得输出力矩,没有温度采样,没有过流、过压和欠压保护,没有堵转检测,没有主动故障事件,也没有通信超时停机。作者在安全说明中要求配置硬件急停,并明确表示未完成限流、过流和急停验证前不要在人体附近满功率运行。应将这条要求视为设计输入,而不是法律免责声明。
文档内部还有一处已经可见的漂移。英文仓库开头仍把第一版描述为电压模式伺服,但 README 参数表、协议文档和 config.h 都显示默认内环是电流模式,电压模式只是编译期回退。复刻者应以实际源码和配置为行为依据,并把这类描述差异视为版本演进留下的痕迹。另一个需要修正的表述是前述 10 A/pu:换算比例与钳位后的可达范围必须分开写清楚。
供电方面,仓库写“最高 48 V”,而默认标称值是 24 V。48 V 使用时不仅要改标称配置,还要检查功率器件、电容、母线分压和散热是否满足要求。首次调试应使用较低母线电压、低电流限制和受限机械行程,先验证标定、方向、零位、反馈符号与急停,再提高功率。不要在一台尚未验证编码器方向的关节上直接闭环到刚性负载。
许可证:公开源码不等于可商用开源
项目自称开源,但实际权利组合应更准确地描述为“源码公开的开放硬件”,而不是没有限制的开源产品。机械与硬件目录采用 CC BY-NC-SA 4.0,固件、SDK 与工具目录采用 GPLv3;此外,顶层许可证和 README 又写明整个项目仅供非商业学习和交流,无论采用哪套目录许可证都不允许商业使用。GitHub 将该仓库许可证识别为 NOASSERTION,这也说明自动识别无法把这种叠加条款归入单一标准许可证。
| 内容 | 目录 | 声明许可证 | 额外限制 |
|---|---|---|---|
| 机械与电子硬件 | mechanical/、hardware/ | CC BY-NC-SA 4.0 | 禁止商业使用,衍生设计保持相同许可并署名 |
| 固件、SDK、工具 | firmware/、sdk/、tools/ | GPLv3 | 顶层文件又附加全项目非商业使用限制 |
| 文档与未声明内容 | 其他路径 | 默认 CC BY-NC-SA 4.0 | 第三方文件优先遵循其自带许可证 |
如果目标是学习 FOC、装配一台个人测试关节,这个仓库提供了罕见的高完整度材料;如果目标是产品化、代工、销售或收费集成,不应自行假设 GPLv3 目录可以覆盖顶层的商业限制。作者明确把商业合作单独列出,说明这类使用需要另行授权。工程判断和法律判断应分开:代码是否跑得通,与是否有权把它放进商业产品,是两个独立问题。
适合谁,下一步走向哪里
YHorizon-JM 更适合三类读者。第一类是希望看清一颗机器人关节如何从机械零件、磁编码器和功率级组合起来的人;第二类是要研究低成本 FOC、低边电流采样和游标编码器的人;第三类是已经在使用成熟商用关节,但希望比较 CAN 协议、控制状态机和安全边界的人。它不适合作为第一套直接带人运行的系统,也不适合跳过装配验证直接接入高负载机械臂。
作者给出的下一步方向是更换 GD32C113,引入 CAN FD 和多轴同步,并补齐使能、过流、过压、过温、堵转、实际力矩和主动故障事件。这个路线反映了第一版真正的短板:不是算力不足,而是单轴通信和系统级安全能力有限。只有在这些能力补齐后,它才更接近可嵌入多关节机器人系统的执行器平台。
作为第一版样机,它的价值在于把完整证据链摆在同一个仓库里。读者可以沿着机械 STEP 追到驱动板,再沿着 ADC 触发追到电流 PI,沿着 CAN 帧追到位置环,最后用 Python 工具读出状态。与此同时,仓库也清楚暴露了样机与产品之间的距离:标定会阻塞、通信会保持最后命令、保护尚未闭环、许可证禁止商用。把这些边界和参数一起读懂,才是这个项目最可靠的使用方式。