Installation

Requirements

System Requirements

Operating System: Linux / Windows / macOS
Python: 3.10, 3.11, 3.12, 3.13, or 3.14
Hardware: CAN interface (SocketCAN, PCAN) or serial adapter

Python Dependencies

The package automatically installs required dependencies:

ctypes (standard library)
dataclasses (standard library)

Install from PyPI

The recommended installation method:

python3 -m pip install motorbridge

Install Specific Version

python3 -m pip install motorbridge==0.5.0

Upgrade Existing Installation

python3 -m pip install --upgrade motorbridge

Verify Installation

Quick Test

python3 -c "import motorbridge; print('motorbridge installed successfully')"

Check Version

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

Test CLI

motorbridge-cli --help

Expected output:

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
...

Test Gateway Command

motorbridge wheel also installs a standalone gateway launcher:

motorbridge-gateway --help

-- is optional: motorbridge-gateway -- --help and motorbridge-gateway --help are equivalent.

WS Gateway Quick Start (3 Platforms)

Use motorbridge-gateway (the Python launcher for ws_gateway) directly after pip install.

A) Damiao serial bridge (`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 path (`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

Notes:

dm-serial is Damiao-only.
For CAN path: Linux needs SocketCAN interface up (ip link set can0 up), Windows needs PEAK PCAN driver + PCANBasic.dll, macOS needs PCBUSB runtime.
CLI/Gateway now print platform-specific dependency hints before startup.
Keep default bind 127.0.0.1 for local usage. If exposing non-loopback addresses, set MOTORBRIDGE_WS_TOKEN and send it via x-motorbridge-token or Authorization: Bearer ....

macOS only (if dynamic library load fails):

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

Pre-release Versions (TestPyPI)

For testing bleeding-edge features before official release:

# Install latest pre-release from TestPyPI (no version pin)
python3 -m pip install --pre -i https://test.pypi.org/simple/ motorbridge

# Or install a specific pre-release version
python3 -m pip install -i https://test.pypi.org/simple/ motorbridge==0.5.0a1

Pre-release versions may be unstable. Do not use in production.

Development Installation

From Source (Git)

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

# Install in editable mode
pip install -e .

Set Library Path (Source Builds Only)

If building from source without a packaged wheel:

# Set Python path to source directory
export PYTHONPATH=/path/to/motorbridge/bindings/python/src

# Set library path for ABI shared object
export LD_LIBRARY_PATH=/path/to/motorbridge/target/release:${LD_LIBRARY_PATH}

Source builds require the Rust toolchain and compiling the libmotor_abi.so library first with cargo build -p motor_abi --release.

Virtual Environment (Recommended)

Isolate your installation using a virtual environment:

# Create virtual environment
python3 -m venv ~/venv/motorbridge

# Activate
source ~/venv/motorbridge/bin/activate

# Install
pip install motorbridge

# Deactivate when done
deactivate

System CAN Setup

Before using the SDK, ensure your CAN interface is configured:

Linux (SocketCAN) software checks and bring-up

# Check whether CAN interface exists
ip link show can0

# Load CAN kernel modules
sudo modprobe can
sudo modprobe can_raw
sudo modprobe can_dev

# If interface is missing, configure CAN interface (example: 1M bitrate)
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up

# Increase TX queue length
sudo ifconfig can0 txqueuelen 1000

Windows (PCAN) software checks and bring-up

Recommended PowerShell (Admin) flow:

# Verify package and CLI
python -c "import motorbridge; print('motorbridge OK')"
motorbridge-cli --help

# Optional: verify PCANBasic.dll loadability
python -c "import ctypes; ctypes.CDLL('PCANBasic.dll'); print('PCANBasic load OK')"

# Run a scan check (can0@1000000 maps to PCAN_USBBUS1)
motorbridge-cli scan --vendor damiao --transport auto --channel can0@1000000 --start-id 1 --end-id 16

macOS (PCBUSB) software checks and bring-up

# Verify package and CLI
python3 -c "import motorbridge; print('motorbridge OK')"
motorbridge-cli --help

# Optional: verify PCBUSB runtime loadability
python3 -c "import ctypes; ctypes.CDLL('libPCBUSB.dylib'); print('PCBUSB load OK')"

# Run a scan check (CAN path)
motorbridge-cli scan --vendor damiao --transport auto --channel can0 --start-id 1 --end-id 16

macOS (PCBUSB) driver/runtime install (if missing)

If libPCBUSB.dylib cannot be loaded, install PCBUSB first. System-wide install:

curl -L -o macOS_Library_for_PCANUSB_v0.13.tar.gz \
  https://raw.githubusercontent.com/motorbridge/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

User-local fallback:

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:-}"

