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]

Option	Description
`--help`	Show help message and exit
`-v`, `--version`	Print 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

Command	Description
`run`	Send control commands to a motor
`scan`	Scan CAN bus for active motors
`id-dump`	Read Damiao ID/mode registers
`id-set`	Write Damiao ID registers
`robstride-read-param`	Read RobStride parameter
`robstride-write-param`	Write RobStride parameter
`damiao-read-param`	Read Damiao parameter/register
`damiao-write-param`	Write Damiao parameter/register

run

Run motor control commands in a loop.

Usage

motorbridge-cli run [OPTIONS]

Options

Option	Default	Description
`--vendor`	`damiao`	Motor vendor: damiao, myactuator, robstride, hightorque, hexfellow
`--channel`	`can0`	CAN interface name
`--transport`	`auto`	Transport: auto, socketcan, socketcanfd, dm-serial, dm-device
`--serial-port`	`/dev/ttyACM0`	Serial port (for dm-serial transport)
`--serial-baud`	`921600`	Serial baud rate
`--dm-device-type`	`usb2canfd-dual`	DM_Device adapter type (for dm-device transport): usb2canfd, usb2canfd-dual, linkx4c
`--dm-channel`	`0`	DM_Device channel. usb2canfd: 0; usb2canfd-dual: 0/1; linkx4c: 0/1/2/3. Omit on `scan` to scan all channels.
`--model`	`4340`	Motor model string
`--motor-id`	`0x01`	Motor CAN ID (hex supported)
`--feedback-id`	`0x11`	Feedback CAN ID (hex supported)
`--mode`	`mit`	Control mode: enable, disable, mit, pos-vel, pos-vel-pp, pos-vel-csp, vel, force-pos, ping, zero, set-zero, firmware-version, save, zero-by-offset, read-param, write-param
`--loop`	`100`	Number of control iterations
`--dt-ms`	`20`	Control period in milliseconds
`--ensure-mode`	`1`	Whether to ensure mode before control
`--ensure-strict`	`0`	Fail if mode switch fails
`--ensure-timeout-ms`	`1000`	Mode switch timeout
`--print-state`	`1`	Print state each iteration
`--pos`	`0.0`	Target position (rad)
`--vel`	`0.0`	Target velocity (rad/s)
`--kp`	`30.0`	Position stiffness (MIT mode)
`--loc-kp`	empty	RobStride `pos-vel` position-loop gain; falls back to `--kp` when omitted
`--kd`	`1.0`	Velocity damping (MIT mode)
`--tau`	`0.0`	Feedforward torque (Nm)
`--vlim`	`1.0`	Velocity limit (rad/s)
`--ratio`	`0.3`	Force ratio (force-pos mode)
`--zero-exp`	`0`	Enable RobStride experimental zero sequence (`1` to execute)
`--offset-negate`	`0`	Reserved for RobStride zero-by-offset; current firmware path is disabled
`--store`	`1`	Persist after `run --mode write-param` / zero sequence
`--param-id`	`0x0`	RobStride parameter ID for `run --mode read-param/write-param`
`--param-value`	empty	RobStride value for `run --mode write-param`
`--param-type`	inferred	RobStride type for `run --mode read-param/write-param`: i8, u8, u16, u32, f32
`--timeout-ms`	`500`	Parameter read/write timeout
`--set-motor-id`	empty	Damiao/RobStride Rust-style ID update shortcut
`--set-feedback-id`	empty	Damiao MST_ID update shortcut; RobStride feedback_id/host_id is not changed
`--verify-id`	`1`	Verify ID update
`--verify-model`	`1`	Damiao model handshake using PMAX/VMAX/TMAX before active control
`--verify-timeout-ms`	`500`	Damiao model/ID verification timeout
`--verify-tol`	`0.2`	Damiao 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 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

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

Option	Default	Description
`--vendor`	`damiao`	Vendor to scan: damiao, myactuator, robstride, hightorque, hexfellow, all
`--channel`	`can0`	CAN interface
`--transport`	`auto`	Transport type
`--serial-port`	`/dev/ttyACM0`	Serial port
`--serial-baud`	`921600`	Serial baud rate
`--model`	`4340`	Motor model
`--start-id`	`0x01`	Start ID for scan
`--end-id`	`0x10`	End ID for scan
`--feedback-ids`	`0xFD,0xFF,0xFE,0x00,0xAA`	RobStride host_id candidates to try; these are not motor/device IDs
`--feedback-base`	`0x10`	Damiao feedback ID base
`--timeout-ms`	`80`	Per-ID timeout
`--param-id`	`0x7019`	RobStride parameter ID for probe
`--param-timeout-ms`	`120`	RobStride 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

Option	Default	Description
`--vendor`	`damiao`	Must be damiao
`--channel`	`can0`	CAN interface
`--transport`	`auto`	Transport type
`--model`	`4340`	Motor model
`--motor-id`	`0x01`	Motor ID
`--feedback-id`	`0x11`	Feedback ID
`--timeout-ms`	`500`	Register read timeout
`--rids`	`7,8,9,10,21,22,23`	Register IDs to read

Register IDs

