Motor 电机 - MotorBridge Python SDK

导入

from motorbridge import Motor  # 通常通过 Controller.add_*_motor() 获取

Motor 实例由 Controller.add_*_motor() 方法创建。请勿直接实例化。

生命周期方法

`close()`

释放电机句柄资源。控制器关闭时自动调用。 参数： 无 返回： None 示例：

motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
try:
    # ... 使用电机
finally:
    motor.close()

`enable()`

使能电机输出（给绕组通电）。 参数： 无 返回： None 抛出： CallError 失败时

`disable()`

禁用电机输出（断电，电机变为自由旋转）。 参数： 无 返回： None 抛出： CallError 失败时

`clear_error()`

清除电机上的任何错误状态。 参数： 无 返回： None 抛出： CallError 失败时

`set_zero_position()`

将当前位置设置为零参考点。 参数： 无 返回： None 抛出： CallError 失败时

这会修改电机的内部位置参考。在多电机系统中请谨慎使用。

模式控制

`ensure_mode(mode, timeout_ms=1000)`

将电机切换到指定的控制模式（带超时）。 参数：

名称	类型	默认值	描述
`mode`	`Mode`	必需	目标控制模式
`timeout_ms`	`int`	`1000`	超时时间（毫秒）

返回： None 抛出： CallError 如果模式切换失败或超时

控制命令

`send_mit(pos, vel, kp, kd, tau)`

发送 MIT 模式控制命令。提供对位置、速度、刚度、阻尼和力矩的完全控制。 参数：

名称	类型	描述
`pos`	`float`	目标位置（弧度）
`vel`	`float`	目标速度（rad/s）
`kp`	`float`	位置刚度（Nm/rad）
`kd`	`float`	速度阻尼（Nm·s/rad）
`tau`	`float`	前馈力矩（Nm）

返回： None 抛出： CallError 失败时

MyActuator 不支持 MIT 模式。RobStride 的 MIT 支持有限。

`send_pos_vel(pos, vlim)`

发送位置-速度模式命令。电机以受限速度移动到目标位置。 参数：

名称	类型	描述
`pos`	`float`	目标位置（弧度）
`vlim`	`float`	速度限制（rad/s）

返回： None 抛出： CallError 失败时

RobStride 支持 POS_VEL 模式。vlim 为 0 时跳过 limit_spd（0x7017）写入，电机保留上次设置的速度限制，仅写 loc_ref（0x7016）；需更新速度限制时传非零 vlim。PP/CSP 变体 robstride_send_pos_vel_pp / robstride_send_pos_vel_csp 遵循厂商手册 PP/CSP 序列，对其速度/加速度寄存器同样应用 > 0 守卫；高速循环请使用预备 profile，每周期直接写 loc_ref。

`robstride_send_pos_vel_pp(pos, vel_max, acc_set)`（RobStride）

发送 PP模式命令，电机以受限速度和加速度移动到目标位置。 参数：

名称	类型	描述
`pos`	`float`	目标位置（弧度）→ 写 `loc_ref`（`0x7016`）
`vel_max`	`float`	最大速度（rad/s）→ 写 `vel_max`（`0x7024`）
`acc_set`	`float`	加速度（rad/s²）→ 写 `acc_set`（`0x7025`）

返回： None 抛出： CallError 失败时

`robstride_send_pos_vel_csp(pos, vlim)`（RobStride）

发送 CSP模式命令，电机以受限速度移动到目标位置。 参数：

名称	类型	描述
`pos`	`float`	目标位置（弧度）→ 写 `loc_ref`（`0x7016`）
`vlim`	`float`	速度限制（rad/s）→ 写 `limit_spd`（`0x7017`）

返回： None 抛出： CallError 失败时

PP 与 CSP 都把位置目标写入 loc_ref（0x7016），但速度/加速度寄存器不同：PP 写 vel_max（0x7024）与 acc_set（0x7025），CSP 写 limit_spd（0x7017）。模式也不同：PP 用 run_mode=1，CSP 用 run_mode=5。

`send_vel(vel)`

发送速度模式命令。电机以恒定速度运行。 参数：