Serial Port Permissions (Linux, dm-serial)

For DM serial bridge transport:

# Add user to dialout group for serial port access
sudo usermod -a -G dialout $USER

# Log out and back in for changes to take effect

Troubleshooting Installation

ImportError: cannot import name ‘Controller’

The ABI library cannot be found. Ensure:

You installed from a wheel (not just copying source)
libmotor_abi.so is in the package directory or LD_LIBRARY_PATH

Permission Denied on /dev/ttyACM0

# Check serial port permissions
ls -la /dev/ttyACM0

# Add user to dialout group
sudo usermod -a -G dialout $USER
# Log out and back in

CAN Interface Not Found

# Check if CAN interface exists
ip link show can0

# If not, load modules and configure
sudo modprobe can_raw
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up

Windows PCAN runtime missing

If you see PCANBasic.dll missing:

Install PEAK driver + PCAN-Basic runtime.
Reopen terminal/IDE and retry.
Prefer channels like can0@1000000 or can1@1000000.

macOS PCBUSB runtime missing

If you see libPCBUSB.dylib missing:

Install PCBUSB runtime first.
Ensure libPCBUSB.dylib is in a searchable path (for example /usr/local/lib).
Reopen terminal and retry.

Next Steps

Transports - Configure your communication layer
Quickstart - Run your first motor control program

​Installation

​Requirements

​System Requirements

​Python Dependencies

​Install from PyPI

​Install Specific Version

​Upgrade Existing Installation

​Verify Installation

​Quick Test

​Check Version

​Test CLI

​Test Gateway Command

​WS Gateway Quick Start (3 Platforms)

​A) Damiao serial bridge (dm-serial)

​B) CAN path (auto/socketcan/pcan)

​Pre-release Versions (TestPyPI)

​Development Installation

​From Source (Git)

​Set Library Path (Source Builds Only)

​Virtual Environment (Recommended)

​System CAN Setup

​Linux (SocketCAN) software checks and bring-up

​Windows (PCAN) software checks and bring-up

​macOS (PCBUSB) software checks and bring-up

​macOS (PCBUSB) driver/runtime install (if missing)

​Serial Port Permissions (Linux, dm-serial)

​Troubleshooting Installation

​ImportError: cannot import name ‘Controller’

​Permission Denied on /dev/ttyACM0

​CAN Interface Not Found

​Windows PCAN runtime missing

​macOS PCBUSB runtime missing

​Next Steps

Installation

Requirements

System Requirements

Python Dependencies

Install from PyPI

Install Specific Version

Upgrade Existing Installation

Verify Installation

Quick Test

Check Version

Test CLI

Test Gateway Command

WS Gateway Quick Start (3 Platforms)

A) Damiao serial bridge (`dm-serial`)

B) CAN path (`auto/socketcan/pcan`)

Pre-release Versions (TestPyPI)

Development Installation

From Source (Git)

Set Library Path (Source Builds Only)

Virtual Environment (Recommended)

System CAN Setup

Linux (SocketCAN) software checks and bring-up

Windows (PCAN) software checks and bring-up

macOS (PCBUSB) software checks and bring-up

macOS (PCBUSB) driver/runtime install (if missing)

Serial Port Permissions (Linux, dm-serial)

Troubleshooting Installation

ImportError: cannot import name ‘Controller’

Permission Denied on /dev/ttyACM0

CAN Interface Not Found

Windows PCAN runtime missing

macOS PCBUSB runtime missing

Next Steps