电机

MotorsBus 是串行总线上串联舵机的底层接口。机器人使用它来读取位置 并写入目标位置；除非你要添加硬件，否则很少会直接接触它。

有关添加新总线，请参阅 自带硬件， 有关特定设备的说明，请参阅 更新 Feetech 固件 和 Damiao 电机与 CAN 总线。

MotorsBus

class lerobot.motors.motors_bus.SerialMotorsBus

< >

( port: strmotors: dict[str, Motor]calibration: dict[str, MotorCalibration] | None = None )

SerialMotorsBus 允许高效地读取和写入通过串行通信连接的电机。 它代表多个菊花链式连接并通过串口连接的电机。 目前该类有两种实现：

  • DynamixelMotorsBus
  • FeetechMotorsBus

该类专门用于基于串行的电机协议（Dynamixel、Feetech 等）。

MotorsBus 子类的实例需要一个端口（例如 FeetechMotorsBus(port="/dev/tty.usbmodem575E0031751"）。

要查找端口，你可以运行我们的实用脚本：

lerobot-find-port.py
>>> Finding all available ports for the MotorsBus.
>>> ["/dev/tty.usbmodem575E0032081", "/dev/tty.usbmodem575E0031751"]
>>> Remove the usb cable from your MotorsBus and press Enter when done.
>>> The port of this MotorsBus is /dev/tty.usbmodem575E0031751.
>>> Reconnect the usb cable.

将 1 个 Feetech sts3215 电机连接到总线的用法示例：

bus = FeetechMotorsBus(
    port="/dev/tty.usbmodem575E0031751",
    motors={"my_motor": (1, "sts3215")},
)
bus.connect()

position = bus.read("Present_Position", "my_motor", normalize=False)

# Move from a few motor steps as an example
few_steps = 30
bus.write("Goal_Position", "my_motor", position + few_steps, normalize=False)

# When done, properly disconnect the port using
bus.disconnect()

broadcast_ping

< >

( num_retry: int = 0raise_on_error: bool = False ) → dict[int, int] | None

参数

  • num_retry (int, optional) — 重试次数。默认值为 0。
  • raise_on_error (bool, optional) — 当为 True 时，失败会抛出异常，而不是返回 None。默认值为 False。

返回

dict[int, int] | None

映射 id → 型号，如果调用失败则为 None。

使用广播地址 ping 总线上的每个 ID。

configure_motors

< >

( )

将实现特定的推荐设置写入每个电机。

典型的更改包括缩短返回延迟、提高 加速度限制或禁用安全锁。

connect

< >

( handshake: bool = True )

参数

  • handshake (bool, optional) — Ping 每个预期的电机，并执行 该实现特有的额外完整性检查。默认值为 True。

抛出异常

DeviceAlreadyConnectedError or ConnectionError

  • DeviceAlreadyConnectedError — 端口已打开。
  • ConnectionError — 底层 SDK 打开端口失败，或握手未成功。

打开串口并初始化通信。

disable_torque

< >

( motors: str | list[str] | None = Nonenum_retry: int = 0 )

参数

  • motors ( str | list[str] | None, optional) — 目标电机。接受电机名称、ID、名称列表或 None 以影响所有已注册的电机。默认值为 None。
  • num_retry (int, optional) — 通信失败时的额外重试次数。 默认值为 0。

禁用所选电机的力矩。

禁用力矩可以写入电机的永久存储区（EPROM/EEPROM）。

disconnect

< >

( disable_torque: bool = True )

参数

  • disable_torque (bool, optional) — 如果为 True（默认），则在关闭端口前禁用每个电机的力矩。 这可以防止断开连接后电机仍施以抵抗力矩而损坏。

关闭串口（可选地先禁用力矩）。

enable_torque

< >

( motors: int | str | list[str] | None = Nonenum_retry: int = 0 )

参数

  • motors (int | str | list[str] | None, optional) — 与 :pymeth:disable_torque 语义相同。 默认值为 None。
  • num_retry (int, optional) — 通信失败时的额外重试次数。 默认值为 0。

启用所选电机的力矩。

get_baudrate

< >

( ) → int

返回

int

以位/秒为单位的波特率。

返回端口上配置的当前波特率。

ping

< >

( motor: NameOrIDnum_retry: int = 0raise_on_error: bool = False ) → int | None

参数

  • motor (NameOrID) — 目标电机（名称或 ID）。
  • num_retry (int, optional) — 放弃前的额外尝试次数。默认值为 0。
  • raise_on_error (bool, optional) — 如果为 True，通信错误会抛出异常，而不是返回 None。默认值为 False。

返回

int | None

电机型号，失败时为 None。

Ping 单个电机并返回其型号。

read

< >

( data_name: strmotor: strnormalize: bool = Truenum_retry: int = 0 ) → Value

参数

  • data_name (str) — 控制表键（例如 "Present_Position"）。
  • motor (str) — 电机名称。
  • normalize (bool, optional) — 当为 True（默认）时，将值缩放到 calibration 定义的用户友好范围。
  • num_retry (int, optional) — 重试次数。默认值为 0。

返回

Value

根据 normalize 返回原始值或归一化值。

从电机读取一个寄存器。

read_calibration

< >

( ) → dict[str, MotorCalibration]

返回

dict[str, MotorCalibration]

映射 电机名称 → calibration。

从电机读取 calibration 参数。

record_ranges_of_motion

< >

( motors: NameOrID | Sequence[NameOrID] | None = Nonedisplay_values: bool = True ) → tuple[dict[str, Value], dict[str, Value]]

参数

  • motors (NameOrID | list[NameOrID] | None, optional) — 要记录的电机。 默认记录所有电机（None）。
  • display_values (bool, optional) — 当为 True（默认）时，控制台会打印实时表格。

返回

tuple[dict[str, Value], dict[str, Value]]

两个字典 mins 和 maxes，包含 每个电机观测到的极值。

以交互方式记录每个电机的最小/最大编码器值。

在方法实时输出位置的同时，用手移动关节（禁用力矩）。按 :kbd:Enter 完成。

reset_calibration

< >

( motors: NameOrID | Sequence[NameOrID] | None = None )

参数

  • motors (NameOrID | Sequence[NameOrID] | None, optional) — 电机选择。None（默认） 重置所有电机。

恢复所选电机的出厂 calibration。

零位偏移设置为 0，最小/最大位置限制设置为完整可用范围。 内存中的 :pyattr:calibration 会被清除。

scan_port

< >

( port: str*args**kwargs ) → dict[int, list[int]]

参数

  • port (str) — 要扫描的串口/USB 端口（例如 "/dev/ttyUSB0"）。
  • *args, **kwargs — 转发给子类构造函数。

返回

dict[int, list[int]]

映射 波特率 → 电机 ID 列表 对每个至少产生一个响应的波特率。

以所有支持的波特率探测 port，并列出响应的 ID。

set_baudrate

< >

( baudrate: int )

参数

  • baudrate (int) — 所需的波特率，以位/秒为单位。

抛出异常

RuntimeError

  • RuntimeError — SDK 未能应用更改。

在端口上设置新的 UART 波特率。

set_half_turn_homings

< >

( motors: NameOrID | Sequence[NameOrID] | None = None ) → dict[str, Value]

参数

  • motors (NameOrID | list[NameOrID] | None, optional) — 要调整的电机。默认调整所有电机（None）。

返回

dict[str, Value]

映射 电机名称 → 写入的零位偏移。

将每个电机的范围以当前位置为中心对齐。

该函数计算并写入一个零位偏移，使当前位置恰好变为 半圈（例如 12 位编码器上的 2047）。

set_timeout

< >

( timeout_ms: int | None = None )

参数

  • timeout_ms (int | None, optional) — 以 毫秒 为单位的超时时间。如果为 None（默认），该方法会 回退到 :pyattr:default_timeout。

更改 SDK 使用的数据包超时时间。

setup_motor

< >

( motor: strinitial_baudrate: int | None = Noneinitial_id: int | None = None )

参数

  • motor (str) — 电机在 :pyattr:motors 中的键。
  • initial_baudrate (int | None, optional) — 当前波特率（提供时跳过扫描）。 默认值为 None。
  • initial_id (int | None, optional) — 当前 ID（提供时跳过扫描）。默认值为 None。

抛出异常

RuntimeError or ConnectionError

  • RuntimeError — 找不到该电机，或其型号 与预期型号不匹配。
  • ConnectionError — 与电机的通信失败。

为单个电机分配正确的 ID 和波特率。

该辅助函数会临时切换到电机的当前设置，禁用力矩，设置所需的 ID，最后写入总线的默认波特率。

sync_read

< >

( data_name: strmotors: NameOrID | Sequence[NameOrID] | None = Nonenormalize: bool = Truenum_retry: int = 0 ) → dict[str, Value]

参数

  • data_name (str) — 寄存器名称。
  • motors (NameOrID | Sequence[NameOrID] | None, optional) — 要查询的电机。None（默认）读取每个电机。
  • normalize (bool, optional) — 归一化标志。默认值为 True。
  • num_retry (int, optional) — 重试次数。默认值为 0。

返回

dict[str, Value]

映射 电机名称 → 值。

同时从多个电机读取同一寄存器。

sync_write

< >

( data_name: strvalues: Value | dict[str, Value]normalize: bool = Truenum_retry: int = 0 )

参数

  • data_name (str) — 寄存器名称。
  • values (Value | dict[str, Value]) — 可以是单个值（应用于每个电机），也可以是映射 电机名称 → 值。
  • normalize (bool, optional) — 如果为 True（默认），将值从用户范围转换为原始单位。
  • num_retry (int, optional) — 重试次数。默认值为 0。

在多个电机上写入同一寄存器。

与 :pymeth:write 不同，此方法 不 期望电机发出响应 state 包，因此 可能允许数据包丢失。它比 :pymeth:write 更快，通常应在 频率重要且丢失部分数据包可接受时使用（例如 teleoperation 循环）。

torque_disabled

< >

( motors: str | list[str] | None = None )

保证力矩被重新启用的上下文管理器。

在配置电机时，该辅助函数可用于暂时禁用力矩。

Examples:

with bus.torque_disabled(): … # Safe operations here … pass

write

< >

( data_name: strmotor: strvalue: Valuenormalize: bool = Truenum_retry: int = 0 )

参数

  • data_name (str) — 寄存器名称。
  • motor (str) — 电机名称。
  • value (Value) — 要写入的值。如果 normalize 为 True，该值会先转换为原始 单位。
  • normalize (bool, optional) — 启用或禁用归一化。默认值为 True。
  • num_retry (int, optional) — 重试次数。默认值为 0。

向单个电机的寄存器写入一个值。

与 :pymeth:sync_write 不同，此方法期望电机发出响应 state 包，这 提供了值已成功写入寄存器的保证。因此，它比 :pymeth:sync_write 慢，但更可靠。通常应在配置 电机时使用。

write_calibration

< >

( calibration_dict: dict[str, MotorCalibration]cache: bool = True )

参数

  • calibration_dict (dict[str, MotorCalibration]) — 从 :pymeth:read_calibration 获得的或由用户构建的 calibration。
  • cache (bool, optional) — 将 calibration 保存到 :pyattr:calibration。默认值为 True。

将 calibration 参数写入电机，并可选地缓存它们。

Motor

class lerobot.motors.Motor

< >

( id: intmodel: strnorm_mode: MotorNormModemotor_type_str: str | None = Nonerecv_id: int | None = None )

MotorCalibration

class lerobot.motors.MotorCalibration

< >

( id: intdrive_mode: inthoming_offset: intrange_min: intrange_max: int )

MotorNormMode

class lerobot.motors.MotorNormMode

< >

( *values )

在 GitHub 上更新