安装与环境

系统要求

硬件要求

操作系统：Linux / Windows / macOS
Python：3.10、3.11、3.12、3.13 或 3.14
硬件：CAN 接口（SocketCAN、PCAN）或串口适配器

Python 依赖

包会自动安装所需依赖：

ctypes（标准库）
dataclasses（标准库）

从 PyPI 安装

推荐安装方式：

python3 -m pip install motorbridge

安装特定版本

python3 -m pip install motorbridge==0.3.3

升级现有安装

python3 -m pip install --upgrade motorbridge

验证安装

快速测试

python3 -c "import motorbridge; print('motorbridge 安装成功')"

检查版本

python3 -c "import importlib.metadata; print(importlib.metadata.version('motorbridge'))"
python3 -c "import motorbridge; print(motorbridge.get_version())"
motorbridge-cli -v

测试 CLI

motorbridge-cli --help

预期输出：

usage: motorbridge-cli [-h] [-v] {run,id-dump,id-set,scan,robstride-read-param,robstride-write-param,damiao-read-param,damiao-write-param} ...

motorbridge Python SDK CLI
...

测试网关命令

motorbridge wheel 还会安装独立网关启动器：

motorbridge-gateway --help

-- 是可选的：motorbridge-gateway -- --help 与 motorbridge-gateway --help 等价。

WS Gateway 启动（三平台）

下面命令均使用 Python 包内置网关命令 motorbridge-gateway（即 ws_gateway 启动器）。

A) Damiao 串口桥（dm-serial）

Ubuntu:

motorbridge-gateway \
  --bind 127.0.0.1:9002 \
  --vendor damiao --transport dm-serial \
  --serial-port /dev/ttyACM0 --serial-baud 921600 \
  --model auto --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

macOS:

motorbridge-gateway \
  --bind 127.0.0.1:9002 \
  --vendor damiao --transport dm-serial \
  --serial-port /dev/cu.usbmodemXXXX --serial-baud 921600 \
  --model auto --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

Windows (PowerShell):

motorbridge-gateway `
  --bind 127.0.0.1:9002 `
  --vendor damiao --transport dm-serial `
  --serial-port COM3 --serial-baud 921600 `
  --model auto --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

B) CAN 路径（auto/socketcan/pcan）

Ubuntu (SocketCAN):

motorbridge-gateway \
  --bind 127.0.0.1:9002 \
  --vendor damiao --transport auto \
  --channel can0 \
  --model auto --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

macOS (PCBUSB runtime):

motorbridge-gateway \
  --bind 127.0.0.1:9002 \
  --vendor damiao --transport auto \
  --channel can0 \
  --model auto --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

Windows (PCAN backend):

motorbridge-gateway `
  --bind 127.0.0.1:9002 `
  --vendor damiao --transport auto `
  --channel can0@1000000 `
  --model auto --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

提示：

dm-serial 仅用于 Damiao。
CAN 路径下，Linux 需先 ip link set can0 up；Windows 需安装 PCAN 驱动/PCANBasic.dll；macOS 需安装 PCBUSB 运行时。
CLI 与 Gateway 现已在启动前给出平台依赖提示。
本地建议保持 127.0.0.1。如需绑定非回环地址，必须设置 MOTORBRIDGE_WS_TOKEN，并在客户端握手中携带（x-motorbridge-token 或 Authorization: Bearer ...）。

仅 macOS（如果出现动态库加载失败）可使用：

GW="$(python3 -c "import motorbridge, pathlib; print(pathlib.Path(motorbridge.__file__).resolve().parent/'bin'/'ws_gateway')")"
PKG_DIR="$(python3 -c "import motorbridge, pathlib; print(pathlib.Path(motorbridge.__file__).resolve().parent)")"
DYLD_LIBRARY_PATH="$PKG_DIR/lib:${DYLD_LIBRARY_PATH:-}" "$GW" --bind 127.0.0.1:9002 --vendor damiao --channel can0 --model auto --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

