MotorBridge

https://motorbridge.seeedstudio.com/
Admin
MotorBridge is a unified motor control stack with pluggable vendor drivers and a C ABI for...
Tokens:150,776
Snippets:1,663
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### CLI Quick Reference

Source: https://motorbridge.seeedstudio.com/quickstart

Use the CLI for quick testing after installation. Examples include scanning for motors, running a motor in MIT mode, and reading specific registers.

```bash
# Scan for motors
motorbridge-cli scan --vendor all --channel can0 --start-id 1 --end-id 32
```

```bash
# Run motor in MIT mode
motorbridge-cli run \
    --vendor damiao \
    --channel can0 \
    --model 4340P \
    --motor-id 0x01 \
    --feedback-id 0x11 \
    --mode mit \
    --loop 100 \
    --dt-ms 20 \
    --pos 1.0 \
    --kp 30.0 \
    --kd 1.0
```

```bash
# Read Damiao registers
motorbridge-cli id-dump \
    --vendor damiao \
    --channel can0 \
    --motor-id 0x01 \
    --feedback-id 0x11 \
    --rids 7,8,9,10,21,22,23
```

--------------------------------

### Motor Calibration Studio Setup

Source: https://motorbridge.seeedstudio.com/what-is-motorbridge

Steps to set up and run the MotorBridge Studio for motor calibration routines. This involves navigating to the studio directory, installing dependencies, and starting the development server.

```bash
cd ../motorbridge-studio
npm install
npm run dev
```

--------------------------------

### Start WebSocket Demo Backend

Source: https://motorbridge.seeedstudio.com/source/python/examples/overview

Initiate the Python WebSocket backend for the quad motor demo. This requires installing the 'websockets' library and setting environment variables for Python path and library path.

```bash
cd /path/to/rust_dm
python3 -m venv .venv-ws
source .venv-ws/bin/activate
pip install websockets
export PYTHONPATH=$PWD/bindings/python/src
export LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH}
python3 bindings/python/examples/quad_vendor_binding_ws_demo.py \
  --bind 127.0.0.1 --port 9010 --channel can0 --dt-ms 20
```

--------------------------------

### Build C Examples

Source: https://motorbridge.seeedstudio.com/source/examples/c/overview

Builds the motor_abi library and the C example executables. Ensure the `target/release` directory is in your `LD_LIBRARY_PATH` before running.

```bash
cargo build -p motor_abi --release
cc examples/c/c_abi_demo.c -I motor_abi/include -L target/release -lmotor_abi -o c_abi_demo
cc examples/c/hexfellow_canfd_demo.c -I motor_abi/include -L target/release -lmotor_abi -o hexfellow_canfd_demo
LD_LIBRARY_PATH=target/release ./c_abi_demo --help
```

--------------------------------

### Build and Run Python Examples

Source: https://motorbridge.seeedstudio.com/source/examples/python/overview

Build the motor_abi Rust crate and display help for the Python ctypes demo script. This is a prerequisite for running the other examples.

```bash
cargo build -p motor_abi --release
python3 examples/python/python_ctypes_demo.py --help
```

--------------------------------

### macOS (PCBUSB) Driver/Runtime Install (System-wide)

Source: https://motorbridge.seeedstudio.com/install

Install the PCBUSB driver and runtime system-wide on macOS by downloading, extracting, and running the install script.

```bash
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
```

--------------------------------

### Manual PCBUSB Installation on macOS

Source: https://motorbridge.seeedstudio.com/source/repository/overview

Steps for manually downloading and installing the PCBUSB runtime on macOS. This involves downloading the archive, extracting it, and running the provided install script.

```bash
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
```

```bash
tar -xzf macOS_Library_for_PCANUSB_v0.13.tar.gz
cd PCBUSB
sudo ./install.sh
```

--------------------------------

### Scan Examples

Source: https://motorbridge.seeedstudio.com/api/cli

Illustrative examples demonstrating how to use the `scan` command with different configurations for various vendors and transport methods.

```APIDOC
### Examples

#### Scan All Vendors

```bash
motorbridge-cli scan --vendor all --channel can0 --start-id 1 --end-id 255
```

#### Scan Damiao Only

```bash
motorbridge-cli scan --vendor damiao --channel can0 --start-id 0x01 --end-id 0x20
```

#### Scan RobStride

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

For RobStride, `probe` / `device_id` is the motor ID. `feedback_id` / `host_id` such as `0xFD` is the host-side ID.

#### Scan MyActuator

```bash
motorbridge-cli scan --vendor myactuator --channel can0 --start-id 1 --end-id 32
```

#### Scan HighTorque

```bash
motorbridge-cli scan --vendor hightorque --channel can0 --start-id 1 --end-id 127
```

#### Scan Hexfellow (CAN-FD required)

```bash
motorbridge-cli scan --vendor hexfellow --transport socketcanfd --channel can0 --start-id 0 --end-id 255
```

#### Scan via Serial

```bash
motorbridge-cli scan \
    --vendor damiao \
    --transport dm-serial \
    --serial-port /dev/ttyACM0 \
    --start-id 1 \
    --end-id 32
