Skip to main content

Documentation Index

Fetch the complete documentation index at: https://motorbridge.seeedstudio.com/llms.txt

Use this file to discover all available pages before exploring further.

​
API: motorbridge-cli

​
Installation

The CLI is installed automatically with the Python package: 
pip install motorbridge
motorbridge-cli --help
Gateway is provided as a separate command at the same PATH level: 
motorbridge-gateway --help
-- is optional: motorbridge-gateway -- --help and motorbridge-gateway --help are equivalent.
For Ubuntu/Windows/macOS startup commands, see Installation -> “WS Gateway Quick Start (3 Platforms)”.

​
Global Options

motorbridge-cli [OPTIONS] COMMAND [ARGS]
OptionDescription
--helpShow help message and exit
-v, --versionPrint the installed motorbridge Python package version and exit
Since v0.3.3, motorbridge-cli disables argparse long-option abbreviation. Invalid subcommand options such as robstride-write-param --mode save are rejected instead of being interpreted as --model save.

​
Commands Overview

CommandDescription
runSend control commands to a motor
scanScan CAN bus for active motors
id-dumpRead Damiao ID/mode registers
id-setWrite Damiao ID registers
robstride-read-paramRead RobStride parameter
robstride-write-paramWrite RobStride parameter
damiao-read-paramRead Damiao parameter/register
damiao-write-paramWrite Damiao parameter/register

​
run

Run motor control commands in a loop.

​
Usage

motorbridge-cli run [OPTIONS]

​
Options

OptionDefaultDescription
--vendordamiaoMotor vendor: damiao, myactuator, robstride, hightorque, hexfellow
--channelcan0CAN interface name
--transportautoTransport: auto, socketcan, socketcanfd, dm-serial
--serial-port/dev/ttyACM0Serial port (for dm-serial transport)
--serial-baud921600Serial baud rate
--model4340Motor model string
--motor-id0x01Motor CAN ID (hex supported)
--feedback-id0x11Feedback CAN ID (hex supported)
--modemitControl mode: enable, disable, mit, pos-vel, vel, force-pos, ping, zero, set-zero, save, zero-by-offset, read-param, write-param
--loop100Number of control iterations
--dt-ms20Control period in milliseconds
--ensure-mode1Whether to ensure mode before control
--ensure-strict0Fail if mode switch fails
--ensure-timeout-ms1000Mode switch timeout
--print-state1Print state each iteration
--pos0.0Target position (rad)
--vel0.0Target velocity (rad/s)
--kp30.0Position stiffness (MIT mode)
--loc-kpemptyRobStride pos-vel position-loop gain; falls back to --kp when omitted
--kd1.0Velocity damping (MIT mode)
--tau0.0Feedforward torque (Nm)
--vlim1.0Velocity limit (rad/s)
--ratio0.3Force ratio (force-pos mode)
--zero-exp0Enable RobStride experimental zero sequence (1 to execute)
--offset-negate0Reserved for RobStride zero-by-offset; current firmware path is disabled
--store1Persist after run --mode write-param / zero sequence
--param-id0x0RobStride parameter ID for run --mode read-param/write-param
--param-valueemptyRobStride value for run --mode write-param
--param-typeinferredRobStride type for run --mode read-param/write-param: i8, u8, u16, u32, f32
--timeout-ms500Parameter read/write timeout
--set-motor-idemptyDamiao/RobStride Rust-style ID update shortcut
--set-feedback-idemptyDamiao MST_ID update shortcut; RobStride feedback_id/host_id is not changed
--verify-id1Verify ID update
--verify-model1Damiao model handshake using PMAX/VMAX/TMAX before active control
--verify-timeout-ms500Damiao model/ID verification timeout
--verify-tol0.2Damiao model verification tolerance

​
Mode-Parameter Mapping Notes

  • mit: --pos/--vel/--kp/--kd/--tau are effective.
  • pos-vel: effective args are --pos/--vlim; for RobStride, Python CLI follows the same native register path as the WS gateway (limit_spd 0x7017, loc_kp 0x701E, loc_ref 0x7016). Use --loop 1 for one target write; --vel/--kd/--tau are ignored by design.
  • zero / set-zero: currently RobStride-only; must pass --zero-exp 1 to actually send zero command sequence. MotorBridge writes zero_sta=1 internally for the RobStride zero flow.
  • save: currently RobStride-only; sends save-parameters and waits for the RobStride status ACK.
  • zero-by-offset: currently RobStride-only and intentionally disabled; it prints a warning and sends no calibration frames.
  • read-param / write-param: currently RobStride-only in run; use --param-id, --param-type, --param-value.
  • --set-motor-id / --set-feedback-id: when present, run enters the same ID update path as id-set. Damiao supports both; RobStride supports device ID only.

