ZeroErr 关节模组公开协议工具包
通过 CANopen 或 EtherCAT 控制 eRob 关节模组。支持 Windows、macOS；提供设备发现、公开字典查询与读写、位置/速度/电流模式、故障复位、保存参数和 CSV 采集。
模组侧接口依据 ZeroErr 官网 CANopen EDS、EtherCAT ESI 和通讯手册。基础控制采用 CiA402，厂商扩展对象仅使用官网描述文件公开的对象。两条通讯路径独立，EtherCAT 无需 USB-CAN。
1. 安装
Python 3.10 或更新版本。在解包目录执行：
python -m venv .venvWindows 使用 .venv\Scripts\python.exe；Mac 使用 .venv/bin/python。以下 python 均指当前虚拟环境解释器。
python -m pip install -r requirements.txt先确认连接协议：CANopen 安装 canopen/requirements.txt，EtherCAT 安装 ethercat/requirements.txt；同时使用两种协议时安装根目录 requirements.txt。
| 系统 | CANopen 接口 | EtherCAT 接口 |
|---|---|---|
| Windows | GCAN ECanVCI SDK、SLCAN、gs_usb，或 python-can 支持的适配器 | 有线网卡 + Npcap，勾选 WinPcap API-compatible Mode |
| macOS | SLCAN 串口型或 gs_usb 兼容适配器 | 有线网卡 + PySOEM + BPF 访问权限 |
GCAN：包内包含厂家公开 SDK 的 32 位和 64 位 ECanVCI DLL 及 USB 依赖库，程序按 Python 位数自动选择，无需另装开发 SDK 或配置 DLL 路径。Windows 仍需安装适配器的系统 USB 驱动。使用其它 SDK 时可用 --dll 或 ZEROERR_ECAN_DLL 指定路径。Windows DLL 不能在 Mac 使用；已有适配器能否用于 Mac 取决于型号和厂家驱动。CANopen 协议不要求更换 CAN 接线。
gs_usb：另装 canopen/requirements-gs-usb.txt 与 libusb；Mac 可用 brew install libusb。SLCAN：安装适配器厂商的串口驱动，选择 /dev/cu.* 或 Windows COM 口。不要将普通传感器串口当作 SLCAN。
EtherCAT Windows 安装 Npcap。Mac 不需要 Npcap，权限不足时使用 sudo 加虚拟环境 Python 的绝对路径运行 detect / connect；如果 PySOEM 需要源码构建，安装 Xcode Command Line Tools。桌面 Python 周期通讯不是硬实时主站。
Mac 完整安装、接线、常驻服务及权限处理见 macOS 使用指南。EtherCAT 服务启动时取得网口访问权限，之后同一服务的读写、运动和采集可用普通用户运行，不需每条命令重复 sudo。
2. 接线后发现
python scripts/zeroerr.py detect自动检测有线 EtherCAT 与已配置/可枚举 CAN 适配器，CANopen 默认扫描 Node ID 1–64。有多个响应时返回候选列表，不自动选择另一台。环境缺失会给出安装提示。
detect 按实际协议响应识别设备，不以“网线已插好”代替从站响应；串口只列候选，SLCAN 型号和端口需明确指定。返回 next_command 可直接继续：已有 EtherCAT 服务时读取状态，新发现的 EtherCAT 从站先连接。ethercat_environment.requirements 描述新开网口的条件，已有服务的普通用户客户端可直接复用服务。
指定 CAN 后端示例：
python scripts/zeroerr.py detect --can-interface ecan --can-channel 0
python scripts/zeroerr.py detect --can-interface slcan --can-channel /dev/cu.usbmodemXXXX
python scripts/zeroerr.py detect --can-interface gs_usb --can-channel 0Windows 未指定 CAN 后端时使用包内 GCAN DLL、设备 0、通道 0。其它适配器可设置 ZEROERR_CAN_INTERFACE 和 ZEROERR_CAN_CHANNEL，后续 CANopen 命令不用重复传后端。默认总线速率 1 Mbps，以设备实际设置为准。
发现结果明确列出已检查的设备、通道、节点及异常。默认范围是设备 0、通道 0、节点 1–64；可扩展范围，异常节点记录后继续检查其它候选：
python scripts/zeroerr.py detect --can-interface ecan --can-device-indices 0,1 --can-channels 0,1 --can-candidates 1-1273. CANopen
以下以 GCAN 通道 0、Node ID 3 为例。使用其它适配器时替换 --interface / --channel。--dll 可直接指定 SDK 路径。
python scripts/zeroerr.py canopen --interface ecan --channel 0 discover
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 state read ProductCode Statusword ErrorCode Pos SpdActual RatedCurrent
python scripts/zeroerr.py canopen dictionary Pos运动示例：速度 10000 count/s，运行 5 秒后停止；或位置移动 10000 count，运行窗口 3 秒后停止。
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 motion velocity --speed 10000 --seconds 5 --after stop
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 motion position --target 10000 --relative --speed 10000 --seconds 3 --after stop
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 motion current --ma 100 --seconds 1 --after stop--seconds 是本次运行观察窗口，不是“位置到达”的判据；窗口内未到目标时，--after stop 仍发 Halt。--after preserve 表示结束时不修改驱动目标。电流模式会产生持续转矩，速度由真实负载决定。示例数值按实际机械工况选择。
运动与 PDO 采集合并执行（初次配置时驱动处于失能）：
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 motion velocity --speed 10000 --seconds 5 --method pdo --configure-pdo --sources Pos,SpdActual,CurrentActual,TorqueActual,Statusword --output output/run.csv --after stop已有运动时只采集，不重新配置映射：
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 capture --seconds 5 --method pdo --sources Pos,SpdActual,CurrentActual,TorqueActual,Statusword --output output/capture.csv --after preserve无已配置 PDO 时使用 --method sdo 轮询。SDO 每个通道单独记录时刻与读取耗时，不保证同步采样。PDO 支持 4 帧，每帧最多 8 字节；本包按字段位宽分配。
PDO 周期同时设置 Event Timer 与 Inhibit Time：默认 10 ms 对应 Event Timer=10、Inhibit Time=100（100 μs/单位）。运动采集在 Pre-operational 下完成映射读取和订阅，再进入 Operational、启动运动。已有运动的独立采集保持原 NMT 状态。
stop 及 --after stop 下发 Halt 后持续读取速度、位置确认停止，返回 halt_sent 和 stopped。默认在 5 秒内确认速度绝对值不超过 10 count/s，且连续 0.2 秒位置范围不超过 2 count；阈值可通过命令帮助中的 stop 参数调整。
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 pdo-config --sources Pos,SpdActual,CurrentActual,Statusword --interval-ms 10
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 state write Accel=250000 Decel=250000
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 stop
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 disable
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 fault-reset
python scripts/zeroerr.py canopen --interface ecan --channel 0 --can-id 3 save基本 Python 通讯示例：python examples/basic_canopen.py --interface ecan --channel 0 --can-id 3。它只读取身份和状态，不运动。
4. EtherCAT
先按 detect 返回的接口和从站连接。下面用 Mac 有线网口 en5 举例；Windows 替换成 adapters / detect 返回的 GUID 或 NPF 名称。
网线直连电脑有线网口与模组 EtherCAT IN，模组单独供电；无需模组 IP 地址，也不通过 Wi-Fi 访问 EtherCAT。Mac 的 BPF 权限不足时仅对首次 discover / connect 使用 sudo，具体命令见 macOS 指南。
python scripts/zeroerr.py ethercat adapters
python scripts/zeroerr.py ethercat --interface en5 discover
python scripts/zeroerr.py ethercat --interface en5 --slave 1 connect
python scripts/zeroerr.py ethercat --interface en5 --slave 1 state read DeviceName Statusword ErrorCode Pos RatedCurrent
python scripts/zeroerr.py ethercat --interface en5 --slave 1 motion velocity --speed 10000 --accel 250000 --decel 250000
python scripts/zeroerr.py ethercat --interface en5 --slave 1 capture --seconds 5 --output output/ethercat.csv --after stop
python scripts/zeroerr.py ethercat --interface en5 --slave 1 close持续服务维护 PDO。motion 返回后继续执行目标；capture --after stop 结束时停止，--after preserve 结束时保留目标；stop 为 Halt，disable 为失能，close 为失能并关闭服务。运行时所有命令复用该服务，勿另开第二个主站。当前运动入口支持单从站；多从站支持发现和 CoE 读写。
其它模式：motion position --target 10000 --relative --speed 10000，motion current --ma 100。公开参数使用 state read/write；save 显式保存。手册规定每次重新使能后等待至少 500 ms 才发运动目标，程序已包含。
已连接后的基本 Python 示例：python examples/basic_ethercat.py --interface en5 --slave 1。它复用服务读取身份和状态，不改变运动目标或关闭服务。完整连接、运动、采集和结束命令见上方示例。排错与工况扩展见 EtherCAT 通讯参考。
5. 输出与能力范围
- 终端：JSON 状态、参数读回、设备地址、故障或输出文件位置。
- CANopen CSV：原始逐字段 CSV，以及每 PDO 帧或 SDO 轮询组一行的
.frames.csv；保留原值并提供电流换算 mA。不同 PDO 的字段留空，不插值拼接为同步数据。 - CANopen
.meta.json：额定电流、连接信息、请求工况、初始驱动设置、结束状态、每通道覆盖时长、实际频率、最大缺口和完整性标记。中断或覆盖不完整时保留.partial.csv/.partial.frames.csv，实际采集时长以元数据为准。 - EtherCAT CSV：PDO 行、位置、速度、电流、控制目标、状态字、WKC、有效标记和周期时间。
- 原始 CANopen EDS、EtherCAT ESI、官网手册与整理字典随包提供；说明见 SOURCES.md。
0x6077 虽名为 Torque actual value，在该手册中采用额定电流千分比，不直接给出负载端 Nm。高频波动分析先核对实际采样率。CANopen 采集是公开 SDO/PDO 实时采集，不包含驱动私有 Recorder。包内包含 GCAN 底层 DLL，不包含 Custom-CAN 通讯库、固件升级功能或固件源码。
错误结果提供执行阶段、节点、对象索引、操作和最近读取的设备状态（含距读取时长）。采集质量在结束后评价；采集完整性与停止确认分别报告。
通讯验证状态（用户确认）：
| 系统 | CANopen | EtherCAT |
|---|---|---|
| Windows | 已通过 | 已通过 |
| macOS | 尚未开展 | 已通过 |
macOS CANopen 因现用 USB-CAN 适配器不兼容 macOS 而尚未开展验证，属于适配器条件未满足，不是协议验证失败。上述结果未逐项记录设备型号、控制模式和采集工况，不扩展为所有适配器或所有工况均已实测。本包另提供离线协议与命令测试。
6. 离线测试
python -B -m unittest discover -s canopen/tests -v
python -B -m unittest discover -s ethercat/tests -v
python -B -m unittest discover -s tests -vCANopen 测试使用内存虚拟 CAN 总线，不扫描或控制硬件。