Repository Overview

Chinese version: README.zh-CN.md

​

Companion Repos

• motorbridge-studio: https://github.com/tianrking/motorbridge-studio Standalone web control UI built on top of ws_gateway.

​

Transport Legend

• [STD-CAN]: classic CAN path (socketcan/pcan)
• [CAN-FD]: dedicated FD path (socketcanfd)
• [DM-SERIAL]: Damiao serial-bridge path (dm-serial)

• [CAN-FD] has been integrated as an independent transport path.
• No motor model is officially marked as CAN-FD validated in this repository yet.

​

Current Vendor Support

• Damiao:
  • models: 3507, 4310, 4310P, 4340, 4340P, 6006, 8006, 8009, 10010L, 10010, H3510, G6215, H6220, JH11, 6248P
  • modes: scan, enable, disable, MIT, POS_VEL, VEL, FORCE_POS, set-id, set-zero
• RobStride:
  • models: rs-00, rs-01, rs-02, rs-03, rs-04, rs-05, rs-06
  • modes: scan, ping, enable, disable, MIT, POS_VEL, VEL, parameter read/write, set-id, zero
  • host/feedback default: 0xFD (with 0xFF/0xFE fallback probing)
  • model selection is required for real hardware use: use the actual rs-00..rs-06 model for limits/logging; parameter read/write uses the common RobStride section 4 runtime table
  • note: torque/current control is currently parameter-level only (write-param on iq_ref/limits), not a first-class unified mode
• MyActuator:
  • models: X8 (runtime string; protocol is ID-based)
  • modes: scan, enable, disable, stop, set-zero, status, current, vel, pos, version, mode-query
• HighTorque:
  • models: hightorque (runtime string; native ht_can v1.5.5)
  • modes: scan, read, mit, pos-vel, vel, stop, brake, rezero
• Hexfellow:
  • models: hexfellow (runtime string; CANopen profile)
  • modes: scan, status, enable, disable, pos-vel, mit (via socketcanfd)

​

Update (2026-04): Damiao / RobStride Capability Convergence

• Damiao production baseline now covers: scan / enable / disable / MIT / POS_VEL / VEL / FORCE_POS / set-id / set-zero.
• RobStride production baseline now covers: scan / ping / enable / disable / MIT / POS_VEL / VEL / parameter read-write / set-id / zero.
• RobStride RS00-RS06 keep the same unified control command shape. Runtime parameter read/write uses the common section 4 table (0x7005..0x702E); --model remains the physical model hint for limits/logging.
• RobStride default host/feedback path is 0xFD; scan now tries 0xFD,0xFF,0xFE,0x00,0xAA by default.
• RobStride feedback_id / host_id is host-side addressing, not the motor device_id; scan hits report the motor ID as probe / device_id.
• In RobStride pos-vel, --vel/--kd/--tau are intentionally ignored and reported as warnings (no hard error).

​

Architecture

​

Layered Runtime View

​

Workspace Topology (Latest)

​

Python Binding Surface (v0.1.7+)

• motor_core: vendor-agnostic controller, routing, CAN bus layer (Linux SocketCAN / Windows experimental PCAN)
• motor_vendors/damiao: Damiao protocol / models / registers
• motor_vendors/hexfellow: Hexfellow CANopen-over-CAN-FD implementation
• motor_vendors/hightorque: HighTorque native ht_can protocol implementation
• motor_vendors/robstride: RobStride extended CAN protocol / models / parameters
• motor_vendors/myactuator: MyActuator CAN protocol implementation
• motor_cli: unified Rust CLI
  • full parameters (English): motor_cli/README.md
  • full parameters (Chinese): motor_cli/README.zh-CN.md
  • Damiao command/register guide: motor_cli/DAMIAO_API.md, motor_cli/DAMIAO_API.zh-CN.md
  • RobStride command/parameter guide: motor_cli/ROBSTRIDE_API.md, motor_cli/ROBSTRIDE_API.zh-CN.md
  • MyActuator command/mode guide: motor_cli/MYACTUATOR_API.md, motor_cli/MYACTUATOR_API.zh-CN.md