预发布版本（TestPyPI）

测试正式发布前的最新功能：

# 从 TestPyPI 安装最新预发布版本（不指定版本号）
python3 -m pip install --pre -i https://test.pypi.org/simple/ motorbridge

# 或安装指定预发布版本
python3 -m pip install -i https://test.pypi.org/simple/ motorbridge==0.3.3a1

预发布版本可能不稳定。请勿在生产环境中使用。

开发环境安装

从源码安装（Git）

git clone https://github.com/tianrking/motorbridge
cd motorbridge
cargo build -p motor_abi --release
cd bindings/python

# 以可编辑模式安装
pip install -e .

设置库路径（仅源码构建）

如果从源码构建而不使用打包的 wheel：

# 设置 Python 路径到源码目录
export PYTHONPATH=/path/to/motorbridge/bindings/python/src

# 设置 ABI 共享对象的库路径
export LD_LIBRARY_PATH=/path/to/motorbridge/target/release:${LD_LIBRARY_PATH}

源码构建需要 Rust 工具链，并先用 cargo build -p motor_abi --release 编译 libmotor_abi.so。

虚拟环境（推荐）

使用虚拟环境隔离安装：

# 创建虚拟环境
python3 -m venv ~/venv/motorbridge

# 激活
source ~/venv/motorbridge/bin/activate

# 安装
pip install motorbridge

# 完成后停用
deactivate

系统 CAN 配置

使用 SDK 前，确保 CAN 接口已配置：

Linux（SocketCAN）软件检查与初始化

# 检查 CAN 接口是否存在
ip link show can0

# 加载 CAN 内核模块
sudo modprobe can
sudo modprobe can_raw
sudo modprobe can_dev

# 如果不存在，配置 CAN 接口（示例：1M 波特率）
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up

# 增加 TX 队列长度（防止缓冲区溢出）
sudo ifconfig can0 txqueuelen 1000

Windows（PCAN）软件检查与初始化

PowerShell（管理员）建议流程：

# 检查 Python 包和 CLI 是否就绪
python -c "import motorbridge; print('motorbridge OK')"
motorbridge-cli --help

# 可选：检查 PCANBasic.dll 是否可加载（需已安装 PEAK 驱动与 PCAN-Basic）
python -c "import ctypes; ctypes.CDLL('PCANBasic.dll'); print('PCANBasic load OK')"

# 运行一次扫描验证（can0@1000000 映射 PCAN_USBBUS1）
motorbridge-cli scan --vendor damiao --transport auto --channel can0@1000000 --start-id 1 --end-id 16

macOS（PCBUSB）软件检查与初始化

# 检查 Python 包和 CLI 是否就绪
python3 -c "import motorbridge; print('motorbridge OK')"
motorbridge-cli --help

# 可选：检查 PCBUSB 运行时是否可加载
python3 -c "import ctypes; ctypes.CDLL('libPCBUSB.dylib'); print('PCBUSB load OK')"

# 运行一次扫描验证（CAN 路径）
motorbridge-cli scan --vendor damiao --transport auto --channel can0 --start-id 1 --end-id 16

macOS（PCBUSB）驱动/运行时安装（缺失时）

如果提示 libPCBUSB.dylib 无法加载，请先安装 PCBUSB。系统级安装：

curl -L -o macOS_Library_for_PCANUSB_v0.13.tar.gz \
  https://raw.githubusercontent.com/tianrking/motorbridge/main/third_party/pcan/macos/macOS_Library_for_PCANUSB_v0.13.tar.gz
tar -xzf macOS_Library_for_PCANUSB_v0.13.tar.gz
cd PCBUSB
sudo ./install.sh

用户目录兜底安装：

mkdir -p ~/.local/lib ~/.local/include
cp PCBUSB/libPCBUSB.0.13.dylib ~/.local/lib/
ln -sf ~/.local/lib/libPCBUSB.0.13.dylib ~/.local/lib/libPCBUSB.dylib
cp PCBUSB/PCBUSB.h ~/.local/include/
export DYLD_LIBRARY_PATH="$HOME/.local/lib:${DYLD_LIBRARY_PATH:-}"