```
```

--------------------------------

### Install PCBUSB Runtime on macOS

Source: https://motorbridge.seeedstudio.com/source/repository/overview

Helper script to install the PCBUSB runtime on macOS. Use `--user-local` for a user-specific installation without sudo, or `--system` for a system-wide installation requiring sudo.

```bash
./scripts/setup_pcbusb_macos.sh --user-local
```

```bash
./scripts/setup_pcbusb_macos.sh --system
```

--------------------------------

### Complete Multi-Motor Control Example

Source: https://motorbridge.seeedstudio.com/tutorials/04-multi-motor

A full example demonstrating how to initialize multiple motors, set their modes, and control them in a synchronized manner using sinusoidal trajectories.

```python
import time
import math
from motorbridge import Controller, Mode

def main():
    MOTORS = {
        "left_hip": {"id": 0x01, "fb": 0x11},
        "left_knee": {"id": 0x02, "fb": 0x12},
        "right_hip": {"id": 0x03, "fb": 0x13},
        "right_knee": {"id": 0x04, "fb": 0x14},
    }

    with Controller("can0") as ctrl:
        motors = {
            name: ctrl.add_damiao_motor(cfg["id"], cfg["fb"], "4340P")
            for name, cfg in MOTORS.items()
        }

        print("Enabling...")
        ctrl.enable_all()

        print("Setting mode...")
        for motor in motors.values():
            motor.ensure_mode(Mode.MIT, 1000)

        print("Running (Ctrl+C to stop)...")
        try:
            for i in range(500):
                t = i * 0.02

                # Generate targets
                targets = {
                    "left_hip": 0.3 * math.sin(t),
                    "left_knee": 0.5 * math.sin(t),
                    "right_hip": 0.3 * math.sin(t + 0.1),
                    "right_knee": 0.5 * math.sin(t + 0.1),
                }

                # Send commands
                for name, target in targets.items():
                    motors[name].send_mit(target, 0.0, 30.0, 1.0, 0.0)

                time.sleep(0.02)

        except KeyboardInterrupt:
            print("\nInterrupted")
        finally:
            print("Disabling...")
            ctrl.disable_all()

if __name__ == "__main__":
    main()
```

--------------------------------

### Run ws_quad_sync_hmi_rs.html Gateway and Server

Source: https://motorbridge.seeedstudio.com/source/examples/web/overview

Commands to start the WebSocket gateway and a Python HTTP server for the RobStride variant of the HMI. This setup is similar to the standard HMI but serves a different HTML file for a different motor configuration.

```bash
# terminal A: start gateway
car go run -p ws_gateway --release -- --bind 127.0.0.1:9002 --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

# terminal B: serve static files from repo root
python3 -m http.server 18080

# browser (RobStride variant):
http://127.0.0.1:18080/examples/web/ws_quad_sync_hmi_rs.html
```

--------------------------------

### Install Motorbridge using a Virtual Environment

Source: https://motorbridge.seeedstudio.com/install

Recommended installation method. Create, activate, install Motorbridge, and then deactivate the virtual environment when finished. This isolates dependencies.

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

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

# Install
pip install motorbridge

# Deactivate when done
deactivate
```

--------------------------------

### Install motorbridge-cli

Source: https://motorbridge.seeedstudio.com/api/cli

Install the CLI tool using pip. After installation, you can run `motorbridge-cli --help` to see available commands.

```bash
pip install motorbridge
motorbridge-cli --help
```

--------------------------------

### Install and Verify Python SDK

Source: https://motorbridge.seeedstudio.com/source/project/windows-distribution

Installs the motorbridge Python SDK from a local wheel file and verifies the installation by creating a Controller instance.

```python
python -m pip install bindings/python/dist/motorbridge-*.whl
python -c "from motorbridge import Controller; c=Controller('can0@1000000'); print('ok'); c.close()"
```

--------------------------------

### Python SDK: Read, Write, and Store Damiao Motor Parameters

Source: https://motorbridge.seeedstudio.com/source/rust-cli/damiao-api

Use this Python SDK example to read, modify, and persist motor parameters. It demonstrates the recommended workflow of getting a register's value, writing a new value, and then storing the parameters.

```python
from motorbridge import Controller

with Controller("can0") as ctrl:
    m = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
    old = m.get_register_f32(22, 1000)
    print("old VMAX", old)
    m.write_register_f32(22, old * 0.9)
    new = m.get_register_f32(22, 1000)
    print("new VMAX", new)
    m.store_parameters()
    m.close()
```

--------------------------------

### WS Gateway Command Examples

Source: https://motorbridge.seeedstudio.com/source/rust-cli/damiao-api

Examples of WS gateway commands for interacting with Damiao devices, including reading registers, writing registers, and storing parameters.

```APIDOC
## WS Gateway Command Examples

These examples show the JSON format for WS gateway commands to control Damiao devices.

