LeRobot documentation
Motores
Motores
SerialMotorsBus é a interface de baixo nível para uma cadeia de servos Feetech ou Dynamixel em um barramento serial. Os robôs a utilizam
para ler posições e gravar posições-alvo; raramente você a manipula diretamente, a menos que esteja adicionando hardware. O modelo de cada motor
é consultado no rustypot, que armazena as tabelas de controle e os
fatos que diferem entre as famílias, e também possui a porta serial. FeetechMotorsBus e DynamixelMotorsBus são
aliases obsoletos dela, mantidos por uma única release.
Migrando dos barramentos baseados em SDK
Os aliases mantêm os nomes das classes, não os atributos antigos do SDK e as tabelas de modelos:
bus.model_resolution_table[model]passa a serbus.resolution(model); as outras tabelas de modelos (model_ctrl_table,model_number_table, …) agora são as definições de servo do rustypot.- Os modos de operação são selecionados por nome,
bus.set_operating_mode("position"), em vez de escrever um valor deOperatingModeno registroOperating_Mode. - A porta do SDK e os manipuladores de pacotes não são mais expostos: o rustypot possui a porta serial.
protocol_versioné ignorado: o modelo de cada motor fornece seu protocolo.
Consulte Bring Your Own Hardware para adicionar um novo barramento, e Updating Feetech Firmware e Damiao Motors and CAN Bus para notas específicas de dispositivos.
SerialMotorsBus
classe lerobot.motors.SerialMotorsBus
< source >( port: strmotors: dict[str, Motor]calibration: dict[str, MotorCalibration] | None = None )
Leia e escreva uma cadeia de servos em cascata em uma única porta serial, Feetech ou Dynamixel.
rustypot gerencia os metadados de cada modelo (tabela de controle, resolução, taxas de baud, modos de operação) e a entrada/saída serial; LeRobot gerencia a normalização, a calibração e as configurações recomendadas. Os motores de vários modelos, como STS e SCS ou XL430 e XL330, compartilham a porta.
Para encontrar a porta, execute:
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.Exemplo para um único Feetech sts3215 no barramento:
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 )
Parâmetros
- return_delay_time (
int, opcional, padrão0) — Atraso antes de um motor responder, em unidades de 2 µs; os motores saem da fábrica com 250 (500 µs). - maximum_acceleration (
int, opcional, padrão254) — Limite de aceleração, nos servos que possuem um (Feetech STS), alto para acelerar a aceleração e a desaceleração. - acceleration (
int, opcional, padrão254) — Aceleração, nos servos que a possuem (Feetech).
Escreva as configurações recomendadas pelo LeRobot em todos os motores.
connect
< source >( handshake: bool = True )
Parâmetros
- handshake (
bool, opcional, padrãoTrue) — Se deve verificar se cada motor responde com o número do modelo do seu modelo e se os motores Feetech de uma definição executam um único firmware.
Exceções
DeviceAlreadyConnectedError ou ConnectionError ou RuntimeError
DeviceAlreadyConnectedError— Se a porta já estiver aberta.ConnectionError— Se a porta não puder ser aberta.RuntimeError— Se o handshake falhar; a porta é fechada novamente.
Abra a porta serial e verifique os motores.
disable_torque
< source >( motors: NameOrID | Sequence[NameOrID] | None = Nonenum_retry: int = 0 )
Parâmetros
- motors (
str | int | Sequence[str | int], opcional) — Motores a serem liberados, por nome ou id.Noneseleciona todos os motores. - num_retry (
int, opcional, padrão0) — Tentativas adicionais em cada motor após uma falha de comunicação.
Exceções
ConnectionError
ConnectionError— Se alguns motores não puderam ser alcançados; a mensagem os identifica.
Desative o torque dos motores selecionados.
Com o torque desligado, a EEPROM de um motor pode ser gravada, e o travamento de um motor Feetech é liberado para isso. Todos os motores selecionados são tentados; as falhas são relatadas, e os motores sem resposta podem permanecer com o torque ativado.
disconnect
< source >( disable_torque: bool = True )
Feche a porta serial, por padrão com o torque de todos os motores desligado.
É seguro chamar em um ônibus que já está desconectado, e a porta é liberada mesmo se a desativação do torque falhar.
enable_torque
< source >( motors: NameOrID | Sequence[NameOrID] | None = Nonenum_retry: int = 0 )
Parâmetros
- motors (
str | int | Sequence[str | int], opcional) — Motores a segurar, por nome ou id.Noneseleciona todos os motores. - num_retry (
int, opcional, padrão0) — Tentativas adicionais em cada motor após uma falha de comunicação.
Exceções
ConnectionError
ConnectionError— Se alguns motores não puderam ser alcançados; a mensagem os identifica.
Ative o torque dos motores selecionados e feche o bloqueio dos motores Feetech.
ping
< source >( motor: NameOrIDnum_retry: int = 0 ) → int | None
O número do modelo com o qual um motor responde.
Lê Model_Number em vez de enviar um ping: a presença e a identidade passam a custar uma ida e volta em vez de duas.
ler
< source >( data_name: strmotor: strnormalize: bool = Truenum_retry: int = 0 ) → int | float
Parâmetros
- data_name (
str) — Nome de registro, por exemplo,"Present_Position"; o caso não importa. - motor (
str) — Motor name. - normalize (
bool, opcional, padrãoTrue) — Se deve escalar uma posição para o intervalo definido pelo seu modo de calibração e de norma. - num_retry (
int, opcional, padrão0) — Tentativas adicionais após uma falha de comunicação.
Retorna
int | float
O valor bruto ou o valor normalizado.
Exceções
ConnectionError ou RuntimeError
ConnectionError— Se o motor não responder.RuntimeError— Se o motor recusar a leitura. Um alarme em seu status, como uma sobrecarga, não gera uma exceção.
Leia um registro de um motor.
read_calibration
< source >( ) → dict[str, MotorCalibration]
Retorna
dict[str, MotorCalibration]
A calibração de cada motor, por nome.
Leia a calibração de cada motor.
Um motor sem um registro de deslocamento de retorno à origem (Feetech SCS) relata 0, e um sem um registro Drive_Mode (Feetech) relata modo de acionamento 0.
record_calibration
< source >( mode: strfull_turn_motors: Sequence[str]inverted_motors: Sequence[str] = ()motors: Sequence[str] | None = None ) → dict[str, MotorCalibration]
Parâmetros
- mode (
str) — Modo de operação dos motores, por exemplo,"position". - full_turn_motors (
Sequence[str]) — Motores que recebem a faixa completa do codificador em vez da faixa pela qual são movidos. - inverted_motors (
Sequence[str], opcional, padrão()) — Motores girando no sentido oposto. - motors (
Sequence[str], opcional) — Motores a calibrar.Nonecalibra todos os motores.
Retorna
dict[str, MotorCalibration]
A calibração de cada motor, na ordem do barramento.
Exceções
ValueError
ValueError— Se um motor não estiver no barramento, ou se um motor de giro completo ou invertido não for um dos motores a serem calibrados; nenhum motor foi tocado.
Calibre os motores movidos à mão.
Os motores selecionados são liberados, colocados em modo de operação e recebem sua direção: um motor com um registro Drive_Mode tem esse registro gravado, invertido ou não, enquanto nos demais, como servos Feetech, uma inversão é aplicada no software durante a normalização. O usuário então segura as juntas no meio de sua faixa de movimento, o que se torna meia volta de cada motor, e move cada junta por toda a sua faixa, registrada até ENTER. Um motor de volta completa não é registrado: ele abrange todo o codificador de seu modelo.
Os motores precisam do modo de operação e de um offset de homing, e o Feetech SCS0009 não possui nenhum dos dois. Os offsets de homing e os limites de posição deles são reescritos, o calibration em cache é limpo e o torque deles é mantido desligado. A calibração retornada não é gravada nos limites de posição nem salva: ~SerialMotorsBus.write_calibration a grava e o dispositivo a salva.
record_ranges_of_motion
< source >( motors: NameOrID | Sequence[NameOrID] | None = Nonedisplay_values: bool = True ) → tuple[dict[str, int | float], dict[str, int | float]]
Parâmetros
- motors (
str | int | Sequence[str | int], opcional) — Motores a serem registrados, por nome ou id.Noneseleciona todos os motores. - display_values (
bool, opcional, padrãoTrue) — Se deve imprimir a tabela ao vivo.
Retorna
tuple[dict[str, int | float], dict[str, int | float]]
A posição bruta mais baixa e a mais alta de cada motor, por nome.
Exceções
ValueError
ValueError— Se um motor não se moveu: suas posições mais baixa e mais alta são iguais.
Registre o intervalo por meio do qual cada motor selecionado é movido manualmente, até ENTER.
As juntas são movidas à mão, com o torque desligado, enquanto uma tabela ao vivo exibe as posições.
reset_calibration
< source >( motors: NameOrID | Sequence[NameOrID] | None = None )
Restaure a calibração de fábrica dos motores selecionados.
O deslocamento de retorno à origem é definido como 0 nos motores que possuem esse recurso, e os limites de posição abrangem todo o codificador. O calibration em cache é limpo.
resolução de
< source >( model: str ) → int
Passos do codificador por volta de um modelo de motor.
set_baudrate
< source >( baudrate: int )
Alterne a taxa de baud da porta aberta.
A porta é aberta na default_baudrate a cada conexão.
set_half_turn_homings
< source >( motors: NameOrID | Sequence[NameOrID] | None = None ) → dict[str, int]
Parâmetros
- motors (
str | int | Sequence[str | int], opcional) — Motores para homing, por nome ou id.Noneseleciona todos os motores.
Retorna
dict[str, int]
O deslocamento de retorno (homing offset) escrito em cada motor, por nome.
Exceções
ValueError
ValueError— Se um motor selecionado não tiver deslocamento de referência, como o Feetech SCS.
Faça com que a posição atual de cada motor selecionado seja meia volta.
A calibração dos motores é redefinida e, em seguida, cada um recebe o deslocamento de retorno à origem que leva sua posição atual para a metade do seu codificador, por exemplo, 2047 em um de 12 bits. Todo motor selecionado deve ter um deslocamento de retorno à origem, o que é verificado antes de qualquer registro ser gravado.
set_operating_mode
< source >( mode: strmotors: NameOrID | Sequence[NameOrID] | None = None )
Parâmetros
- mode (
str) — Nome do modo de operação, por exemplo,"position". - motors (
str | int | Sequence[str | int], opcional) — Motores a definir, por nome ou id.Noneseleciona todos os motores.
Exceções
ValueError
ValueError— Se um motor selecionado não possui esse modo; nenhum motor alterou o modo.
Coloque os motores selecionados em um modo de operação, dado pelo nome.
Os modos vêm da definição de cada motor, portanto dependem do modelo, não apenas da família: o Feetech SCS0009 não possui nenhum. O modo deve existir para todos os motores selecionados, o que é verificado antes que qualquer motor mude de modo. Escreva-o com o torque desligado.
position: mantém uma posição de objetivo dentro de uma rodada e os limites de posição.velocity: gira continuamente a uma velocidade alvo, como uma roda.pwm: controla diretamente a tensão do motor, em malha aberta.step(Feetech): move pela quantidade de passos escritos como a posição de destino.current(Dynamixel): mantém uma corrente de objetivo, ou seja, um torque, independentemente da posição.extended_position(Dynamixel): mantém uma posição de destino por várias voltas. Os registrosMin_Position_LimiteMax_Position_Limitsão ignorados neste modo.current_based_position(Dynamixel): mantém uma posição de destino por várias voltas, com a corrente limitada pela corrente de destino, como uma garra que não deve esmagar o que segura.
setup_motor
< source >( motor: strinitial_baudrate: int | None = Noneinitial_id: int | None = None )
Parâmetros
- motor (
str) — Nome do motor. - initial_baudrate (
int, opcional) — Taxa de baud na qual o motor responde atualmente. - initial_id (
int, opcional) — ID ao qual o motor responde no momento, usado cominitial_baudrate.
Exceções
RuntimeError ou ConnectionError
RuntimeError— Se o motor não for encontrado, não for do seu modelo ou não responder conforme configurado após a configuração.ConnectionError— Se a comunicação com o motor falhar.
Dê a um único motor seu id e a taxa de baud padrão do barramento.
O motor deve ser o único no barramento. A menos que tanto initial_baudrate quanto initial_id sejam fornecidos, ele é encontrado primeiro: na initial_baudrate quando apenas essa é fornecida, caso contrário, entre as taxas de baud do seu modelo; um initial_id fornecido isoladamente é substituído pelo id encontrado. O rustypot então desliga o torque, abre a EEPROM e grava o id e a taxa de baud.
setup_motors
< source >( motors: Sequence[str] | None = None )
Configure os motores um de cada vez, pedindo que cada um esteja sozinho no barramento.
sync_read
< source >( data_name: strmotors: NameOrID | Sequence[NameOrID] | None = Nonenormalize: bool = Truenum_retry: int = 0 ) → dict[str, int | float]
Parâmetros
- data_name (
str) — Nome de registro, por exemplo,"Present_Position"; o caso não importa. - motors (
str | int | Sequence[str | int], opcional) — Motores a serem lidos, por nome ou id.Nonelê todos os motores. - normalize (
bool, opcional, padrãoTrue) — Se as posições devem ser escalonadas para o intervalo definido pelo modo de calibração e de norma. - num_retry (
int, opcional, padrão0) — Tentativas adicionais após uma falha de comunicação. Uma nova tentativa reenvia todos os grupos, incluindo aqueles que haviam tido sucesso; um motor ou registro desconhecido nunca é reenviado.
Retorna
dict[str, int | float]
O valor de cada motor, por nome.
Exceções
ConnectionError ou RuntimeError
ConnectionError— Se um motor não responder.RuntimeError— Se um motor recusar a leitura. Um alarme em um status, como uma sobrecarga, não gera uma exceção.
Leia um registro de vários motores.
rustypot envia uma Sync Read por grupo de motores que compartilham um protocolo e o endereço e o tamanho do registro, e lê os motores de um servo sem Sync Read, como o Feetech SCS, um após o outro. Os valores, portanto, não são um instantâneo simultâneo.
sync_write
< source >( data_name: strvalues: Value | dict[str, Value]normalize: bool = Truenum_retry: int = 0 )
Parâmetros
- data_name (
str) — Nome do registro, por exemplo,"Goal_Position"; o uso de maiúsculas e minúsculas não importa. - values (
int | float | dict[str, int | float]) — Um valor para cada motor, ou um valor por nome de motor. - normalize (
bool, opcional, padrãoTrue) — Se as posições são fornecidas no intervalo definido pelo seu modo de calibração e normalização. - num_retry (
int, opcional, padrão0) — Tentativas adicionais após uma falha da porta. Uma nova tentativa reenvia todos os grupos.
Exceções
ConnectionError
ConnectionError— Se a porta falhar.
Escreva um registro de vários motores, sem esperar por uma resposta.
Diferentemente de ~SerialMotorsBus.write, nenhum motor responde a uma escrita síncrona: mais rápido, adequado para loops de controle, mas um pacote perdido passa despercebido. O rustypot envia uma Sync Write por grupo de motores que compartilham um protocolo e o endereço e o tamanho do registro.
torque_disabled
< source >( motors: NameOrID | Sequence[NameOrID] | None = None )
Desative o torque dos motores selecionados durante a duração de um bloco with.
O torque é reativado na saída, mesmo quando o bloco levanta, o que é adequado para a configuração de motores.
write
< source >( data_name: strmotor: strvalue: Valuenormalize: bool = Truenum_retry: int = 0 )
Parâmetros
- data_name (
str) — Nome do registro, por exemplo,"Goal_Position"; o uso de maiúsculas e minúsculas não importa. - motor (
str) — Motor name. - value (
int | float) — Valor a ser gravado, normalizado ou bruto, conforme indicado pornormalize. - normalize (
bool, opcional, padrãoTrue) — Se uma posição é dada no intervalo definido pelo seu modo de calibração e normalização. - num_retry (
int, opcional, padrão0) — Tentativas adicionais após uma falha de comunicação.
Exceções
ConnectionError ou RuntimeError
ConnectionError— Se o motor não responder.RuntimeError— Se o motor recusar a escrita. Um alarme em seu status, como uma sobrecarga, não gera uma exceção.
Escreva um registro de um motor e aguarde sua resposta.
Diferentemente de ~SerialMotorsBus.sync_write, o motor confirma a escrita, de modo que uma falha é
relatada: mais lento, mas adequado para configurar motores.
write_calibration
< source >( calibration_dict: dict[str, MotorCalibration]cache: bool = True )
Escreva uma calibração para os motores e, por padrão, faça o cache dela.
Os limites de posição são gravados em todos os motores, e o offset de homing nos motores que possuem um. Nem o id nem o modo de acionamento são gravados: o modo de acionamento de um Feetech é aplicado em software durante a normalização, e o registro Drive_Mode de um Dynamixel é definido de forma independente.
Motor
classe lerobot.motors.Motor
< source >( id: intmodel: strnorm_mode: MotorNormModemotor_type_str: str | None = Nonerecv_id: int | None = None )
MotorCalibration
classe lerobot.motors.MotorCalibration
< source >( id: intdrive_mode: inthoming_offset: intrange_min: intrange_max: int )
MotorNormMode
DriveMode
DriveMode possui dois membros, NON_INVERTED = 0 e INVERTED = 1. Use .value onde o inteiro é esperado, em um registro Drive_Mode ou em MotorCalibration.drive_mode:
bus.write("Drive_Mode", "elbow_flex", DriveMode.INVERTED.value)Valor do registro Drive_Mode de um Dynamixel e de MotorCalibration.drive_mode.