RID	Name	Description
7	MST_ID	Feedback ID
8	ESC_ID	Motor ID
9	TIMEOUT	Communication timeout
10	CTRL_MODE	Control mode
21	PMAX	Position mapping range
22	VMAX	Velocity mapping range
23	TMAX	Torque 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

Option	Default	Description
`--vendor`	`damiao`	`damiao` or `robstride`
`--channel`	`can0`	CAN interface
`--transport`	`auto`	Transport type
`--model`	`4340`	Motor model
`--motor-id`	`0x01`	Current motor ID
`--feedback-id`	`0x11`	Current 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
`--store`	`1`	Store to flash after write
`--verify`	`1`	Verify after write
`--timeout-ms`	`800`	Verify 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 (via new id)
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

Option	Default	Description
`--channel`	`can0`	CAN interface
`--transport`	`auto`	Transport: auto, socketcan, socketcanfd
`--model`	physical model	Physical RobStride model (`rs-00` through `rs-06`); required because parameter tables differ by model
`--motor-id`	`127`	Motor ID
`--feedback-id`	`0xFD`	RobStride 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-ms`	`500`	Read 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

Option	Default	Description
`--channel`	`can0`	CAN interface
`--transport`	`auto`	Transport: auto, socketcan, socketcanfd
`--model`	physical model	Physical RobStride model (`rs-00` through `rs-06`); required because parameter tables differ by model
`--motor-id`	`127`	Motor ID
`--feedback-id`	`0xFD`	RobStride 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`)
`--verify`	`1`	Read back and verify
`--store`	`0`	After a successful write/verify, send RobStride save-parameters (`type 22`)
`--timeout-ms`	`500`	Verify 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

Option	Default	Description
`--channel`	`can0`	CAN interface
`--transport`	`auto`	Transport: auto, socketcan, socketcanfd, dm-serial
`--model`	`4340`	Damiao model
`--motor-id`	`0x01`	Damiao ESC_ID
`--feedback-id`	`0x11`	Damiao MST_ID
`--param-id`	(required)	Register/parameter ID
`--type`	(required)	Data type: u32 or f32
`--timeout-ms`	`500`	Read 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

Option	Default	Description
`--channel`	`can0`	CAN interface
`--transport`	`auto`	Transport: auto, socketcan, socketcanfd, dm-serial
`--model`	`4340`	Damiao model
`--motor-id`	`0x01`	Damiao ESC_ID
`--feedback-id`	`0x11`	Damiao MST_ID
`--param-id`	(required)	Register/parameter ID
`--type`	(required)	Data type: u32 or f32
`--value`	(required)	Value to write
`--verify`	`1`	Read back after write
`--store`	`0`	After a successful write/verify, call Damiao `store_parameters()`
`--timeout-ms`	`500`	Verify 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

Code	Meaning
0	Success
1	General error
2	Invalid arguments

​API: motorbridge-cli

​Installation

​Global Options

​Commands Overview

​run

​Usage

​Options

​Mode-Parameter Mapping Notes

​Examples

​Enable Motor Only

​Disable Motor

​MIT Mode Control

​Position-Velocity Mode

​RobStride Motor

​RobStride Position-Velocity Mode

​RobStride Ping

​RobStride Zero (set-zero alias available)

​MyActuator Position-Velocity Mode

​Hexfellow MIT Mode (CAN-FD required)

​Using Serial Transport

​scan

​Usage

​Options

​Examples

​Scan All Vendors

​Scan Damiao Only

​Scan RobStride

​Scan MyActuator

​Scan HighTorque

​Scan Hexfellow (CAN-FD required)

​Scan via Serial

​Output Format

​id-dump

​Usage

​Options

​Register IDs

​Example

​Output

​id-set

​Usage

​Options

​Example

​Output

​robstride-read-param

​Usage

​Options

​Example

​Output

​robstride-write-param

​Usage

​Options

​Example

​Output

​damiao-read-param

​Usage

​Options

​Example

​damiao-write-param

​Usage

​Options

​Example

​Common Workflows

​Initial Setup

​Changing Motor ID

​RobStride Parameter Tuning

​Exit Codes

​See Also

API: motorbridge-cli

Installation

Global Options

Commands Overview

run

Usage

Options

Mode-Parameter Mapping Notes

Examples

Enable Motor Only

Disable Motor

MIT Mode Control

Position-Velocity Mode

RobStride Motor

RobStride Position-Velocity Mode

RobStride Ping

RobStride Zero (set-zero alias available)

MyActuator Position-Velocity Mode

Hexfellow MIT Mode (CAN-FD required)

Using Serial Transport

scan

Usage

Options

Examples

Scan All Vendors

Scan Damiao Only

Scan RobStride

Scan MyActuator

Scan HighTorque

Scan Hexfellow (CAN-FD required)

Scan via Serial

Output Format

id-dump

Usage

Options

Register IDs

Example

Output

id-set

Usage

Options

Example

Output

robstride-read-param

Usage

Options

Example

Output

robstride-write-param

Usage

Options

Example

Output

damiao-read-param

Usage

Options

Example

damiao-write-param

Usage

Options

Example

Common Workflows

Initial Setup

Changing Motor ID

RobStride Parameter Tuning

Exit Codes

See Also