• motor_abi: stable C ABI
• bindings/python: Python SDK + motorbridge-cli
• bindings/cpp: C++ RAII wrapper
• motorbridge-studio: standalone web control UI repository (split out of tools/factory_calib_ui_ws)

​

Quick Start

cargo build

sudo ip link set can0 down 2>/dev/null || true
sudo ip link set can0 type can bitrate 1000000 restart-ms 100
sudo ip link set can0 up
ip -details link show can0

# default: can0 / 1Mbps / restart-ms=100 / loopback off
IF=can0; BITRATE=1000000; RESTART_MS=100; LOOPBACK=off
sudo ip link set "$IF" down 2>/dev/null || true
if [ "$LOOPBACK" = "on" ]; then
  sudo ip link set "$IF" type can bitrate "$BITRATE" restart-ms "$RESTART_MS" loopback on
else
  sudo ip link set "$IF" type can bitrate "$BITRATE" restart-ms "$RESTART_MS" loopback off
fi
sudo ip link set "$IF" up
ip -details link show "$IF"

cargo run -p motor_cli --release -- \
  --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --mode mit --pos 0 --vel 0 --kp 20 --kd 1 --tau 0 --loop 50 --dt-ms 20

cargo run -p motor_cli --release -- \
  --vendor hexfellow --transport socketcanfd --channel can0 \
  --model hexfellow --motor-id 1 --feedback-id 0 \
  --mode status

cargo run -p motor_cli --release -- \
  --vendor robstride --channel can0 --model rs-06 --motor-id 127 \
  --mode vel --vel 0.3 --loop 40 --dt-ms 50

cargo run -p motor_cli --release -- \
  --vendor hightorque --channel can0 --model hightorque --motor-id 1 \
  --mode read

cargo run -p motor_cli --release -- \
  --vendor robstride --channel can0 --model rs-06 --motor-id 127 \
  --mode read-param --param-id 0x7019

cargo run -p motor_cli --release -- \
  --vendor myactuator --channel can0 --model X8 --motor-id 1 --feedback-id 0x241 \
  --mode status --loop 20 --dt-ms 50

cargo run -p motor_cli --release -- \
  --vendor all --channel can0 --mode scan --start-id 1 --end-id 255

cargo run -p motor_cli --release -- \
  scan --vendor robstride --channel can0 --start-id 1 --end-id 127 \
  --feedback-ids 0xFD,0xFF,0xFE,0x00,0xAA

motorbridge-cli scan \
  --vendor robstride --channel can0 --start-id 1 --end-id 127 \
  --feedback-ids 0xFD,0xFF,0xFE,0x00,0xAA

​

Experimental Windows Support (PCAN-USB)

• Install PEAK PCAN driver + PCAN-Basic runtime on Windows.
• Channel mapping:
  • can0 -> PCAN_USBBUS1
  • can1 -> PCAN_USBBUS2
• Optional bitrate suffix: @<bitrate> (for example can0@1000000).

# Scan Damiao IDs
cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4340P --motor-id 0x01 --feedback-id 0x11 --mode scan --start-id 1 --end-id 16

# Move motor #1 (4340P) to +pi rad (~180 deg)
cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4340P --motor-id 0x01 --feedback-id 0x11 --mode pos-vel --pos 3.1416 --vlim 2.0 --loop 1 --dt-ms 20

# Move motor #7 (4310) to +pi rad (~180 deg)
cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4310 --motor-id 0x07 --feedback-id 0x17 --mode pos-vel --pos 3.1416 --vlim 2.0 --loop 1 --dt-ms 20

​

macOS PCAN Runtime (PCBUSB)

​

1. Prerequisites