名称	类型	描述
`vel`	`float`	目标速度（rad/s）

返回： None 抛出： CallError 失败时

Hexfellow 不支持 VEL 模式。

`send_force_pos(pos, vlim, ratio)`

发送力位置模式命令。带力比例的柔顺位置控制。 参数：

名称	类型	描述
`pos`	`float`	目标位置（弧度）
`vlim`	`float`	速度限制（rad/s）
`ratio`	`float`	力比例（0.0-1.0）

返回： None 抛出： CallError 失败时

RobStride、MyActuator 和 Hexfellow 不支持 FORCE_POS 模式。

反馈方法

`request_feedback()`

请求电机发送新鲜反馈帧。 参数： 无 返回： None 抛出： CallError 失败时

`get_state()`

获取上次收到反馈的缓存电机状态。 参数： 无 返回： MotorState | None — 电机状态，如果尚未收到反馈则为 None

CAN 配置

`set_can_timeout_ms(timeout_ms)`

设置此电机的 CAN 通信超时时间。 参数：

名称	类型	默认值	描述
`timeout_ms`	`int`	必需	超时时间（毫秒）

返回： None 抛出： CallError 失败时 示例：

motor.set_can_timeout_ms(100)  # 100ms 超时

寄存器访问（达妙）

这些方法主要用于达妙电机。

`write_register_f32(rid, value)`

向寄存器写入 32 位浮点值。 参数：

名称	类型	描述
`rid`	`int`	寄存器 ID
`value`	`float`	要写入的值

返回： None 抛出： CallError 失败时

`write_register_u32(rid, value)`

向寄存器写入 32 位无符号整数值。 参数：

名称	类型	描述
`rid`	`int`	寄存器 ID
`value`	`int`	要写入的值

返回： None 抛出： CallError 失败时

`get_register_f32(rid, timeout_ms=1000)`

从寄存器读取 32 位浮点值。 参数：

名称	类型	默认值	描述
`rid`	`int`	必需	寄存器 ID
`timeout_ms`	`int`	`1000`	超时时间（毫秒）

返回： float — 寄存器值 抛出： CallError 失败或超时时

`get_register_u32(rid, timeout_ms=1000)`

从寄存器读取 32 位无符号整数值。 参数：

名称	类型	默认值	描述
`rid`	`int`	必需	寄存器 ID
`timeout_ms`	`int`	`1000`	超时时间（毫秒）

返回： int — 寄存器值 抛出： CallError 失败或超时时

`store_parameters()`

将当前参数保存到电机的非易失性存储器。 参数： 无 返回： None 抛出： CallError 失败时

RobStride 专用方法

`robstride_ping()`

Ping RobStride 电机以获取设备和响应者 ID。 参数： 无 返回： tuple[int, int] — (device_id, responder_id) 抛出： CallError 失败时

`robstride_ping_host_id(host_id, timeout_ms=500)`

使用明确的主机侧 ID ping RobStride 电机。当前扫描流程使用这个 host-id 精确路径，适合逐个探测多个 feedback_id / host_id 候选值。 参数： host_id: int, timeout_ms: int = 500 返回： tuple[int, int]，即 (device_id, responder_id) 抛出： host_id 不在 0..255 时抛出 ValueError；通信失败或超时时抛出 CallError 示例：

device_id, responder_id = motor.robstride_ping_host_id(0xFD, timeout_ms=80)
print(f"Device: {device_id}, Responder: {responder_id}")

`robstride_get_param_f32_host_id(param_id, host_id, timeout_ms=1000)`

用指定主机侧 ID 读取 RobStride 的 f32 参数。主要用于扫描和调试流程，避免多个 host_id 候选之间隐式回退造成混淆。 参数： param_id: int, host_id: int, timeout_ms: int = 1000 返回： float 抛出： host_id 不在 0..255 时抛出 ValueError；通信失败或超时时抛出 CallError 示例：

value = motor.robstride_get_param_f32_host_id(0x7019, 0xFD, timeout_ms=120)
print(value)

`robstride_set_device_id(new_device_id)`

为 RobStride 电机设置新的设备 ID。 参数：

