almond_axol.motor

Low-level async interface for individual motors. The API is Python, but the Rust axol-rt transport sends and receives every CAN frame. Python never opens SocketCAN. Most code uses Axol instead. This layer is for diagnostics, custom control modes and bench tests of single motors.

from almond_axol.motor import CanBus, Motor, ControlMode, MotorStatus, MotorGains, Joint

import asyncio
from almond_axol.motor import CanBus, Motor, ControlMode, Joint

async def main():
    async with CanBus("can_alm_axol_l") as bus:
        elbow = Motor(bus, Joint.ELBOW)
        await elbow.enable()
        await elbow.set_control_mode(ControlMode.IMPEDANCE)

        pos = await elbow.get_position()  # rad
        print("elbow position:", pos)

        await elbow.set_impedance(p_des=pos, v_des=0.0, kp=100.0, kd=2.0, t_ff=0.0)
        await elbow.disable()

asyncio.run(main())

`Motor` methods

Method	Description
`enable()` / `disable()`	Enable the motor, or disable it and engage the brake. On a Damiao motor, `disable()` also clears a `LOST_COMM` fault (see below).
`attach(mode)`	Reconnect to a motor that is already enabled, without changing its torque. Checks with reads only that it is enabled, fault-free and in `mode`.
`is_holding()`	`True` if the motor is enabled and holding torque. Read-only (see below for how each motor family reports it).
`clear_errors()`	Clear latched error flags
`set_zero_position()`	Save the current position as the encoder zero, in flash. Set it at a mechanical end stop, not the rest pose.
`set_control_mode(mode)`	Set the `ControlMode`, which mode-specific commands require. MyActuator motors reboot to switch, with torque off for about 2 s, so never call it on a motor holding a load.
`get_control_mode()`	Read active mode from hardware (`None` for MyActuator)
`get_model()`	Motor model string, e.g. `"X8S2V"` (`None` for Damiao)
`get_firmware_version()`	Firmware VersionDate `int`, e.g. `2026042402` (`None` for Damiao)
`get_position()`	Shaft position (rad); raises if telemetry is active
`get_velocity()`	Shaft velocity (rad/s)
`get_torque()`	Torque estimate (Nm); raises if telemetry is active
`get_temperature()`	Motor temperature (°C)
`get_voltage()`	Bus voltage (V)
`get_error_code()`	`MotorStatus`
`get_gains()` / `set_gains(gains)`	Read/write PID gains (persisted to flash)
`set_impedance(p_des, v_des, kp, kd, t_ff)`	MIT impedance command; requires `IMPEDANCE` mode
`set_position_velocity(position, max_speed)`	Built-in position controller; requires `POSITION_VELOCITY` mode
`set_velocity(velocity)`	Built-in speed controller; requires `VELOCITY` mode
`set_position_force(position, max_speed, max_torque)`	Damiao only; requires `POSITION_FORCE` mode
`set_acceleration(acceleration, deceleration)`	Acceleration ramp (rad/s²)
`set_can_id(can_id)`	Change CAN ID (persisted to flash)
`start_telemetry(hz, torque=False)` / `stop_telemetry()`	Background polling loop
`motor.telemetry_active`	`True` while the background polling loop is running. `get_position()` and `get_torque()` raise while it runs.
`motor.position`	Cached position (rad); populated by telemetry or `set_impedance` responses
`motor.has_position`	`True` once a position has been cached
`motor.torque`	Cached torque (Nm); populated by telemetry with `torque=True`

Notes on the methods above:

disable() on a Damiao motor in the LOST_COMM fault, left by a session that ended without a clean shutdown, clears that fault so the motor reports DISABLED. Clearing never enables the motor, and other faults stay in place.
attach() uses reads only because set_control_mode() would reboot a MyActuator motor and drop its torque for about 2 s.
is_holding() on a Damiao motor means the feedback status is ENABLED, which is also true of a motor that was enabled but never commanded. On a MyActuator motor it means the running byte of status 1 is set and no fault is latched.
Damiao motors switch control modes with a register write, so switching while holding doesn’t disturb them.

Configuration parameters

Both motor families have a named configuration table: MyActuator’s 0xC0 parameters and Damiao’s 0x7FF registers. Use it to service a motor over CAN without the vendor’s setup software. The motor.dump-config, motor.set-config and motor.restore-config commands are the usual way in. The same methods are on Motor:

Method	Description
`resolve_config_param(name)`	Look up a `MotorParam` by name for this motor’s family
`read_config(param)`	Read one parameter, in the unit its spec names
`write_config(param, value)`	Write one parameter and persist it to flash/ROM
`dump_config(raw_range=None)`	Read every known parameter; pass a `range` to sweep raw MyActuator indices
`restore_config(values, *, include_protected=False)`	Write a saved config back; returns the parameters actually changed (protected ones skipped unless `include_protected`)
`get_low_voltage_threshold()` / `set_low_voltage_threshold(volts)`	Undervoltage protection threshold (V); MyActuator only
`get_can_timeout()` / `set_can_timeout(milliseconds)`	Loss-of-comms alarm time (ms); Damiao only

On enable(), MyActuator motors set a low undervoltage threshold (LOW_VOLTAGE, -2 V), so a brief sag in bus voltage can’t latch the level-2 undervoltage fault.
Parameters whose ParamSpec.min_firmware is newer than the motor’s firmware are left out of dumps and restores. read_config and write_config raise MotorError for them.
Read-only parameters are never written.
A restore skips protected parameters (factory calibration and identity, CAN IDs, baud rate) unless you pass include_protected=True. Writing them can leave a motor unable to commutate or unreachable on the bus.

`ControlMode` values

Value	Description
`IMPEDANCE`	MIT impedance control (arm joints)
`POSITION_VELOCITY`	Motor built-in position controller
`VELOCITY`	Motor built-in speed controller
`POSITION_FORCE`	Position with hard torque cap; Damiao only (gripper)

`MotorStatus` values

OK, DISABLED, OVER_VOLTAGE, UNDER_VOLTAGE, OVER_CURRENT, OVER_TEMPERATURE, MOS_OVER_TEMP, ROTOR_OVER_TEMP, LOST_COMM, OVERLOAD, MOTOR_STALL*, ENCODER_ERROR*, CALIBRATION_ERROR*, POWER_OVERRUN*, SPEEDING*, UNKNOWN * MyActuator only

Joint to driver mapping

Joint	Driver	CAN ID
`SHOULDER_1` – `WRIST_1`	MyActuator	`0x01` – `0x05`
`WRIST_2`, `WRIST_3`, `GRIPPER`	Damiao	`0x06` – `0x08`

Get Started

Operations

Mantis

Remote Teleop

Web Interfaces

Advanced

almond_axol.motor

`Motor` methods

Configuration parameters

`ControlMode` values

`MotorStatus` values

Joint to driver mapping

​Motor methods

​Configuration parameters

​ControlMode values

​MotorStatus values

​Joint to driver mapping

`Motor` methods

Configuration parameters

`ControlMode` values

`MotorStatus` values

Joint to driver mapping