### Get Register (32-bit float)

Retrieves the value of a specified register.

- **op**: `get_register_f32` (string, required)
- **rid**: Register ID (integer, required)
- **timeout_ms**: Timeout in milliseconds (integer, required)

```json
{
  "op": "get_register_f32",
  "rid": 22,
  "timeout_ms": 1000
}
```

### Write Register (32-bit float)

Writes a new value to a specified register.

- **op**: `write_register_f32` (string, required)
- **rid**: Register ID (integer, required)
- **value**: The new value to write (float, required)

```json
{
  "op": "write_register_f32",
  "rid": 22,
  "value": 25.0
}
```

### Store Parameters

Persists the current parameters on the device.

- **op**: `store_parameters` (string, required)

```json
{
  "op": "store_parameters"
}
```
```

--------------------------------

### Build C/C++ ABI Demos

Source: https://motorbridge.seeedstudio.com/source/examples/damiao-controll-all-in-one

Builds the C and C++ ABI demo executables. Ensure you have Rust and GCC/G++ installed.

```bash
cargo build -p motor_abi --release
gcc -O2 examples/c/c_abi_demo.c -I motor_abi/include -L target/release -lmotor_abi -Wl,-rpath,'$ORIGIN/../../target/release' -o examples/c/c_abi_demo
g++ -O2 examples/cpp/cpp_abi_demo.cpp -I motor_abi/include -L target/release -lmotor_abi -Wl,-rpath,'$ORIGIN/../../target/release' -o examples/cpp/cpp_abi_demo
```

--------------------------------

### Run Damiao MIT Mode Example

Source: https://motorbridge.seeedstudio.com/source/examples/cpp/overview

Executes the C++ demo in MIT mode for a Damiao motor. This example requires specifying motor details, control parameters, and loop settings.

```bash
LD_LIBRARY_PATH=target/release ./cpp_abi_demo \
  --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --mode mit --pos 0 --vel 0 --kp 20 --kd 20 --tau 0 --loop 50 --dt-ms 20
```

--------------------------------

### Serial Port Setup on macOS

Source: https://motorbridge.seeedstudio.com/transports

List typical serial device paths on macOS systems.

```bash
# Typical serial devices
ls -la /dev/cu.usbmodem* /dev/cu.usbserial*
```

--------------------------------

### Install Motorbridge from Source (Git)

Source: https://motorbridge.seeedstudio.com/install

Clone the repository, navigate to the Python bindings directory, build the ABI library, and then install the package in editable mode. This method requires the Rust toolchain.

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

pip install -e .
```

--------------------------------

### User-Local PCBUSB Installation on macOS

Source: https://motorbridge.seeedstudio.com/source/repository/overview

Instructions for installing PCBUSB to a user-local directory if system-wide installation is not possible. This involves copying library files and creating symbolic links.

```bash
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/
```

--------------------------------

### macOS (PCBUSB) Driver/Runtime Install (User-local)

Source: https://motorbridge.seeedstudio.com/install

Install the PCBUSB driver and runtime locally for the current user on macOS. This involves copying dylib and header files and setting the DYLD_LIBRARY_PATH.

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

--------------------------------

### Complete Motor Control Example

Source: https://motorbridge.seeedstudio.com/tutorials/02-enable-and-status

A comprehensive example demonstrating motor enabling, continuous state monitoring (position, velocity, torque, temperature, status), error clearing, and graceful shutdown. Handles `KeyboardInterrupt` for stopping.

```python
import time
from motorbridge import Controller
from motorbridge.errors import CallError

def main():
    with Controller("can0") as ctrl:
        motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")

        print("Enabling motor...")
        ctrl.enable_all()

        print("Monitoring state (Ctrl+C to stop)...")
        try:
            while True:
                motor.request_feedback()
                state = motor.get_state()

                if state:
                    # Format state
                    print(
                        f"pos={state.pos:+7.3f} | "
                        f"vel={state.vel:+6.3f} | "
                        f"torq={state.torq:+5.2f} | "
                        f"t={state.t_mos:5.1f}°C | "
                        f"status=0x{state.status_code:02X}"
                    )

                    # Check for errors
                    if state.status_code != 0:
                        print(f"Error detected, clearing...")
                        motor.clear_error()
                else:
                    print("Waiting for feedback...")

                time.sleep(0.1)

        except KeyboardInterrupt:
            print("\nStopping...")
        finally:
            print("Disabling motor...")
            motor.disable()
            print("Done")

if __name__ == "__main__":
    main()
```

--------------------------------

### Python SDK API Example

Source: https://motorbridge.seeedstudio.com/source/rust-cli/damiao-api

Example of using the Python SDK to read, write, and store 32-bit float registers for a Damiao motor.