​
Examples

​
Enable Motor Only

motorbridge-cli run --vendor damiao --channel can0 --motor-id 0x01 --mode enable --loop 1

​
Disable Motor

motorbridge-cli run --vendor damiao --channel can0 --motor-id 0x01 --mode disable --loop 1

​
MIT Mode Control

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

​
Position-Velocity Mode

motorbridge-cli run \
    --vendor damiao \
    --channel can0 \
    --model 4340P \
    --motor-id 0x01 \
    --feedback-id 0x11 \
    --mode pos-vel \
    --loop 200 \
    --pos 2.0 \
    --vlim 1.5

​
RobStride Motor

motorbridge-cli run \
    --vendor robstride \
    --channel can0 \
    --model rs-00 \
    --motor-id 2 \
    --feedback-id 0xFD \
    --mode mit \
    --pos 0.5 \
    --vel 0 \
    --kp 20.0 \
    --kd 0.5 \
    --tau 0 \
    --ensure-strict 1 \
    --loop 100 \
    --dt-ms 20

​
RobStride Position-Velocity Mode

motorbridge-cli run \
    --vendor robstride \
    --channel can0 \
    --model rs-00 \
    --motor-id 2 \
    --feedback-id 0xFD \
    --mode pos-vel \
    --pos 1.5 \
    --vlim 1.0 \
    --loc-kp 5.0 \
    --loop 1 \
    --dt-ms 20
    --loc-kp 5.0 \
    --loop 1 \
    --dt-ms 20
Reverse direction by writing the opposite absolute position: 
motorbridge-cli run \
    --vendor robstride \
    --channel can0 \
    --model rs-00 \
    --motor-id 2 \
    --feedback-id 0xFD \
    --mode pos-vel \
    --pos -1.5 \
    --vlim 1.0 \
    --loc-kp 5.0 \
    --loop 1 \
    --dt-ms 20

​
RobStride Ping

motorbridge-cli run \
    --vendor robstride \
    --channel can0 \
    --model rs-06 \
    --motor-id 127 \
    --feedback-id 0xFD \
    --mode ping \
    --loop 1

​
RobStride Zero (set-zero alias available)

motorbridge-cli run \
    --vendor robstride \
    --channel can0 \
    --model rs-06 \
    --motor-id 127 \
    --feedback-id 0xFD \
    --mode set-zero \
    --zero-exp 1 \
    --store 1 \
    --loop 1 \
    --dt-ms 100

​
MyActuator Position-Velocity Mode

motorbridge-cli run \
    --vendor myactuator \
    --channel can0 \
    --model X8 \
    --motor-id 1 \
    --feedback-id 0x241 \
    --mode pos-vel \
    --loop 100 \
    --pos 1.0 \
    --vlim 2.0

​
Hexfellow MIT Mode (CAN-FD required)

motorbridge-cli run \
    --vendor hexfellow \
    --transport socketcanfd \
    --channel can0 \
    --model hexfellow \
    --motor-id 0x00 \
    --feedback-id 0x00 \
    --mode mit \
    --loop 100 \
    --pos 0.5 \
    --kp 2.0 \
    --kd 0.1

​
Using Serial Transport

motorbridge-cli run \
    --vendor damiao \
    --transport dm-serial \
    --serial-port /dev/ttyACM0 \
    --serial-baud 921600 \
    --model 4340P \
    --motor-id 0x01 \
    --feedback-id 0x11 \
    --mode mit \
    --loop 50

​
scan

Scan CAN bus for active motors.

​
Usage

motorbridge-cli scan [OPTIONS]

​
Options

OptionDefaultDescription
--vendordamiaoVendor to scan: damiao, myactuator, robstride, hightorque, hexfellow, all
--channelcan0CAN interface
--transportautoTransport type
--serial-port/dev/ttyACM0Serial port
--serial-baud921600Serial baud rate
--model4340Motor model
--start-id0x01Start ID for scan
--end-id0x10End ID for scan
--feedback-ids0xFD,0xFF,0xFE,0x00,0xAARobStride host_id candidates to try; these are not motor/device IDs
--feedback-base0x10Damiao feedback ID base
--timeout-ms80Per-ID timeout
--param-id0x7019RobStride parameter ID for probe
--param-timeout-ms120RobStride parameter timeout

​
Examples

​
Scan All Vendors

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

​
Scan Damiao Only

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

​
Scan RobStride

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

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

​
Scan HighTorque

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

​
Scan Hexfellow (CAN-FD required)

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

​
Scan via Serial

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