名称	类型	描述
`new_device_id`	`int`	新设备 ID

返回： None 抛出： CallError 失败时

`robstride_write_param_*`

向 RobStride 电机写入类型化参数值。

方法	类型
`robstride_write_param_i8(param_id, value)`	`int`（有符号 8 位）
`robstride_write_param_u8(param_id, value)`	`int`（无符号 8 位）
`robstride_write_param_u16(param_id, value)`	`int`（无符号 16 位）
`robstride_write_param_u32(param_id, value)`	`int`（无符号 32 位）
`robstride_write_param_f32(param_id, value)`	`float`

`robstride_get_param_*`

从 RobStride 电机读取类型化参数值。

方法	返回类型
`robstride_get_param_i8(param_id, timeout_ms=1000)`	`int`
`robstride_get_param_u8(param_id, timeout_ms=1000)`	`int`
`robstride_get_param_u16(param_id, timeout_ms=1000)`	`int`
`robstride_get_param_u32(param_id, timeout_ms=1000)`	`int`
`robstride_get_param_f32(param_id, timeout_ms=1000)`	`float`

`robstride_write_param_i8(param_id, value)`

写入 RobStride 有符号 8 位参数。 参数： param_id: int, value: int 返回： None 抛出： CallError 失败时

`robstride_write_param_u8(param_id, value)`

写入 RobStride 无符号 8 位参数。 参数： param_id: int, value: int 返回： None 抛出： CallError 失败时

`robstride_write_param_u16(param_id, value)`

写入 RobStride 无符号 16 位参数。 参数： param_id: int, value: int 返回： None 抛出： CallError 失败时

`robstride_write_param_u32(param_id, value)`

写入 RobStride 无符号 32 位参数。 参数： param_id: int, value: int 返回： None 抛出： CallError 失败时

`robstride_write_param_f32(param_id, value)`

写入 RobStride 32 位浮点参数。 参数： param_id: int, value: float 返回： None 抛出： CallError 失败时

`robstride_get_param_i8(param_id, timeout_ms=1000)`

读取 RobStride 有符号 8 位参数。 参数： param_id: int, timeout_ms: int = 1000 返回： int 抛出： CallError 失败或超时时

`robstride_get_param_u8(param_id, timeout_ms=1000)`

读取 RobStride 无符号 8 位参数。 参数： param_id: int, timeout_ms: int = 1000 返回： int 抛出： CallError 失败或超时时

`robstride_get_param_u16(param_id, timeout_ms=1000)`

读取 RobStride 无符号 16 位参数。 参数： param_id: int, timeout_ms: int = 1000 返回： int 抛出： CallError 失败或超时时

`robstride_get_param_u32(param_id, timeout_ms=1000)`

读取 RobStride 无符号 32 位参数。 参数： param_id: int, timeout_ms: int = 1000 返回： int 抛出： CallError 失败或超时时

`robstride_get_param_f32(param_id, timeout_ms=1000)`

读取 RobStride 32 位浮点参数。 参数： param_id: int, timeout_ms: int = 1000 返回： float 抛出： CallError 失败或超时时

达妙 Typed 参数方法

这些方法提供基于 param_id 的达妙参数读写路径。

`damiao_write_param_f32(param_id, value)`

写入达妙 32 位浮点参数。 参数： param_id: int, value: float 返回： None 抛出： CallError 失败时

`damiao_write_param_u32(param_id, value)`

写入达妙无符号 32 位参数。 参数： param_id: int, value: int 返回： None 抛出： CallError 失败时

`damiao_get_param_f32(param_id, timeout_ms=1000)`

读取达妙 32 位浮点参数。 参数： param_id: int, timeout_ms: int = 1000 返回： float 抛出： CallError 失败或超时时

`damiao_get_param_u32(param_id, timeout_ms=1000)`

读取达妙无符号 32 位参数。 参数： param_id: int, timeout_ms: int = 1000 返回： int 抛出： CallError 失败或超时时

另见

Controller API - 控制器方法
Mode and State - Mode 枚举和 MotorState 类
厂商能力矩阵 - 厂商特性支持

​导入

​生命周期方法

​close()

​enable()