```APIDOC
## Python SDK API Example

This example demonstrates how to use the `motorbridge` Python SDK to interact with a Damiao motor.

### Usage

1. Initialize a `Controller` with the appropriate CAN interface.
2. Add a Damiao motor using `add_damiao_motor`.
3. Read an existing 32-bit float register value using `get_register_f32`.
4. Write a new 32-bit float value to a register using `write_register_f32`.
5. Read back the register value to verify the write operation.
6. Persist the parameters using `store_parameters`.
7. Close the motor controller connection.

```python
from motorbridge import Controller

with Controller("can0") as ctrl:
    m = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
    old = m.get_register_f32(22, 1000)
    print("old VMAX", old)
    m.write_register_f32(22, old * 0.9)
    new = m.get_register_f32(22, 1000)
    print("new VMAX", new)
    m.store_parameters()
    m.close()
```
```

--------------------------------

### 30-Second Minimal Motorbridge Example

Source: https://motorbridge.seeedstudio.com/quickstart

A concise example demonstrating the basic usage of Motorbridge to add a motor, enable it, set its mode, send a position command, and read its state.

```python
from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)

    # Send position command
    motor.send_mit(pos=0.5, vel=0.0, kp=20.0, kd=1.0, tau=0.0)

    # Read state
    print(motor.get_state())
```

--------------------------------

### Build Project with Cargo

Source: https://motorbridge.seeedstudio.com/source/repository/overview

Compile the project using Cargo. Ensure you have Rust and Cargo installed.

```bash
cargo build
```

--------------------------------

### Damiao MIT Example

Source: https://motorbridge.seeedstudio.com/source/examples/c/overview

Executes a 'mit' (positional) mode example for a Damiao motor. Requires specifying vendor, channel, model, motor ID, feedback ID, and control parameters.

```bash
LD_LIBRARY_PATH=target/release ./c_abi_demo \
  --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
```

--------------------------------

### Complete Motor Control Loop Example

Source: https://motorbridge.seeedstudio.com/api/mode-and-state

A comprehensive example demonstrating motor control within a `Controller` context. It includes enabling the motor, setting its mode, executing a sinusoidal position control loop, monitoring state, and performing safety checks for temperature and status codes. Ensure the 'can0' interface is available and the motor is correctly configured.

```python
import time
from motorbridge import Controller, Mode, MotorState

def print_state(state: MotorState, prefix: str = ""):
    """Pretty print motor state."""
    print(f"{prefix}pos={state.pos:+7.3f} rad | "
          f"vel={state.vel:+6.3f} rad/s | "
          f"torq={state.torq:+5.2f} Nm | "
          f"t_mos={state.t_mos:5.1f}°C | "
          f"status=0x{state.status_code:02X}")

with Controller("can0") as ctrl:
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")

    # Enable motor
    ctrl.enable_all()
    motor.ensure_mode(Mode.POS_VEL, 1000)

    # Control loop with state monitoring
    target_pos = 0.0

    for i in range(100):
        # Sinusoidal position target
        target_pos = 1.0 * (1.0 - (i / 50.0) if i < 50 else (i - 50) / 50.0)

        # Send command
        motor.send_pos_vel(target_pos, vlim=2.0)

        # Read state
        motor.request_feedback()
        state = motor.get_state()

        if state:
            print_state(state, prefix=f"#{i:03d} ")

            # Safety check
            if state.t_mos > 85.0:
                print("WARNING: MOSFET overheating!")
            if state.status_code != 0:
                print(f"ERROR: status=0x{state.status_code:02X}")

        time.sleep(0.02)

    motor.disable()
```

--------------------------------

### RobStride Motor Control and Parameter Reading

Source: https://motorbridge.seeedstudio.com/source/cpp/overview

Quick start for controlling a RobStride motor. This example shows adding the motor, pinging it to get IDs, reading a float parameter, and checking conditions.

```cpp
#include "motorbridge/motorbridge.hpp"

int main() {
  motorbridge::Controller ctrl("can0");
  auto motor = ctrl.add_robstride_motor(127, 0xFD, "rs-06"); // replace with the RS model you use for limits/logging
  auto ids = motor.robstride_ping();
  float pos = motor.robstride_get_param_f32(0x7019);
  ctrl.shutdown();
  return static_cast<int>(ids.first == 127 && pos > -1000.0f);
}
```

--------------------------------

### Run C ABI Demo Examples

Source: https://motorbridge.seeedstudio.com/source/examples/damiao-controll-all-in-one

Executes the C ABI demo with different control modes and parameters. Requires the demo executable to be built.

```bash
./examples/c/c_abi_demo \
  --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --mode mit --pos 0 --vel 0 --kp 8 --kd 0.2 --tau 0.3 --loop 100 --dt-ms 10
```

```bash
./examples/c/c_abi_demo \
  --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --mode pos-vel --pos -2.0 --vlim 1.0 --loop 100 --dt-ms 20
```

--------------------------------

### Serial Port Setup on Windows (PowerShell)

Source: https://motorbridge.seeedstudio.com/transports

List available COM ports on Windows using PowerShell.

```powershell
# List COM ports
[System.IO.Ports.SerialPort]::GetPortNames()
```

--------------------------------

### Configure CAN-FD Interface on Linux

