API: Motor
Import
Class Overview
Motor instances are created by Controller.add_*_motor() methods. Do not instantiate directly.Lifecycle Methods
close()
Release motor handle resources. Called automatically when controller closes.
Parameters: None
Returns: None
Example:
enable()
Enable motor output (apply power to windings).
Parameters: None
Returns: None
Raises: CallError on failure
Example:
disable()
Disable motor output (release power, motor becomes free-spinning).
Parameters: None
Returns: None
Raises: CallError on failure
Example:
clear_error()
Clear any error state on the motor.
Parameters: None
Returns: None
Raises: CallError on failure
Example:
set_zero_position()
Set current position as zero reference point.
Parameters: None
Returns: None
Raises: CallError on failure
Example:
Mode Control
ensure_mode(mode, timeout_ms=1000)
Switch motor to specified control mode with timeout.
Parameters:
Returns:
None
Raises: CallError if mode switch fails or times out
Example:
Control Commands
send_mit(pos, vel, kp, kd, tau)
Send MIT mode control command. Provides full control over position, velocity, stiffness, damping, and torque.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
MyActuator does not support MIT mode. RobStride has limited MIT support.
send_pos_vel(pos, vlim)
Send position-velocity mode command. Motor moves to position with velocity limit.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
RobStride supports POS_VEL mode. A
vlim of 0 skips the limit_spd (0x7017) write, so the motor keeps its last set velocity limit; only loc_ref (0x7016) is written. Pass a non-zero vlim to update the limit. PP/CSP variants robstride_send_pos_vel_pp / robstride_send_pos_vel_csp follow the vendor manual PP/CSP sequences and apply the same > 0 guard to their velocity/acceleration registers; for high-rate loops use a prepared profile and write loc_ref directly each cycle.robstride_send_pos_vel_pp(pos, vel_max, acc_set) (RobStride)
Send RobStride PP (Profile Position) mode command. Motor moves to the target position via a profiled trajectory.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
robstride_send_pos_vel_csp(pos, vlim) (RobStride)
Send RobStride CSP (Cyclic Synchronous Position) mode command. Motor cyclically tracks the target position each cycle.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
PP and CSP both write the position target to
loc_ref (0x7016), but their velocity/acceleration registers differ: PP writes vel_max (0x7024) + acc_set (0x7025); CSP writes limit_spd (0x7017). The modes also differ: PP uses run_mode=1, CSP uses run_mode=5.send_vel(vel)
Send velocity mode command. Motor runs at constant velocity.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
Hexfellow does not support VEL mode.
send_force_pos(pos, vlim, ratio)
Send force position mode command. Compliant position control with force ratio.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
RobStride, MyActuator, and Hexfellow do not support FORCE_POS mode.
Feedback Methods
request_feedback()
Request fresh feedback frame from motor.
Parameters: None
Returns: None
Raises: CallError on failure
Example:
get_state()
Get cached motor state from last received feedback.
Parameters: None
Returns: MotorState | None — Motor state or None if no feedback received
Example:
CAN Configuration
set_can_timeout_ms(timeout_ms)
Set CAN communication timeout for this motor.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
Register Access (Damiao)
These methods are primarily for Damiao motors. See Register & Params Tutorial for register definitions and usage.write_register_f32(rid, value)
Write 32-bit float value to register.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
write_register_u32(rid, value)
Write 32-bit unsigned integer value to register.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
get_register_f32(rid, timeout_ms=1000)
Read 32-bit float value from register.
Parameters:
Returns:
float — Register value
Raises: CallError on failure or timeout
Example:
get_register_u32(rid, timeout_ms=1000)
Read 32-bit unsigned integer value from register.
Parameters:
Returns:
int — Register value
Raises: CallError on failure or timeout
Example:
store_parameters()
Save current parameters to motor’s non-volatile memory.
Parameters: None
Returns: None
Raises: CallError on failure
Example:
RobStride-Specific Methods
These methods are only available for RobStride motors.robstride_ping()
Ping RobStride motor to get device and responder IDs.
Parameters: None
Returns: tuple[int, int] — (device_id, responder_id)
Raises: CallError on failure
Example:
robstride_ping_host_id(host_id, timeout_ms=500)
Ping a RobStride motor using an explicit host-side ID. This host-id-specific path is used by the current scan flow when probing multiple possible feedback_id / host_id values.
Parameters: host_id: int, timeout_ms: int = 500
Returns: tuple[int, int] — (device_id, responder_id)
Raises: ValueError if host_id is outside 0..255; CallError on timeout or protocol failure
Example:
robstride_get_param_f32_host_id(param_id, host_id, timeout_ms=1000)
Read a RobStride f32 parameter while forcing the host-side ID used for the request. This is primarily for exact scan/commissioning flows where several host IDs are probed.
Parameters: param_id: int, host_id: int, timeout_ms: int = 1000
Returns: float
Raises: ValueError if host_id is outside 0..255; CallError on failure or timeout
Example:
robstride_set_device_id(new_device_id)
Set new device ID for RobStride motor.
Parameters:
Returns:
None
Raises: CallError on failure
Example:
robstride_write_param_*
Write typed parameter values to RobStride motor.
Example:
robstride_get_param_*
Read typed parameter values from RobStride motor.
Example:
robstride_write_param_i8(param_id, value)
Write signed 8-bit RobStride parameter.
Parameters: param_id: int, value: int
Returns: None
Raises: CallError on failure
robstride_write_param_u8(param_id, value)
Write unsigned 8-bit RobStride parameter.
Parameters: param_id: int, value: int
Returns: None
Raises: CallError on failure
robstride_write_param_u16(param_id, value)
Write unsigned 16-bit RobStride parameter.
Parameters: param_id: int, value: int
Returns: None
Raises: CallError on failure
robstride_write_param_u32(param_id, value)
Write unsigned 32-bit RobStride parameter.
Parameters: param_id: int, value: int
Returns: None
Raises: CallError on failure
robstride_write_param_f32(param_id, value)
Write 32-bit float RobStride parameter.
Parameters: param_id: int, value: float
Returns: None
Raises: CallError on failure
robstride_get_param_i8(param_id, timeout_ms=1000)
Read signed 8-bit RobStride parameter.
Parameters: param_id: int, timeout_ms: int = 1000
Returns: int
Raises: CallError on failure or timeout
robstride_get_param_u8(param_id, timeout_ms=1000)
Read unsigned 8-bit RobStride parameter.
Parameters: param_id: int, timeout_ms: int = 1000
Returns: int
Raises: CallError on failure or timeout
robstride_get_param_u16(param_id, timeout_ms=1000)
Read unsigned 16-bit RobStride parameter.
Parameters: param_id: int, timeout_ms: int = 1000
Returns: int
Raises: CallError on failure or timeout
robstride_get_param_u32(param_id, timeout_ms=1000)
Read unsigned 32-bit RobStride parameter.
Parameters: param_id: int, timeout_ms: int = 1000
Returns: int
Raises: CallError on failure or timeout
robstride_get_param_f32(param_id, timeout_ms=1000)
Read 32-bit float RobStride parameter.
Parameters: param_id: int, timeout_ms: int = 1000
Returns: float
Raises: CallError on failure or timeout
Damiao Typed Param Methods
These methods provide typed parameter read/write paths for Damiao byparam_id.
damiao_write_param_f32(param_id, value)
Write 32-bit float Damiao parameter.
Parameters: param_id: int, value: float
Returns: None
Raises: CallError on failure
damiao_write_param_u32(param_id, value)
Write unsigned 32-bit Damiao parameter.
Parameters: param_id: int, value: int
Returns: None
Raises: CallError on failure
damiao_get_param_f32(param_id, timeout_ms=1000)
Read 32-bit float Damiao parameter.
Parameters: param_id: int, timeout_ms: int = 1000
Returns: float
Raises: CallError on failure or timeout
damiao_get_param_u32(param_id, timeout_ms=1000)
Read unsigned 32-bit Damiao parameter.
Parameters: param_id: int, timeout_ms: int = 1000
Returns: int
Raises: CallError on failure or timeout
Complete Example
See Also
- Controller API - Controller methods
- Mode and State - Mode enum and MotorState class
- Vendor Capability Matrix - Vendor-specific feature support