​
Output Format

command=scan vendor=damiao transport=auto channel=can0 model=4340 id_range=[0x1,0x20] timeout_ms=80
[scan:damiao] channel=can0 model=4340 id_range=[0x1,0x20] timeout_ms=80
[hit] vendor=damiao probe=0x01 esc_id=0x1 mst_id=0x11
[hit] vendor=damiao probe=0x02 esc_id=0x2 mst_id=0x12
[.. ] vendor=damiao probe=0x03 no reply
scan done: 2 motor(s) found
  probe=0x01 vendor=damiao esc_id=0x1 mst_id=0x11
  probe=0x02 vendor=damiao esc_id=0x2 mst_id=0x12

​
id-dump

Read key ID and configuration registers from Damiao motors.

​
Usage

motorbridge-cli id-dump [OPTIONS]

​
Options

OptionDefaultDescription
--vendordamiaoMust be damiao
--channelcan0CAN interface
--transportautoTransport type
--model4340Motor model
--motor-id0x01Motor ID
--feedback-id0x11Feedback ID
--timeout-ms500Register read timeout
--rids7,8,9,10,21,22,23Register IDs to read

​
Register IDs

RIDNameDescription
7MST_IDFeedback ID
8ESC_IDMotor ID
9TIMEOUTCommunication timeout
10CTRL_MODEControl mode
21PMAXPosition mapping range
22VMAXVelocity mapping range
23TMAXTorque mapping range

​
Example

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

​
Output

command=id-dump transport=auto channel=can0 model=4340 motor_id=0x1 feedback_id=0x11
rid=  7 (u32) = 17 (0x11)
rid=  8 (u32) = 1 (0x1)
rid=  9 (u32) = 5000 (0x1388)
rid= 10 (u32) = 1 (0x1)
rid= 21 (f32) = 12.566371
rid= 22 (f32) = 30.000000
rid= 23 (f32) = 10.000000

​
id-set

Write motor IDs and optionally store to flash. Damiao supports ESC_ID/MST_ID; RobStride supports changing device_id.

​
Usage

motorbridge-cli id-set [OPTIONS]

​
Options

OptionDefaultDescription
--vendordamiaodamiao or robstride
--channelcan0CAN interface
--transportautoTransport type
--model4340Motor model
--motor-id0x01Current motor ID
--feedback-id0x11Current feedback ID
--new-motor-id(same)New motor ID to set
--new-feedback-id(same)New Damiao feedback ID; ignored/not supported for RobStride host_id
--store1Store to flash after write
--verify1Verify after write
--timeout-ms800Verify timeout

​
Example

# Change motor ID from 0x01 to 0x05
motorbridge-cli id-set \
    --vendor damiao \
    --channel can0 \
    --motor-id 0x01 \
    --feedback-id 0x11 \
    --new-motor-id 0x05 \
    --new-feedback-id 0x15 \
    --store 1 \
    --verify 1

# RobStride: change device_id from 0x7F to 0x7E
motorbridge-cli id-set \
    --vendor robstride \
    --channel can0 \
    --model rs-06 \
    --motor-id 0x7F \
    --feedback-id 0xFD \
    --new-motor-id 0x7E \
    --store 1 \
    --verify 1

​
Output

command=id-set transport=auto channel=can0 model=4340 old_motor_id=0x1 old_feedback_id=0x11 new_motor_id=0x5 new_feedback_id=0x15
write rid=7 (MST_ID) <= 0x15
write rid=8 (ESC_ID) <= 0x5
store_parameters sent
verify rid=8 (ESC_ID): 0x5
verify rid=7 (MST_ID): 0x15
verify ok

​
robstride-read-param

Read a parameter from RobStride motor.

​
Usage

motorbridge-cli robstride-read-param [OPTIONS]

​
Options

OptionDefaultDescription
--channelcan0CAN interface
--transportautoTransport: auto, socketcan, socketcanfd
--modelphysical modelPhysical RobStride model (rs-00 through rs-06); required because parameter tables differ by model
--motor-id127Motor ID
--feedback-id0xFDRobStride host_id default; not the motor/device ID
--param-id(required)Parameter ID to read
--type(required)Data type: i8, u8, u16, u32, f32
--timeout-ms500Read timeout

​
Example

motorbridge-cli run \
    --vendor robstride \
    --channel can0 \
    --model rs-06 \
    --motor-id 127 \
    --feedback-id 0xFD \
    --mode read-param \
    --param-id 0x7019 \
    --param-type f32

motorbridge-cli robstride-read-param \
    --channel can0 \
    --model rs-06 \
    --motor-id 127 \
    --feedback-id 0xFD \
    --param-id 0x7019 \
    --type f32