Source: https://motorbridge.seeedstudio.com/transports

Configure a CAN interface for CAN-FD mode with specified bitrates. This setup is required before using the Python CAN-FD example.

```bash
sudo ip link set can0 type can bitrate 1000000 dbitrate 5000000 fd on
sudo ip link set can0 up
```

--------------------------------

### Get Motorbridge Version

Source: https://motorbridge.seeedstudio.com/source/python/overview

You can check the installed package version using the `__version__` attribute or the `get_version()` function. The CLI also provides a version flag.

```python
import motorbridge

print(motorbridge.__version__)
print(motorbridge.get_version())
```

--------------------------------

### Add Single Damiao Motor

Source: https://motorbridge.seeedstudio.com/reference/can-id-and-model-cheatsheet

Example of setting up a single Damiao motor with its specific CAN IDs and model string.

```python
# Typical single motor setup
motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
```

--------------------------------

### MotorBridge WebSocket Gateway

Source: https://motorbridge.seeedstudio.com/what-is-motorbridge

Start the WebSocket gateway to control motors remotely. This is useful for browser-based applications. Ensure the gateway is installed via pip wheel.

```bash
motorbridge-gateway -- --bind 127.0.0.1:9002
```

--------------------------------

### Start WebSocket Demo Frontend

Source: https://motorbridge.seeedstudio.com/source/python/examples/overview

Launch the HTTP server for the WebSocket demo's frontend. This should be run in a separate terminal from the backend.

```bash
cd /path/to/rust_dm/bindings/python/examples
python3 -m http.server 8080
```

--------------------------------

### Damiao Motor Control via CAN

Source: https://motorbridge.seeedstudio.com/source/cpp/overview

Quick start example for controlling a Damiao motor using the CAN interface. Ensure the motor is added and enabled before sending commands.

```cpp
#include "motorbridge/motorbridge.hpp"

int main() {
  motorbridge::Controller ctrl("can0");
  auto motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P");
  ctrl.enable_all();
  motor.ensure_mode(motorbridge::Mode::MIT, 1000);
  motor.send_mit(0.0f, 0.0f, 20.0f, 1.0f, 0.0f);
  ctrl.shutdown();
  return 0;
}
```

--------------------------------

### Run C++ ABI Demo Examples

Source: https://motorbridge.seeedstudio.com/source/examples/damiao-controll-all-in-one

Executes the C++ ABI demo with different control modes and parameters. Requires the demo executable to be built.

```bash
./examples/cpp/cpp_abi_demo \
  --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --mode vel --vel 1.0 --loop 100 --dt-ms 20
```

```bash
./examples/cpp/cpp_abi_demo \
  --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --mode force-pos --pos -2.0 --vlim 1.0 --ratio 0.2 --loop 100 --dt-ms 10
```

--------------------------------

### Complete Motor Control Example

Source: https://motorbridge.seeedstudio.com/api/motor

This Python script shows the full lifecycle of motor control, from initialization to a continuous control loop and final disable. Ensure the 'motorbridge' library is installed and the CAN interface ('can0') is configured.

```python
import time
from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    # Register motor
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")

    # Enable and set mode
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, timeout_ms=1000)

    # Control loop
    for i in range(100):
        # Send command
        motor.send_mit(pos=0.5, vel=0.0, kp=30.0, kd=1.0, tau=0.0)

        # Request and read feedback
        motor.request_feedback()
        state = motor.get_state()

        if state:
            print(f"#{i:03d} pos={state.pos:+.3f} vel={state.vel:+.3f}")

        time.sleep(0.02)

    # Clean disable
    motor.disable()
```

--------------------------------

### Run ws_quad_sync_hmi.html Gateway and Server

Source: https://motorbridge.seeedstudio.com/source/examples/web/overview

Commands to start the WebSocket gateway and a Python HTTP server to serve the HMI files. Ensure the gateway is configured with the correct motor and feedback IDs. Adjust `--dt-ms` for stability if needed.

```bash
# terminal A: start gateway
car go run -p ws_gateway --release -- --bind 127.0.0.1:9002 --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

# terminal B: serve static files from repo root
python3 -m http.server 18080

# browser:
http://127.0.0.1:18080/examples/web/ws_quad_sync_hmi.html
```

--------------------------------

### Install Motorbridge from PyPI

Source: https://motorbridge.seeedstudio.com/best-practices/release-and-versioning

Install the latest stable version, a specific version, or upgrade an existing installation using pip.

```bash
# Latest stable version
pip install motorbridge

# Specific version
pip install motorbridge==0.4.1

# Upgrade
pip install --upgrade motorbridge
```

--------------------------------

### Build Motor ABI and Run C Demo

Source: https://motorbridge.seeedstudio.com/source/examples/overview

Build the motor ABI library and compile a C demo program. Run the C demo to interact with motors, supporting RobStride and Damiao vendors.