• A PEAK-compatible USB-CAN adapter recognized by macOS.
• motorbridge source built on macOS.
• Bundled archive in this repo: third_party/pcan/macos/macOS_Library_for_PCANUSB_v0.13.tar.gz.
• Or download directly from GitHub:
  • https://github.com/tianrking/motorbridge/blob/main/third_party/pcan/macos/macOS_Library_for_PCANUSB_v0.13.tar.gz

​

2. Quick install from bundled archive (recommended)

# user-local install (no sudo, recommended)
./scripts/setup_pcbusb_macos.sh --user-local

# system install (uses package install.sh, requires sudo)
./scripts/setup_pcbusb_macos.sh --system

DYLD_LIBRARY_PATH=$HOME/.local/lib ./target/release/motor_cli ...

​

3. Manual install PCBUSB (system-wide)

mkdir -p /tmp/motorbridge-pcan && cd /tmp/motorbridge-pcan
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

• libPCBUSB.dylib into /usr/local/lib
• PCBUSB.h into /usr/local/include

​

4. Optional user-local install (no sudo)

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/

DYLD_LIBRARY_PATH=$HOME/.local/lib ./target/release/motor_cli ...

​

5. Verify runtime loading

python3 - <<'PY'
from can.interfaces.pcan.basic import PCANBasic
PCANBasic()
print("PCBUSB load OK")
PY

DYLD_LIBRARY_PATH=$HOME/.local/lib python3 - <<'PY'
from can.interfaces.pcan.basic import PCANBasic
PCANBasic()
print("PCBUSB load OK")
PY

​

6. Build motorbridge CLI

cargo build -p motor_cli --release

​

7. Channel mapping on macOS (PCAN backend)

• can0 maps to PCAN_USBBUS1
• can1 maps to PCAN_USBBUS2
• Optional bitrate suffix is supported (example: can0@1000000)

​

8. Scan motors (Damiao)

./target/release/motor_cli \
  --vendor damiao --channel can0 --mode scan --start-id 1 --end-id 16

DYLD_LIBRARY_PATH=$HOME/.local/lib ./target/release/motor_cli \
  --vendor damiao --channel can0 --mode scan --start-id 1 --end-id 16

​

9. Control example (Damiao MIT)

./target/release/motor_cli \
  --vendor damiao --channel can0 --model 4310 \
  --motor-id 0x02 --feedback-id 0x12 \
  --mode mit --pos 0 --vel 0 --kp 20 --kd 1 --tau 0 \
  --loop 50 --dt-ms 20

​

10. Troubleshooting

• load PCBUSB failed ...:
  • Install PCBUSB with install.sh, or export DYLD_LIBRARY_PATH for local install.
• No CAN backend for current platform:
  • Use a build that includes the macOS PCAN backend.
• hits=0 on scan:
  • Check wiring, power, termination resistor, and CAN bitrate.

​

Linux USB-CAN (slcan) Quick Guide

sudo slcand -o -c -s8 /dev/ttyUSB0 slcan0
sudo ip link set slcan0 up
ip -details link show slcan0

cargo run -p motor_cli --release -- --vendor damiao --channel slcan0 --mode scan --start-id 1 --end-id 255

​

Damiao Dedicated CAN-FD Transport (socketcanfd)

# Bring up CAN-FD interface first
scripts/canfd_restart.sh can0

# Damiao over dedicated socketcanfd transport
cargo run -p motor_cli --release -- --vendor damiao \
  --transport socketcanfd --channel can0 \
  --model 4310 --motor-id 0x04 --feedback-id 0x14 \
  --mode mit --verify-model 0 --ensure-mode 0 \
  --pos 0.5 --vel 0 --kp 20 --kd 1 --tau 0 --loop 80 --dt-ms 20

​

Damiao Serial Bridge Quick Guide (dm-serial)

# Damiao scan over serial bridge
cargo run -p motor_cli --release -- --vendor damiao \
  --transport dm-serial --serial-port /dev/ttyACM1 --serial-baud 921600 \
  --model 4310 --mode scan --start-id 1 --end-id 16