​disable()

​clear_error()

​set_zero_position()

​模式控制

​ensure_mode(mode, timeout_ms=1000)

​控制命令

​send_mit(pos, vel, kp, kd, tau)

​send_pos_vel(pos, vlim)

​robstride_send_pos_vel_pp(pos, vel_max, acc_set)（RobStride）

​robstride_send_pos_vel_csp(pos, vlim)（RobStride）

​send_vel(vel)

​send_force_pos(pos, vlim, ratio)

​反馈方法

​request_feedback()

​get_state()

​CAN 配置

​set_can_timeout_ms(timeout_ms)

​寄存器访问（达妙）

​write_register_f32(rid, value)

​write_register_u32(rid, value)

​get_register_f32(rid, timeout_ms=1000)

​get_register_u32(rid, timeout_ms=1000)

​store_parameters()

​RobStride 专用方法

​robstride_ping()

​robstride_ping_host_id(host_id, timeout_ms=500)

​robstride_get_param_f32_host_id(param_id, host_id, timeout_ms=1000)

​robstride_set_device_id(new_device_id)

​robstride_write_param_*

​robstride_get_param_*

​robstride_write_param_i8(param_id, value)

​robstride_write_param_u8(param_id, value)

​robstride_write_param_u16(param_id, value)

​robstride_write_param_u32(param_id, value)

​robstride_write_param_f32(param_id, value)

​robstride_get_param_i8(param_id, timeout_ms=1000)

​robstride_get_param_u8(param_id, timeout_ms=1000)

​robstride_get_param_u16(param_id, timeout_ms=1000)

​robstride_get_param_u32(param_id, timeout_ms=1000)

​robstride_get_param_f32(param_id, timeout_ms=1000)

​达妙 Typed 参数方法

​damiao_write_param_f32(param_id, value)

​damiao_write_param_u32(param_id, value)

​damiao_get_param_f32(param_id, timeout_ms=1000)

​damiao_get_param_u32(param_id, timeout_ms=1000)

​另见

导入

生命周期方法

`close()`

`enable()`

`disable()`

`clear_error()`

`set_zero_position()`

模式控制

`ensure_mode(mode, timeout_ms=1000)`

控制命令

`send_mit(pos, vel, kp, kd, tau)`

`send_pos_vel(pos, vlim)`

`robstride_send_pos_vel_pp(pos, vel_max, acc_set)`（RobStride）

`robstride_send_pos_vel_csp(pos, vlim)`（RobStride）

`send_vel(vel)`

`send_force_pos(pos, vlim, ratio)`

反馈方法

`request_feedback()`

`get_state()`

CAN 配置

`set_can_timeout_ms(timeout_ms)`

寄存器访问（达妙）

`write_register_f32(rid, value)`

`write_register_u32(rid, value)`

`get_register_f32(rid, timeout_ms=1000)`

`get_register_u32(rid, timeout_ms=1000)`

`store_parameters()`

RobStride 专用方法

`robstride_ping()`

`robstride_ping_host_id(host_id, timeout_ms=500)`

`robstride_get_param_f32_host_id(param_id, host_id, timeout_ms=1000)`

`robstride_set_device_id(new_device_id)`

`robstride_write_param_*`

`robstride_get_param_*`

`robstride_write_param_i8(param_id, value)`

`robstride_write_param_u8(param_id, value)`

`robstride_write_param_u16(param_id, value)`

`robstride_write_param_u32(param_id, value)`

`robstride_write_param_f32(param_id, value)`

`robstride_get_param_i8(param_id, timeout_ms=1000)`

`robstride_get_param_u8(param_id, timeout_ms=1000)`

`robstride_get_param_u16(param_id, timeout_ms=1000)`

`robstride_get_param_u32(param_id, timeout_ms=1000)`

`robstride_get_param_f32(param_id, timeout_ms=1000)`

达妙 Typed 参数方法

`damiao_write_param_f32(param_id, value)`

`damiao_write_param_u32(param_id, value)`

`damiao_get_param_f32(param_id, timeout_ms=1000)`

`damiao_get_param_u32(param_id, timeout_ms=1000)`

另见