```bash
cargo build -p motor_abi --release
cc examples/c/c_abi_demo.c -I motor_abi/include -L target/release -lmotor_abi -o c_abi_demo
LD_LIBRARY_PATH=target/release ./c_abi_demo --vendor robstride --channel can0 --model rs-06 --motor-id 127 --mode ping
LD_LIBRARY_PATH=target/release ./c_abi_demo --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 --mode mit
```

--------------------------------

### Verify Motorbridge Installation

Source: https://motorbridge.seeedstudio.com/best-practices/troubleshooting

Check if the motorbridge package is correctly installed and importable in Python. This is a quick verification step after installation or reinstallation.

```bash
python3 -c "import motorbridge; print('OK')"
```

--------------------------------

### Mermaid Flowchart for Documentation Paths

Source: https://motorbridge.seeedstudio.com/source/index

Illustrates the different paths a user can take through the documentation, from new user to deep implementation details.

```mermaid
flowchart TB
  New["New user"] --> Curated["Curated guides\nGet Started / Tutorials / API"]
  Curated --> Task["Task-oriented use\ninstall, scan, control, troubleshoot"]
  Task --> Source["Source reference\noriginal repository docs"]
  Source --> Deep["Deep implementation\nABI, Rust CLI, integrations, release notes"]

  classDef start fill:#E0F2FE,stroke:#0284C7,color:#075985;
  classDef guide fill:#F0FDF4,stroke:#16A34A,color:#166534;
  classDef ref fill:#FFF7ED,stroke:#EA580C,color:#9A3412;
  class New start;
  class Curated,Task guide;
  class Source,Deep ref;
```

--------------------------------

### Linux (SocketCAN) CAN Interface Setup

Source: https://motorbridge.seeedstudio.com/install

Configure and bring up a CAN interface on Linux using SocketCAN. Ensure the necessary kernel modules are loaded and the interface is configured with the desired bitrate.

```bash
# Check whether CAN interface exists
ip link show can0
```

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

```bash
# 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
```

```bash
# Increase TX queue length
sudo ifconfig can0 txqueuelen 1000
```

--------------------------------

### Basic MIT Control Example

Source: https://motorbridge.seeedstudio.com/tutorials/03-mode-switch-and-control

Demonstrates basic MIT mode control for both stiff position control and soft compliant control. Ensure the motor is initialized and enabled before sending commands.

```python
import time
from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)

    # Stiff position control
    motor.send_mit(
        pos=1.0,    # 1 radian target
        vel=0.0,    # Zero target velocity
        kp=50.0,    # High stiffness
        kd=2.0,     # Moderate damping
        tau=0.0     # No feedforward
    )

    # Soft compliant control
    motor.send_mit(
        pos=1.0,
        vel=0.0,
        kp=5.0,     # Low stiffness
        kd=0.5,     # Low damping
        tau=0.0
    )
```

--------------------------------

### Run Course Scripts

Source: https://motorbridge.seeedstudio.com/source/python/get-started/overview

Execute course scripts from the get_started directory using Python. These scripts guide users through various motor control workflows.

```bash
python3 bindings/python/get_started/courses/00-enable-and-status.py
python3 bindings/python/get_started/courses/01-scan.py
python3 bindings/python/get_started/courses/03-mode-switch-method.py
```

```bash
python3 bindings/python/get_started/courses/00-enable-and-status.py
python3 bindings/python/get_started/courses/01-scan.py
python3 bindings/python/get_started/courses/09-multi-motor.py
```

--------------------------------

### Run First Motorbridge Program

Source: https://motorbridge.seeedstudio.com/what-is-motorbridge

Example of initializing a Motorbridge controller, adding a specific motor, enabling all motors, setting the motor to MIT mode, and sending a command.

```python
from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)
    motor.send_mit(0.5, 0.0, 30.0, 1.0, 0.0)
    print("Motor running!")
```

--------------------------------

### Upgrade Motorbridge Installation

Source: https://motorbridge.seeedstudio.com/install

Upgrade an existing motorbridge installation to the latest available version.

```bash
python3 -m pip install --upgrade motorbridge
```

--------------------------------

### Verify Motorbridge Installation

Source: https://motorbridge.seeedstudio.com/install

Quickly verify if the motorbridge package has been installed successfully by importing it in Python.

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

--------------------------------

### Build WS Gateway

Source: https://motorbridge.seeedstudio.com/source/integrations/ws-gateway/overview

Build the WS Gateway project in release mode.

```bash
cargo build -p ws_gateway --release
```

--------------------------------

### Install Specific Motorbridge Version

Source: https://motorbridge.seeedstudio.com/install

Install a particular version of the motorbridge package by specifying the version number.

```bash
python3 -m pip install motorbridge==0.4.1
```

--------------------------------

### Install Motorbridge from Git

Source: https://motorbridge.seeedstudio.com/best-practices/release-and-versioning

Install motorbridge directly from a Git repository, either from the main branch or a specific tag/commit.

```bash
# Install from Git
pip install git+https://github.com/tianrking/motorbridge@v0.4.1

# Install specific branch
pip install git+https://github.com/tianrking/motorbridge@main
```