串口权限（Linux，dm-serial）

对于 DM 串口桥传输：

# 将用户添加到 dialout 组以获取串口访问权限
sudo usermod -a -G dialout $USER

# 注销并重新登录以使更改生效

安装故障排除

ImportError: cannot import name ‘Controller’

ABI 库无法找到。确保：

从 wheel 安装（不仅仅是复制源码）
libmotor_abi.so 在包目录或 LD_LIBRARY_PATH 中

/dev/ttyACM0 权限被拒绝

# 检查串口权限
ls -la /dev/ttyACM0

# 将用户添加到 dialout 组
sudo usermod -a -G dialout $USER
# 注销并重新登录

CAN 接口未找到

# 检查 CAN 接口是否存在
ip link show can0

# 如果不存在，加载模块并配置
sudo modprobe can_raw
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up

Windows PCAN 运行时缺失

如果提示 PCANBasic.dll 缺失：

安装 PEAK 驱动与 PCAN-Basic 运行时。
重新打开终端/IDE 后重试。
通道建议使用 can0@1000000 或 can1@1000000。

macOS PCBUSB 运行时缺失

如果提示 libPCBUSB.dylib 缺失：

先安装 PCBUSB 运行时。
确认 libPCBUSB.dylib 在系统可搜索路径中（如 /usr/local/lib）。
重新打开终端后重试。

下一步

传输方式 - 配置通信层
快速开始 - 运行第一个电机控制程序

快速开始

教程

接口手册

最佳实践

参考

源码：仓库

源码：项目文档

源码：Python Binding

源码：C++ Binding

源码：Rust CLI

源码：示例

源码：集成

源码：工具与厂商

Documentation Index

​安装与环境

​系统要求

​硬件要求

​Python 依赖

​从 PyPI 安装

​安装特定版本

​升级现有安装

​验证安装

​快速测试

​检查版本

​测试 CLI

​测试网关命令

​WS Gateway 启动（三平台）

​A) Damiao 串口桥（dm-serial）

​B) CAN 路径（auto/socketcan/pcan）

​预发布版本（TestPyPI）

​开发环境安装

​从源码安装（Git）

​设置库路径（仅源码构建）

​虚拟环境（推荐）

​系统 CAN 配置

​Linux（SocketCAN）软件检查与初始化

​Windows（PCAN）软件检查与初始化

​macOS（PCBUSB）软件检查与初始化

​macOS（PCBUSB）驱动/运行时安装（缺失时）

​串口权限（Linux，dm-serial）

​安装故障排除

​ImportError: cannot import name ‘Controller’

​/dev/ttyACM0 权限被拒绝

​CAN 接口未找到

​Windows PCAN 运行时缺失

​macOS PCBUSB 运行时缺失

​下一步

安装与环境

系统要求

硬件要求

Python 依赖

从 PyPI 安装

安装特定版本

升级现有安装

验证安装

快速测试

检查版本

测试 CLI

测试网关命令

WS Gateway 启动（三平台）

A) Damiao 串口桥（dm-serial）

B) CAN 路径（auto/socketcan/pcan）

预发布版本（TestPyPI）

开发环境安装

从源码安装（Git）

设置库路径（仅源码构建）

虚拟环境（推荐）

系统 CAN 配置

Linux（SocketCAN）软件检查与初始化

Windows（PCAN）软件检查与初始化

macOS（PCBUSB）软件检查与初始化

macOS（PCBUSB）驱动/运行时安装（缺失时）

串口权限（Linux，dm-serial）

安装故障排除

ImportError: cannot import name ‘Controller’

/dev/ttyACM0 权限被拒绝

CAN 接口未找到

Windows PCAN 运行时缺失

macOS PCBUSB 运行时缺失

下一步