Python API reference¶
moteus.Controller¶
Operates a single moteus controller across some communication medium.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
bus ID of the controller or DeviceAddress structure |
1
|
|
query_resolution
|
an instance of moteus.QueryResolution |
QueryResolution()
|
|
position_resolution
|
an instance of moteus.PositionResolution |
PositionResolution()
|
|
transport
|
something modeling moteus.Transport to send commands through |
None
|
set_position(*args, **kwargs)
async
¶
make_position(*, position=None, velocity=None, feedforward_torque=None, kp_scale=None, kd_scale=None, maximum_torque=None, stop_position=None, watchdog_timeout=None, velocity_limit=None, accel_limit=None, fixed_voltage_override=None, ilimit_scale=None, fixed_current_override=None, ignore_position_bounds=None, query=False, query_override=None)
¶
Return a moteus.Command structure with data necessary to send a position mode command with the given values.
set_position_wait_complete(period_s=0.025, query_override=None, *args, **kwargs)
async
¶
Repeatedly send a position mode command to a device until it reports that the trajectory has been completed.
If the controller is unresponsive, this method will never return.
If the controller reports a fault or position mode timeout, a FaultError exception will be raised.
set_stop(*args, **kwargs)
async
¶
make_stop(*, query=False, query_override=None)
¶
Return a moteus.Command structure with data necessary to send a stop mode command.
query(**kwargs)
async
¶
make_query(query_override=None)
¶
custom_query(*args, **kwargs)
async
¶
make_custom_query(to_query_fields)
¶
Return a moteus.Command structure with data required to query the registers given by the 'to_query_fields' dictionary of registers to resolutions.
set_output_nearest(*args, **kwargs)
async
¶
make_set_output_nearest(*args, position=0.0, query=False, query_override=None)
¶
set_output_exact(*args, **kwargs)
async
¶
make_set_output_exact(*args, position=0.0, query=False, query_override=None)
¶
set_recapture_position_velocity(query=False, query_override=None)
async
¶
make_recapture_position_velocity(query=False, query_override=None)
¶
set_vfoc(*args, **kwargs)
async
¶
make_vfoc(*, theta, voltage, theta_rate=0.0, query=False, query_override=None)
¶
Return a moteus.Command structure with data necessary to send a voltage mode FOC command.
set_current(*args, **kwargs)
async
¶
make_current(*, d_A, q_A, query=False, query_override=None)
¶
Return a moteus.Command structure with data necessary to send a current mode command.
set_stay_within(*args, **kwargs)
async
¶
make_stay_within(*, lower_bound=None, upper_bound=None, feedforward_torque=None, kp_scale=None, kd_scale=None, maximum_torque=None, stop_position=None, watchdog_timeout=None, ilimit_scale=None, ignore_position_bounds=None, query=False, query_override=None)
¶
Return a moteus.Command structure with data necessary to send a within mode command with the given values.
set_brake(*args, **kwargs)
async
¶
make_brake(*, query=False, query_override=None)
¶
set_write_gpio(*args, **kwargs)
async
¶
make_write_gpio(aux1=None, aux2=None, query=False, query_override=None)
¶
Return a moteus.Command structure with data necessary to set one or more GPIO registers.
aux1/aux2 are an optional integer bitfield, where the least significant bit is pin 0 on the respective port.
read_gpio()
async
¶
Return a bytes() object with an int8 for each auxiliary port. The pins for each port are represented as bits, with the least significant bit being pin 0.
None can be returned if no response is received.
set_trim(*args, **kwargs)
async
¶
make_set_trim(*, trim=0)
¶
set_aux_pwm(*args, **kwargs)
async
¶
make_aux_pwm(*, aux1_pwm1=None, aux1_pwm2=None, aux1_pwm3=None, aux1_pwm4=None, aux1_pwm5=None, aux2_pwm1=None, aux2_pwm2=None, aux2_pwm3=None, aux2_pwm4=None, aux2_pwm5=None, query=False, query_override=None)
¶
moteus.move_to¶
Move servos to setpoint positions and wait for all to complete.
This function provides a simple way to move one or more servos to setpoint positions and wait until all trajectories are complete.
Can be called two ways:
Single servo
await move_to(controller, position=0.5, duration=1.0)
Multiple servos
await move_to([ (controller1, 0.5), (controller2, -0.3), ], duration=2.0)
The setpoint can be a plain number (position), math.nan (hold position), or a Setpoint object for additional control:
await move_to([
(c1, 0.5), # Just position
(c2, Setpoint(position=-0.3, velocity=0.1)), # With velocity
(c3, Setpoint(position=0.0, kp_scale=0.5)), # With reduced kp
(c4, math.nan), # Hold position
])
Servos with math.nan as their setpoint position will be commanded to hold their current position (position=nan keeps the current setpoint) but will not be waited on for completion. This is useful when you need to move a subset of servos while keeping others active.
If a duration is specified, then approximate velocity limits will be used to attempt to have all servos reach trajectory completion at the same time. However, this does not account for any possible configured or specified acceleration limit or starting velocity, so the actual completion times may still be quite far apart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
setpoints
|
List of (Controller, setpoint) tuples for multi-servo, or single Controller for single-servo case. The setpoint can be a number, math.nan, or a Setpoint object. |
required | |
position
|
Setpoint position (required for single-servo case) |
None
|
|
transport
|
Optional transport, inferred from controllers if absent |
None
|
|
duration
|
If specified, velocity limits are calculated so all servos complete in approximately this time. This overrides both the global velocity_limit and any Setpoint velocity_limit. |
None
|
|
velocity_limit
|
Default velocity limit for servos without a Setpoint velocity_limit. Setpoint values override this. |
None
|
|
accel_limit
|
Default acceleration limit. Setpoint values override this. |
None
|
|
maximum_torque
|
Default maximum torque limit. Setpoint values override this. |
None
|
|
period_s
|
Polling interval for checking completion (default 0.025s) |
0.025
|
|
timeout
|
Maximum time to wait (raises TimeoutError if exceeded) |
None
|
Returns:
| Type | Description |
|---|---|
|
For single-servo case: the final Result object |
|
|
For multi-servo case: List of (Controller, final_Result) tuples in same order as input |
Raises:
| Type | Description |
|---|---|
FaultError
|
If any servo enters fault or timeout mode |
TimeoutError
|
If timeout exceeded |
ValueError
|
If position is not provided for single-servo case |
moteus.make_transport_args¶
Add transport specific arguments to an argparse.ArgumentParser
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parser
|
the argparse.ArgumentParser instance |
required |
moteus.get_singleton_transport¶
Return (and construct if necessary) a transport.Transport instance that uses either all available CAN-FD interfaces on the system, or those configured by args.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
args
|
an argparse.Namespace object |
None
|
Returns:
| Type | Description |
|---|---|
|
a moteus.Transport object |
moteus.QueryResolution¶
Specify which registers should be requested, and with which resolution, during query operations.
mode = mp.INT8
class-attribute
instance-attribute
¶
position = mp.F32
class-attribute
instance-attribute
¶
velocity = mp.F32
class-attribute
instance-attribute
¶
torque = mp.F32
class-attribute
instance-attribute
¶
q_current = mp.IGNORE
class-attribute
instance-attribute
¶
d_current = mp.IGNORE
class-attribute
instance-attribute
¶
abs_position = mp.IGNORE
class-attribute
instance-attribute
¶
power = mp.IGNORE
class-attribute
instance-attribute
¶
motor_temperature = mp.IGNORE
class-attribute
instance-attribute
¶
trajectory_complete = mp.IGNORE
class-attribute
instance-attribute
¶
rezero_state = mp.IGNORE
class-attribute
instance-attribute
¶
home_state = mp.IGNORE
class-attribute
instance-attribute
¶
voltage = mp.INT8
class-attribute
instance-attribute
¶
temperature = mp.INT8
class-attribute
instance-attribute
¶
fault = mp.INT8
class-attribute
instance-attribute
¶
aux1_gpio = mp.IGNORE
class-attribute
instance-attribute
¶
aux2_gpio = mp.IGNORE
class-attribute
instance-attribute
¶
aux1_pwm_input_period_us = mp.IGNORE
class-attribute
instance-attribute
¶
aux1_pwm_input_duty_cycle = mp.IGNORE
class-attribute
instance-attribute
¶
aux2_pwm_input_period_us = mp.IGNORE
class-attribute
instance-attribute
¶
aux2_pwm_input_duty_cycle = mp.IGNORE
class-attribute
instance-attribute
¶
moteus.PositionResolution¶
Specify what resolutions should be used for each register when sending position mode commands.
position = mp.F32
class-attribute
instance-attribute
¶
velocity = mp.F32
class-attribute
instance-attribute
¶
feedforward_torque = mp.F32
class-attribute
instance-attribute
¶
kp_scale = mp.F32
class-attribute
instance-attribute
¶
kd_scale = mp.F32
class-attribute
instance-attribute
¶
maximum_torque = mp.F32
class-attribute
instance-attribute
¶
stop_position = mp.F32
class-attribute
instance-attribute
¶
watchdog_timeout = mp.F32
class-attribute
instance-attribute
¶
velocity_limit = mp.F32
class-attribute
instance-attribute
¶
accel_limit = mp.F32
class-attribute
instance-attribute
¶
fixed_voltage_override = mp.F32
class-attribute
instance-attribute
¶
ilimit_scale = mp.F32
class-attribute
instance-attribute
¶
fixed_current_override = mp.F32
class-attribute
instance-attribute
¶
ignore_position_bounds = mp.F32
class-attribute
instance-attribute
¶
moteus.Stream¶
Presents a python file-like interface to the diagnostic stream of a moteus controller.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
controller
|
moteus.Controller instance |
required | |
channel
|
diagnostic channel to use |
1
|
|
verbose
|
if True, all communication written to stdout |
False
|
moteus.Transport¶
This is an object which can dispatch commands to one or more controllers across potentially multiple CAN-FD busses.
cycle(commands, request_attitude=False, read_unsolicited=None, force_can_check=None)
async
¶
Issue all commands, returning any resulting frames.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request_attitude
|
This is present to allow producing IMU data in the same SPI cycle as CAN data with an mjbots pi3hat. |
False
|
|
read_unsolicited
|
An optional list of TransportDevices, for which any available unsolicited CAN frames should be returned. If specified on a TransportDevice where moteus controllers are commanded, this may result in duplicate frame receipts. |
None
|
|
force_can_check
|
A bitfield to force a connected pi3hat to check specific CAN ports. Modern code should instead use the read_unsolicited kwargs. |
None
|
read(channel=None)
async
¶
Wait for one or more frames to be received.
This can be used to receive unsolicited data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel
|
If specified, only read from the given TransportDevice. |
None
|
discover(can_prefix=0, source=0, timeout=0.2)
async
¶
Discover all controllers attached to any included TransportDevices which support discovery.
Returns:
| Type | Description |
|---|---|
list[DeviceInfo]
|
A list of DeviceInfo structures containing the CAN ID, UUID, and TransportDevice where the device is located. |
flush_read_queue(timeout=0.1, channel=None)
async
¶
Flush any pending receive frames.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeout
|
Time in seconds to keep reading before giving up. |
0.1
|
|
channel
|
None = all channels |
None
|
devices()
¶
Returns:
| Type | Description |
|---|---|
list[TransportDevice]
|
list of TransportDevices in this Transport |
count()
¶
Returns:
| Type | Description |
|---|---|
int
|
integer number of TransportDevices in this Transport |
close()
¶
Close all TransportDevices associated with this Transport.
moteus.FdcanusbDevice¶
Bases: TransportDevice
Connects to a single mjbots fdcanusb.
detect_fdcanusbs()
staticmethod
¶
Returns:
| Type | Description |
|---|---|
list[str]
|
list of filesystem paths that can be used to construct FdcanusbDevice objects |
moteus.PythonCanDevice¶
Bases: TransportDevice
Implements a 'Transport' on top of python-can.
enumerate_devices(**kwargs)
staticmethod
¶
Returns:
| Type | Description |
|---|---|
list[PythonCanDevice]
|
list of objects for devices present in the current system |