--------------------------------

### Install motorbridge Package

Source: https://motorbridge.seeedstudio.com/source/python/get-started/overview

Install the motorbridge package using pip. For pre-release versions, specify the TestPyPI repository and version.

```bash
python3 -m pip install motorbridge
```

```bash
python3 -m pip install -i https://test.pypi.org/simple/ motorbridge==<version>
```

--------------------------------

### Mixed Vendor System Setup

Source: https://motorbridge.seeedstudio.com/reference/can-id-and-model-cheatsheet

Demonstrates setting up motors from different vendors (Damiao and RobStride) on the same CAN bus using separate controller instances.

```python
# Damiao + RobStride on same bus
with Controller("can0") as dm_ctrl:
    dm = dm_ctrl.add_damiao_motor(0x01, 0x11, "4340P")

    with Controller("can0") as rs_ctrl:
        rs = rs_ctrl.add_robstride_motor(127, 0xFD, "rs-06")
```

--------------------------------

### Install Motorbridge from PyPI

Source: https://motorbridge.seeedstudio.com/install

Use this command to install the latest stable version of the motorbridge package from the Python Package Index.

```bash
python3 -m pip install motorbridge
```

--------------------------------

### Run Damiao Wrapper Demo

Source: https://motorbridge.seeedstudio.com/source/cpp/overview

Execute the C++ wrapper demo for Damiao motors. This command requires setting the LD_LIBRARY_PATH to include the release directory of the MotorBridge ABI library. Configure parameters like channel, model, motor ID, feedback ID, position, velocity, gains, loop count, and time step.

```bash
export LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH}

# Damiao wrapper demo
./bindings/cpp/build/cpp_wrapper_demo \
  --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --pos 0 --vel 0 --kp 20 --kd 1 --tau 0 --loop 20 --dt-ms 20
```

--------------------------------

### Install MotorBridge Package

Source: https://motorbridge.seeedstudio.com/

Installs the MotorBridge library using pip. This is the first step for setting up the motor control environment.

```bash
pip install motorbridge
```

--------------------------------

### Robstride Write Parameter Output Example

Source: https://motorbridge.seeedstudio.com/api/cli

This is an example of the output you might see after successfully writing a parameter to a Robstride motor.

```text
command=robstride-write-param channel=can0 model=rs-06 motor_id=0x7F param_id=0x7019 type=f32 value=2.0 verify=2.0 store=1
```

--------------------------------

### Initialize Controller with SocketCAN

Source: https://motorbridge.seeedstudio.com/api/controller

Create a Controller instance using the standard SocketCAN transport. This is the recommended approach for basic usage and can be managed with a context manager.

```python
from motorbridge import Controller

# Basic usage
ctrl = Controller("can0")

# With context manager (recommended)
with Controller("can0") as ctrl:
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
```

--------------------------------

### Install Motorbridge from Source (Fallback)

Source: https://motorbridge.seeedstudio.com/source/repository/overview

Use this command for a fallback installation of Motorbridge from source, useful when binary wheels are not available or preferred.

```bash
pip install --no-binary motorbridge motorbridge
```

--------------------------------

### MotorBridge WebSocket Gateway (from source)

Source: https://motorbridge.seeedstudio.com/what-is-motorbridge

Alternative method to start the WebSocket gateway directly from the source tree using Cargo. Ensure you are in the correct directory.

```bash
cargo run -p ws_gateway -- --bind 127.0.0.1:9002
```

--------------------------------

### Install Motorbridge from TestPyPI

Source: https://motorbridge.seeedstudio.com/best-practices/release-and-versioning

Install a pre-release version from TestPyPI for testing purposes. Use with caution as pre-releases may contain breaking changes.

```bash
# Install from TestPyPI
pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1a1
```

--------------------------------

### Controller Initialization with Serial Bridge

Source: https://motorbridge.seeedstudio.com/api/controller

Create a controller instance using Damiao serial bridge transport.

```APIDOC
## Controller.from_dm_serial(serial_port="/dev/ttyACM0", baud=921600)

### Description
Create a controller using Damiao serial bridge transport.

### Parameters
#### Path Parameters
- **serial_port** (str) - Optional - Serial device path. Defaults to "/dev/ttyACM0".
- **baud** (int) - Optional - Baud rate. Defaults to 921600 (recommended for Damiao).

### Request Example
```python
from motorbridge import Controller

with Controller.from_dm_serial("/dev/ttyACM0", 921600) as ctrl:
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
```

### Response
#### Success Response (Controller instance)
- Returns a Controller instance.

#### Error Response
- **CallError**: Raised if the serial port cannot be opened.
```

--------------------------------

### Initialize Controller with CAN-FD

Source: https://motorbridge.seeedstudio.com/source/python/overview

Use the `Controller.from_socketcanfd` class method when your system requires CAN-FD, such as with Hexfellow devices.

```python
from motorbridge import Controller

controller = Controller.from_socketcanfd(channel="can0")
```

