← 返回 AI 驱动安装与使用说明macOS 使用指南

macOS 接线、安装与权限

选择连接方式

接口连接方式软件条件
EtherCATMac 有线网口或系统支持的 USB-C/雷电有线网卡 → 模组 EtherCAT IN64 位 Python、PySOEM、BPF 访问权限
CANopen / SLCANMac USB → 支持 SLCAN 的 USB-CAN 适配器 → 模组 CANpython-can、pyserial，按适配器要求安装串口驱动
CANopen / gs_usbMac USB → gs_usb 兼容 USB-CAN 适配器 → 模组 CANpython-can、gs_usb、libusb

EtherCAT 和 CANopen 是独立入口，EtherCAT 连接无需 USB-CAN。模组另行供电；EtherCAT 使用有线以太网原始帧，不设置模组 IP、不经 Wi-Fi 或普通 TCP 连接。网卡名采用实际发现的 enX，不能认定 en0 就是有线网口。

ZeroErr 下载页提供公开协议资料和标为 Windows 的 eTuner；本包 Mac 路径由 Python 入口实现。USB-CAN 的 CAN 接线保持相同，电脑侧能否继续使用原适配器取决于其型号与 macOS 驱动。包内 Windows DLL 用于 Windows；Mac 选择 SLCAN 或 gs_usb 后端。

安装

在解包根目录执行。使用原生架构的 Python 3.10+：Apple Silicon 使用 arm64，Intel 使用 x86_64，Python 与所装库保持同一架构。

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/zeroerr.py --help

只用 EtherCAT 可替换成 -r ethercat/requirements.txt。如 pip 报编译工具缺失，安装 Xcode Command Line Tools（xcode-select --install），再安装依赖。依赖安装在普通用户虚拟环境中。

EtherCAT：一次启动服务，后续普通用户操作

先查看接口并自动探测：

.venv/bin/python scripts/zeroerr.py ethercat adapters
.venv/bin/python scripts/zeroerr.py detect

发现结果只有一个设备时，使用 selected 中的网卡名和从站号；多个候选时先选设备。若提示 BPF 权限不足，在用户终端执行以下命令，en5 替换为实际有线网口。sudo 密码由用户在终端输入，不交给 Agent。

sudo "$(pwd)/.venv/bin/python" scripts/zeroerr.py ethercat --interface en5 discover
sudo "$(pwd)/.venv/bin/python" scripts/zeroerr.py ethercat --interface en5 --slave 1 connect

connect 启动后台持续 PDO 服务，返回后服务继续运行。下列命令使用普通用户，复用相同网口/从站和默认本机端口 8792：

.venv/bin/python scripts/zeroerr.py ethercat --interface en5 --slave 1 status
.venv/bin/python examples/basic_ethercat.py --interface en5 --slave 1
.venv/bin/python scripts/zeroerr.py ethercat --interface en5 --slave 1 state read Pos SpdActual ErrorCode

按用户指定的速度、加减速度和结束动作执行工况。例如下方命令明确选择采集结束停止：

.venv/bin/python scripts/zeroerr.py ethercat --interface en5 --slave 1 motion velocity --speed 10000 --accel 250000 --decel 250000
.venv/bin/python scripts/zeroerr.py ethercat --interface en5 --slave 1 capture --seconds 5 --output output/run.csv --after stop
.venv/bin/python scripts/zeroerr.py ethercat --interface en5 --slave 1 close

--after preserve 用于用户明确要求采集后保持当前目标的工况；两种结束动作均需显式选择。close 失能并关闭服务，下次连接重新取得 BPF 权限。--port 可指定其它本机端口，后续命令都使用同一端口；自动 detect 复用默认端口 8792。

服务只监听本机 127.0.0.1，由本机客户端控制。它不是有身份认证的多用户或远程控制服务；使用专用操作账户，不向网络转发该端口。避免同时启动第二个 EtherCAT 主站。连接保持期间，原始网口权限由服务持有，而非每个客户端重新打开。

CANopen：明确适配器后端

SLCAN 示例（波特率按实际设备填写）：

.venv/bin/python scripts/zeroerr.py canopen adapters
.venv/bin/python scripts/zeroerr.py canopen --interface slcan --channel /dev/cu.usbmodemXXXX --serial-baud 115200 --bitrate 1000000 discover
.venv/bin/python scripts/zeroerr.py canopen --interface slcan --channel /dev/cu.usbmodemXXXX --serial-baud 115200 --bitrate 1000000 --can-id 3 state read ProductCode Statusword Pos

--serial-baud 是电脑到适配器的串口速率，--bitrate 是 CAN 总线速率，两者不同。自动探测默认分别为 115200 与 1000000；设备采用其它值时，使用上面的协议入口显式指定。串口候选可能是传感器，只有确认是 SLCAN 适配器后才打开。

gs_usb 示例（已经安装 Homebrew 时可用它安装 libusb）：

brew install libusb
.venv/bin/python -m pip install -r canopen/requirements-gs-usb.txt
.venv/bin/python scripts/zeroerr.py detect --can-interface gs_usb --can-channel 0
.venv/bin/python scripts/zeroerr.py canopen --interface gs_usb --channel 0 --can-id 3 state read ProductCode Statusword Pos

Node ID 使用实际发现值，默认扫描 1–64。设备存在但无响应时检查总线速率、CAN_H/CAN_L、终端电阻、供电和适配器占用，依据返回错误处理。

区分权限来源

提示对应处理
BPF / 原始网口 permission denied同一个虚拟环境 Python 通过 sudo 执行首次 discover / connect；后续复用服务。Mac 不安装 Npcap。
sudo 后找不到 pysoem使用上面的虚拟环境 Python 绝对路径，避免切换到系统 Python。
桌面、下载、文稿目录访问提示在系统设置 → 隐私与安全性 → 文件与文件夹，给实际运行命令的终端或宿主应用授予所需目录权限；这是系统目录授权。Apple 说明。
每条命令被 Agent 宿主询问确认由宿主应用的执行审批设置管理，与 BPF 权限分开。本包不添加逐命令审批界面。
CSV 可读但普通用户不能原地修改CSV 由服务进程写出；通过 sudo 启动的服务可能生成 root 所有的文件。读取后把分析结果输出到用户可写目录。

本包不安装开机提权服务、不修改 sudoers 或系统权限策略。使用用户已授权的工作目录，保持解包目录、虚拟环境和输出路径稳定即可。

网口、OP/PDO、同步与驱动故障排查见 EtherCAT 通讯参考；依赖和模块协议资料来源见 SOURCES.md。