​
Output

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

​
robstride-write-param

Write a parameter to RobStride motor.

​
Usage

motorbridge-cli robstride-write-param [OPTIONS]

​
Options

OptionDefaultDescription
--channelcan0CAN interface
--transportautoTransport: auto, socketcan, socketcanfd
--modelphysical modelPhysical RobStride model (rs-00 through rs-06); required because parameter tables differ by model
--motor-id127Motor ID
--feedback-id0xFDRobStride host_id default; not the motor/device ID
--param-id(required)Parameter ID to write
--type(required)Data type: i8, u8, u16, u32, f32
--value(required)Value to write (parsed according to --type)
--verify1Read back and verify
--store0After a successful write/verify, send RobStride save-parameters (type 22)
--timeout-ms500Verify timeout

​
Example

motorbridge-cli run \
    --vendor robstride \
    --channel can0 \
    --model rs-06 \
    --motor-id 127 \
    --feedback-id 0xFD \
    --mode write-param \
    --param-id 0x7019 \
    --param-type f32 \
    --param-value 2.0

motorbridge-cli robstride-write-param \
    --channel can0 \
    --model rs-06 \
    --motor-id 127 \
    --feedback-id 0xFD \
    --param-id 0x7019 \
    --type f32 \
    --value 2.0 \
    --verify 1 \
    --store 1

​
Output

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

​
damiao-read-param

Read a Damiao parameter/register exposed by the Python binding.

​
Usage

motorbridge-cli damiao-read-param [OPTIONS]

​
Options

OptionDefaultDescription
--channelcan0CAN interface
--transportautoTransport: auto, socketcan, socketcanfd, dm-serial
--model4340Damiao model
--motor-id0x01Damiao ESC_ID
--feedback-id0x11Damiao MST_ID
--param-id(required)Register/parameter ID
--type(required)Data type: u32 or f32
--timeout-ms500Read timeout

​
Example

motorbridge-cli damiao-read-param \
    --channel can0 \
    --model 4340P \
    --motor-id 0x01 \
    --feedback-id 0x11 \
    --param-id 21 \
    --type f32

​
damiao-write-param

Write a Damiao parameter/register and optionally read it back.

​
Usage

motorbridge-cli damiao-write-param [OPTIONS]

​
Options

OptionDefaultDescription
--channelcan0CAN interface
--transportautoTransport: auto, socketcan, socketcanfd, dm-serial
--model4340Damiao model
--motor-id0x01Damiao ESC_ID
--feedback-id0x11Damiao MST_ID
--param-id(required)Register/parameter ID
--type(required)Data type: u32 or f32
--value(required)Value to write
--verify1Read back after write
--store0After a successful write/verify, call Damiao store_parameters()
--timeout-ms500Verify timeout

​
Example

motorbridge-cli damiao-write-param \
    --channel can0 \
    --model 4340P \
    --motor-id 0x01 \
    --feedback-id 0x11 \
    --param-id 8 \
    --type u32 \
    --value 0x01 \
    --verify 1 \
    --store 1

​
Common Workflows

​
Initial Setup

# 1. Scan for motors
motorbridge-cli scan --vendor all --channel can0 --start-id 1 --end-id 255

# 2. Read motor configuration
motorbridge-cli id-dump --vendor damiao --motor-id 0x01 --feedback-id 0x11

# 3. Test motor control
motorbridge-cli run --vendor damiao --motor-id 0x01 --mode enable --loop 1
motorbridge-cli run --vendor damiao --motor-id 0x01 --mode mit --loop 50 --pos 0.5

​
Changing Motor ID

# 1. Verify current ID works
motorbridge-cli id-dump --motor-id 0x01 --feedback-id 0x11

# 2. Set new ID
motorbridge-cli id-set \
    --motor-id 0x01 \
    --feedback-id 0x11 \
    --new-motor-id 0x05 \
    --new-feedback-id 0x15 \
    --store 1 \
    --verify 1

# 3. Verify with new ID
motorbridge-cli id-dump --motor-id 0x05 --feedback-id 0x15

​
RobStride Parameter Tuning

# Read current parameter
motorbridge-cli robstride-read-param --model rs-06 --motor-id 127 --param-id 0x7019 --type f32

# Write new value
motorbridge-cli robstride-write-param --model rs-06 --motor-id 127 --param-id 0x7019 --type f32 --value 2.5

# Verify
motorbridge-cli robstride-read-param --model rs-06 --motor-id 127 --param-id 0x7019 --type f32

​
Exit Codes

CodeMeaning
0Success
1General error
2Invalid arguments

​
See Also