LeRobot documentation
モーター
モーター
SerialMotorsBus は、シリアルバス上の Feetech または Dynamixel サーボのチェーンに対する低レベルインターフェースです。ロボットはこれを使用して位置を読み取り、目標位置を書き込みます。ハードウェアの追加を行わない限り、直接触れることはほとんどありません。各モーターのモデルは、制御テーブルやファミリー間で異なる事実を保持し、シリアルポートも所有する rustypot で参照されます。FeetechMotorsBus と DynamixelMotorsBus は、1リリースの間だけ残された非推奨のエイリアスです。
SDKベースのバスからの移行
エイリアスは、旧SDKの属性やモデルテーブルではなく、クラス名を保持します:
bus.model_resolution_table[model]はbus.resolution(model)となり、その他のモデルテーブル（model_ctrl_table、model_number_tableなど）は、rustypot のサーボ定義として扱われます。- 動作モードは、
Operating_ModeレジスタにOperatingModeの値を書き込むのではなく、bus.set_operating_mode("position")のように名前を指定して選択します。 - SDKのポートとパケットハンドラーはもはや公開されていません: rustypotがシリアルポートを所有します。
protocol_versionは無視されます。各モーターのモデルがプロトコルを指定します。
See Bring Your Own Hardware for adding a new bus, and Updating Feetech Firmware and Damiao Motors and CAN Bus for device-specific notes.
SerialMotorsBus
class lerobot.motors.SerialMotorsBus
< source >( port: strmotors: dict[str, Motor]calibration: dict[str, MotorCalibration] | None = None )
1つのシリアルポートにデイジーチェーン接続されたFeetechまたはDynamixelのサーボチェーンを読み書きします。
rustypot は各モデルのメタデータ（制御テーブル、解像度、ボーレート、動作モード）およびシリアル I/O を処理し、LeRobot は正規化、キャリブレーション、推奨設定を処理します。STS と SCS、または XL430 と XL330 のように、複数のモデルのモーターがポートを共有する場合があります。
ポートを見つけるには、次のコマンドを実行します:
lerobot-find-port
>>> 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.バス上の単一のFeetech sts3215の例:
from lerobot.motors import Motor, MotorNormMode, SerialMotorsBus
bus = SerialMotorsBus(
port="/dev/tty.usbmodem575E0031751",
motors={"my_motor": Motor(1, "sts3215", MotorNormMode.RANGE_M100_100)},
)
bus.connect()
position = bus.read("Present_Position", "my_motor", normalize=False)
# Move a few motor steps as an example
bus.write("Goal_Position", "my_motor", position + 30, normalize=False)
bus.disconnect()configure_motors
< source >( return_delay_time: int = 0maximum_acceleration: int = 254acceleration: int = 254 )
LeRobotが推奨する設定をすべてのモーターに書き込みます。
connect
< source >( handshake: bool = True )
パラメータ
- handshake (
bool、省略可、デフォルトはTrue) — すべてのモーターがそのモデルのモデル番号で応答すること、および1つの定義内の Feetech モーターが1つのファームウェアで動作することをチェックするかどうかを指定します。
例外
DeviceAlreadyConnectedError または ConnectionError または RuntimeError
DeviceAlreadyConnectedError— ポートがすでに開いている場合。ConnectionError— ポートをオープンできなかった場合。RuntimeError— ハンドシェイクが失敗した場合。ポートは再度閉じられます。
シリアルポートを開き、モーターを確認します。
disable_torque
< source >( motors: NameOrID | Sequence[NameOrID] | None = Nonenum_retry: int = 0 )
選択したモーターのトルクを無効にします。
トルクをオフにすると、モーターのEEPROMに書き込みが可能になり、Feetechモーターのロックが解除されます。選択されたすべてのモーターに対して試行が行われ、失敗は報告されます。応答のないモーターはトルクが有効なまま残る可能性があります。
切断
< source >( disable_torque: bool = True )
デフォルトでは、すべてのモーターのトルクをオフにしてシリアルポートを閉じます。
すでに切断されているバスに対して呼び出すことは安全であり、トルクの無効化が失敗した場合でもポートは解放されます。
enable_torque
< source >( motors: NameOrID | Sequence[NameOrID] | None = Nonenum_retry: int = 0 )
選択したモーターのトルクを有効にし、Feetechモーターのロックを解除します。
ping
< source >( motor: NameOrIDnum_retry: int = 0 ) → int | None
モーターが応答するモデル番号。
Model_Numberを読み取ってpingを送信する代わりに、存在確認とIDの取得を2回の往復ではなく1回の往復で済ませます。
読み取り
< source >( data_name: strmotor: strnormalize: bool = Truenum_retry: int = 0 ) → int | float
パラメータ
- data_name (
str) — 登録名。例:"Present_Position"。大文字と小文字は区別されません。 - motor (
str) — モーター名。 - normalize (
bool、省略可能、デフォルトはTrue) — キャリブレーションとノームモードで定義される範囲に位置をスケーリングするかどうか。 - num_retry (
int、任意、デフォルトは0) — 通信失敗後の追加試行回数。
戻り値
int | float
生の値、または正規化された値。
例外
ConnectionError または RuntimeError
ConnectionError— モーターが応答しない場合。RuntimeError— モーターが読み取りを拒否した場合に発生します。過負荷などのステータスにアラームが発生しても、例外は引き起こされません。
1つのモーターのレジスタを読み取ります。
read_calibration
< source >( ) → dict[str, MotorCalibration]
戻り値
dict[str, MotorCalibration]
各モーターの名前によるキャリブレーション。
すべてのモーターのキャリブレーションを読み取ります。
ホーミングオフセットレジスタを持たないモーター（Feetech SCS）は 0 を報告し、Drive_Mode レジスタを持たないもの（Feetech）はドライブモード 0 を報告します。
record_calibration
< source >( mode: strfull_turn_motors: Sequence[str]inverted_motors: Sequence[str] = ()motors: Sequence[str] | None = None ) → dict[str, MotorCalibration]
パラメータ
- mode (
str) — モーターの動作モード。例:"position"。 - full_turn_motors (
Sequence[str]) — 移動する範囲ではなく、エンコーダー全体の範囲が与えられるモーター。 - inverted_motors (
Sequence[str]、任意、デフォルトは()) — 逆方向に回転するモーター。 - motors (
Sequence[str]、省略可) — キャリブレーションを行うモーター。Noneを指定すると、すべてのモーターがキャリブレーションされます。
戻り値
dict[str, MotorCalibration]
バス上の順序に従った各モーターのキャリブレーション。
例外
ValueError
ValueError— モーターがバスに接続されていない場合、またはフルターンまたは反転モーターがキャリブレーション対象のモーターに含まれていない場合。この場合、モーターは変更されません。
手動で移動したモーターをキャリブレーションします。
選択されたモーターは解放され、動作モードに設定され、方向が割り当てられます。Drive_Modeレジスタを持つモーターには、反転の有無にかかわらず値が書き込まれ、Feetechサーボである他のモーターには、正規化の際にソフトウェアで反転が適用されます。その後、ユーザーは各関節を可動範囲の中央、すなわち各モーターの半回転位置に保持し、各関節を全可動範囲にわたって動かします。この動作は ENTER キーが押されるまで記録されます。全回転モーターは記録されません。これは、そのモデルのエンコーダーの全範囲にまたがるためです。
モーターには動作モードとホーミングオフセットが必要ですが、Feetech SCS0009にはどちらもありません。それらのホーミングオフセットと位置制限は書き換えられ、キャッシュされたcalibrationはクリアされ、トルクはオフのままにされます。返されるキャリブレーションは位置制限に書き込まれることも保存されることもありません。~SerialMotorsBus.write_calibrationが書き込みを行い、デバイスが保存します。
record_ranges_of_motion
< source >( motors: NameOrID | Sequence[NameOrID] | None = Nonedisplay_values: bool = True ) → tuple[dict[str, int | float], dict[str, int | float]]
パラメータ
- motors (
str | int | Sequence[str | int]、省略可) — 名前または ID で指定する、記録対象のモーター。Noneを指定すると、すべてのモーターが選択されます。 - display_values (
bool、省略可能、デフォルトはTrue) — ライブテーブルを表示するかどうか。
戻り値
tuple[dict[str, int | float], dict[str, int | float]]
各モーターの最低および最高の生位置（raw position）を、名前別に示します。
例外
ValueError
ValueError— モーターが動かなかった場合: その最低位置と最高位置が等しい場合。
ENTERを押すまで、選択したモーターを手動で動かして、その移動範囲を記録します。
トルクをオフにした状態で手動で関節を動かすと、ライブテーブルに位置が表示されます。
reset_calibration
< source >( motors: NameOrID | Sequence[NameOrID] | None = None )
選択したモーターの工場出荷時のキャリブレーションを復元します。
ホーミングオフセットは、設定されているモーターで0に設定され、位置制限はエンコーダー全体にわたります。キャッシュされたcalibrationはクリアされます。
解像度
< source >( model: str ) → int
モーターモデルの1回転あたりのエンコーダーステップ数。
開いているポートのボーレートを変更します。
ポートは、接続のたびにdefault_baudrateで開きます。
set_half_turn_homings
< source >( motors: NameOrID | Sequence[NameOrID] | None = None ) → dict[str, int]
選択した各モーターの現在の位置を半回転分に変更します。
モーターのキャリブレーションがリセットされ、その後、各モーターには、現在の位置をエンコーダーの半分（12ビットの場合、2047など）に移動させるホーミングオフセットが設定されます。選択されたすべてのモーターにはホーミングオフセットが必要であり、レジスターへの書き込みの前にチェックが行われます。
set_operating_mode
< source >( mode: strmotors: NameOrID | Sequence[NameOrID] | None = None )
名前によって指定された動作モードに、選択されたモーターを設定します。
モードは各モーターの定義に由来するため、ファミリーだけでなくモデルにも依存します。例えば、Feetech SCS0009にはモードがありません。選択されたすべてのモーターにそのモードが存在する必要があります。これは、モーターがモードを変更する前にチェックされます。トルクをオフにした状態で記述してください。
position: 1ターン内の目標位置と位置の制限を保持します。velocity: 車輪のように、目標速度で回転し続けます。pwm: モーター電圧を直接駆動するオープンループ方式。step(Feetech): 目標位置として書き込まれたステップ数だけ移動します。current(Dynamixel): 位置に関係なく、トルクである目標電流を保持します。extended_position（Dynamixel）：数ターンの間、目標位置を保持します。このモードでは、Min_Position_LimitおよびMax_Position_Limitレジスタは無視されます。current_based_position(Dynamixel): 目標電流で電流を制限しながら、数回転にわたって目標位置を保持します。握りつぶしてはならない対象を保持するグリップとして機能します。
setup_motor
< source >( motor: strinitial_baudrate: int | None = Noneinitial_id: int | None = None )
単一のモーターにそのIDと、バスのデフォルトのボーレートを設定します。
モーターはバス上に1台のみ接続されている必要があります。initial_baudrateとinitial_idの両方が指定されていない場合、まずモーターを検出します。initial_baudrateのみが指定されている場合はそのレートで、それ以外の場合はそのモデルのボーレート全体を検索します。initial_idのみが指定されている場合は、検出されたIDに置き換えられます。その後、rustypotはトルクをオフにし、EEPROMを開いて、IDとボーレートを書き込みます。
setup_motors
< source >( motors: Sequence[str] | None = None )
モーターは1つずつ設定し、各モーターがバス上に単独で接続されていることを確認してください。
sync_read
< source >( data_name: strmotors: NameOrID | Sequence[NameOrID] | None = Nonenormalize: bool = Truenum_retry: int = 0 ) → dict[str, int | float]
パラメータ
- data_name (
str) — 登録名。例:"Present_Position"。大文字と小文字は区別されません。 - motors (
str | int | Sequence[str | int]、省略可) — 名前または ID で指定する、読み取り対象のモーター。Noneの場合はすべてのモーターを読み取ります。 - normalize (
bool、省略可能、デフォルトはTrue) — キャリブレーションとノームモードで定義される範囲に位置をスケーリングするかどうか。 - num_retry (
int、任意、デフォルトは0) — 通信障害が発生した後の追加の試行回数です。リトライでは、成功したグループも含めてすべてのグループが再送信されます。不明なモーターやレジスターはリトライされません。
戻り値
dict[str, int | float]
モーター名ごとの値
例外
ConnectionError または RuntimeError
ConnectionError— モーターが応答しない場合。RuntimeError— モーターが読み取りを拒否した場合に発生します。過負荷などのステータスにおけるアラームは、例外を発生させません。
複数のモーターのレジスタを読み取ります。
rustypot は、プロトコルとレジスタのアドレスおよびサイズを共有するモーターのグループごとに1回の Sync Read を送信し、Feetech SCS などの Sync Read を使用しないサーボモーターについては、1つずつ順番に読み取ります。そのため、これらの値は同時の一時的なスナップショットではありません。
sync_write
< source >( data_name: strvalues: Value | dict[str, Value]normalize: bool = Truenum_retry: int = 0 )
パラメータ
- data_name (
str) — 登録名。例:"Goal_Position"。大文字と小文字は区別されません。 - values (
int | float | dict[str, int | float]) — モーターごとに1つの値、またはモーター名ごとの値。 - normalize (
bool、省略可能、デフォルトはTrue) — 位置が、キャリブレーションとノームモードによって定義される範囲内で与えられるかどうか。 - num_retry (
int、任意、デフォルトは0) — ポートの失敗後の追加試行回数。リトライでは、すべてのグループが再度送信されます。
例外
ConnectionError
ConnectionError— ポートが失敗した場合。
応答を待たずに、複数のモーターのレジスタを書き込みます。
~SerialMotorsBus.write とは異なり、同期書き込みに対してモーターからの応答はありません。そのため高速で制御ループに適していますが、パケットの喪失は検知されません。rustypot は、プロトコルとレジスタのアドレスおよびサイズを共有するモーターのグループごとに 1 つの同期書き込みを送信します。
torque_disabled
< source >( motors: NameOrID | Sequence[NameOrID] | None = None )
with ブロックの期間中、選択したモーターのトルクを無効にします。
ブロックが例外を送出した場合でも、ブロックの終了時にトルクが再度有効化されるため、モーターの構成に適しています。
write
< source >( data_name: strmotor: strvalue: Valuenormalize: bool = Truenum_retry: int = 0 )
パラメータ
- data_name (
str) — 登録名。例:"Goal_Position"。大文字と小文字は区別されません。 - motor (
str) — モーター名。 - value (
int | float) —normalizeの指定に従い、正規化済みまたは生の値として書き込む値。 - normalize (
bool、省略可能、デフォルトはTrue) — 位置が、そのキャリブレーションとノームモードによって定義される範囲内であるかどうかを示します。 - num_retry (
int、任意、デフォルトは0) — 通信失敗後の追加試行回数。
例外
ConnectionError または RuntimeError
ConnectionError— モーターが応答しない場合。RuntimeError— モーターが書き込みを拒否した場合に発生します。過負荷などのステータスアラームでは、例外は発生しません。
1つのモーターのレジスタに書き込み、その応答を待機します。
~SerialMotorsBus.sync_write とは異なり、モーターが書き込みを応答するため、失敗が報告されます。速度は遅くなりますが、モーターの設定に適しています。
write_calibration
< source >( calibration_dict: dict[str, MotorCalibration]cache: bool = True )
モーターにキャリブレーションを書き込み、デフォルトではそれをキャッシュします。
位置制限はすべてのモーターに書き込まれ、ホーミングオフセットはそれを持つモーターに書き込まれます。idおよびドライブモードは書き込まれません。Feetechのドライブモードは正規化時にソフトウェアで適用され、DynamixelのDrive_Modeレジスタは個別に設定されます。
モーター
クラス lerobot.motors.Motor
< source >( id: intmodel: strnorm_mode: MotorNormModemotor_type_str: str | None = Nonerecv_id: int | None = None )
MotorCalibration
クラス lerobot.motors.MotorCalibration
< source >( id: intdrive_mode: inthoming_offset: intrange_min: intrange_max: int )
MotorNormMode
DriveMode
DriveModeには、NON_INVERTED = 0とINVERTED = 1という2つのメンバーがあります。整数が期待される場所、つまりDrive_ModeレジスタやMotorCalibration.drive_modeでは、.valueを使用してください。
bus.write("Drive_Mode", "elbow_flex", DriveMode.INVERTED.value)DynamixelのDrive_ModeレジスタおよびMotorCalibration.drive_modeの値。