# Damiao MIT over serial bridge
cargo run -p motor_cli --release -- --vendor damiao \
  --transport dm-serial --serial-port /dev/ttyACM1 --serial-baud 921600 \
  --model 4310 --motor-id 0x04 --feedback-id 0x14 \
  --mode mit --verify-model 0 --ensure-mode 0 \
  --pos 0.5 --vel 0 --kp 20 --kd 1 --tau 0 --loop 80 --dt-ms 20

​

CAN Debugging (Professional Playbook)

• docs/en/can_debugging.md
• docs/zh/can_debugging.md

• vendor=damiao id=<n> means one Damiao motor is online at motor ID <n>.
• vendor=robstride ... probe=<n> ... device_id=<n> means one RobStride motor responded at motor/device ID <n>.
• In RobStride output, feedback_id / host_id such as 0xFD or 0xFE is not the motor ID.
• vendor=hightorque ... [hit] id=<n> ... means one HighTorque motor responded via native ht_can v1.5.5.
• vendor=myactuator id=<n> means one MyActuator motor responded.
• hits=<k> at the end of each scan block is the count of discovered devices.

​

ABI and Bindings

• C ABI:
  • motor_controller_new_socketcan(channel)
  • motor_controller_new_dm_serial(serial_port, baud) (Damiao-only serial bridge; cross-platform, e.g. /dev/ttyACM0 or COM3)
  • Damiao: motor_controller_add_damiao_motor(...)
  • Hexfellow: motor_controller_add_hexfellow_motor(...) (CAN-FD path via socketcanfd)
  • RobStride: motor_controller_add_robstride_motor(...)
  • MyActuator: motor_controller_add_myactuator_motor(...)
  • HighTorque: motor_controller_add_hightorque_motor(...)
• Python:
  • Controller(channel="can0")
  • Controller.from_dm_serial("/dev/ttyACM0", 921600) (Damiao-only)
  • Controller.add_damiao_motor(...)
  • Controller.add_hexfellow_motor(...)
  • Controller.add_robstride_motor(...)
  • Controller.add_myactuator_motor(...)
  • Controller.add_hightorque_motor(...)
• C++:
  • Controller("can0")
  • Controller::from_dm_serial("/dev/ttyACM0", 921600) (Damiao-only)
  • Controller::add_damiao_motor(...)
  • Controller::add_hexfellow_motor(...)
  • Controller::add_robstride_motor(...)
  • Controller::add_myactuator_motor(...)
  • Controller::add_hightorque_motor(...)

• 1 = MIT
• 2 = POS_VEL
• 3 = VEL
• 4 = FORCE_POS

• position: rad
• velocity: rad/s
• torque: Nm

• docs/en/abi.md
• docs/zh/abi.md

• robstride_ping
• robstride_set_device_id
• robstride_get_param_*
• robstride_write_param_*

​

Example Entry Points

• Cross-language index: examples/README.md
• C ABI demo: examples/c/c_abi_demo.c
• C++ ABI demo: examples/cpp/cpp_abi_demo.cpp
• Python ctypes demo: examples/python/python_ctypes_demo.py
• Python SDK docs: bindings/python/README.md
• C++ binding docs: bindings/cpp/README.md

​

Release and Package Matrix

​

A) GitHub Releases (binary assets)

​

B) PyPI / TestPyPI (Python package channel)

pip install motorbridge

pip install --no-binary motorbridge motorbridge

​

C) Functional Scope by Distribution Type

​

D) Additional Automated Distribution Channel

• .deb is currently Linux x86_64 oriented; other Linux targets should use ABI .tar.gz.
• macOS x86_64 wheels are intentionally not produced in current matrix.
• Device matrix reference: docs/en/devices.md.
• Distribution channel automation guide: docs/en/distribution_channels.md.