--------------------------------

### Verify Python Package Installation from TestPyPI

Source: https://motorbridge.seeedstudio.com/best-practices/release-and-versioning

Installs a package from TestPyPI and runs pytest to verify its functionality. Ensure the version number matches the one uploaded.

```bash
pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1
python3 -m pytest tests/
```

--------------------------------

### Serial Port Setup on Linux

Source: https://motorbridge.seeedstudio.com/transports

Commands to check available serial ports and add user permissions for accessing them. Requires logging out and back in after adding the user to the dialout group.

```bash
# Check available serial ports
ls -la /dev/ttyACM* /dev/ttyUSB*

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

--------------------------------

### Check Installed Motorbridge Version (CLI)

Source: https://motorbridge.seeedstudio.com/best-practices/release-and-versioning

Verify the installed motorbridge version using command-line tools like pip, the motorbridge CLI, or the Rust CLI.

```bash
# Using pip
pip show motorbridge

# Using the Python CLI
motorbridge-cli -v

# Using the Rust CLI
motor_cli -v

# Using Python
python3 -c "import importlib.metadata; print(importlib.metadata.version('motorbridge'))"
python3 -c "import motorbridge; print(motorbridge.get_version())"
```

--------------------------------

### Build Motor ABI and Run C++ Demo

Source: https://motorbridge.seeedstudio.com/source/examples/overview

Build the motor ABI library and compile a C++ demo program. Run the C++ demo to interact with motors, supporting RobStride and Damiao vendors.

```bash
cargo build -p motor_abi --release
g++ -std=c++17 examples/cpp/cpp_abi_demo.cpp -I motor_abi/include -L target/release -lmotor_abi -o cpp_abi_demo
LD_LIBRARY_PATH=target/release ./cpp_abi_demo --vendor robstride --channel can0 --model rs-06 --motor-id 127 --mode ping
LD_LIBRARY_PATH=target/release ./cpp_abi_demo --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 --mode mit
```

--------------------------------

### Robstride Read Parameter Output Example

Source: https://motorbridge.seeedstudio.com/api/cli

This is an example of the output format when successfully reading a parameter from a RobStride motor. It includes command details and the retrieved value.

```text
command=robstride-read-param channel=can0 model=rs-06 motor_id=0x7F param_id=0x7019 type=f32 value=1.5
```

--------------------------------

### Validate MotorBridge CLI on Windows

Source: https://motorbridge.seeedstudio.com/source/python/overview

Use these commands to validate the MotorBridge CLI installation on Windows with PCAN-USB. Ensure the PEAK PCAN driver and PCAN-Basic runtime are installed.

```bash
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
```

```bash
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
```

```bash
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
```

--------------------------------

### Run Python Wrapper Demo

Source: https://motorbridge.seeedstudio.com/source/python/examples/overview

Executes the Python wrapper demo script for basic motor control via CAN. Requires specifying channel, model, motor/feedback IDs, and control parameters.

```bash
PYTHONPATH=bindings/python/src python3 bindings/python/examples/python_wrapper_demo.py \
  --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --pos 0 --vel 0 --kp 20 --kd 1 --tau 0 --loop 20 --dt-ms 20
```

--------------------------------

### Check Installed Motorbridge Version (Programmatically)

Source: https://motorbridge.seeedstudio.com/best-practices/release-and-versioning

Retrieve the installed motorbridge version within a Python script using importlib.metadata or the motorbridge library's get_version() function.

```python
import motorbridge

import importlib.metadata
print(f"motorbridge version: {importlib.metadata.version('motorbridge')}")
print(f"motorbridge API version: {motorbridge.get_version()}")
```

--------------------------------

### Initialize Controller with Damiao Serial

Source: https://motorbridge.seeedstudio.com/source/python/overview

For Damiao-only serial bridges, use the `Controller.from_dm_serial` class method, specifying the serial port and baud rate.

```python
from motorbridge import Controller

controller = Controller.from_dm_serial(serial_port="/dev/ttyACM0", baud=921600)
```

--------------------------------

### Set Python Environment for ctypes Examples

Source: https://motorbridge.seeedstudio.com/source/examples/damiao-controll-all-in-one

Sets the LD_LIBRARY_PATH environment variable to include the release directory for shared libraries. This is required before running Python ctypes examples.

```bash
export LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH}
```

--------------------------------

### Launch WS Gateway on macOS (Dynamic Library Load Failure)

Source: https://motorbridge.seeedstudio.com/install

This command is for macOS when dynamic library loading fails. It manually sets the library path and launches the gateway.

```bash
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
```

--------------------------------

### Run RobStride Python ctypes Example

Source: https://motorbridge.seeedstudio.com/source/project/examples

Executes a Python ctypes example for a RobStride motor. Requires specifying vendor, channel, model, motor ID, and operating mode.

```bash
python3 examples/python/python_ctypes_demo.py --vendor robstride --channel can0 --model rs-06 --motor-id 127 --mode ping
```
Tokens:
Raw