almond_axol.motor

Low-level async motor interface through the Rust CAN core.

Low-level async interface for individual motors. The API is Python, but every CAN frame is sent and received by the Rust axol-rt transport; Python never opens SocketCAN. Most users work through Axol — this layer is exposed for diagnostics, custom control modes, and bench testing individual 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 motor / engage brake
attach(mode)	Reconnect to an already-enabled motor without disturbing its torque state: verifies it is enabled, fault-free, and in mode, using reads only (set_control_mode would reboot a MyActuator motor, dropping torque for ~2 s)
is_holding()	True if the motor is enabled and holding torque (read-only). Damiao: feedback status ENABLED (an enabled-but-never-commanded motor also reports True). MyActuator: status-1 running byte set and no fault latched
clear_errors()	Clear latched error flags
set_zero_position()	Save current position as encoder zero (persisted to flash). Calibrated at a mechanical end stop, not the rest position
set_control_mode(mode)	Set ControlMode; required before mode-specific commands. MyActuator motors reboot to switch (torque off ~2 s) — never call it on a motor holding a load. Damiao is a plain register write; a live flip is non-disruptive
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() / get_torque() do direct reads and raise while it is)
motor.position	Cached position (rad); populated by telemetry or set_impedance responses
motor.has_position	True once a position has been cached (i.e. telemetry has warmed up)
motor.torque	Cached torque (Nm); populated by telemetry with torque=True

Configuration parameters

Both motor families expose a named configuration table — MyActuator’s 0xC0 parameters and Damiao’s 0x7FF registers — for servicing a motor over CAN without the vendor setup software. These back the motor.dump-config, motor.set-config, and motor.restore-config commands; the CLI is the usual way in, but the same surface is 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

MyActuator motors apply a low undervoltage threshold (LOW_VOLTAGE, -2 V) on enable() so a brief bus-voltage sag 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, and read_config / write_config raise MotorError for them. Read-only parameters are never written, and protected ones (factory calibration and identity, CAN IDs, baud rate) are skipped by a restore unless you opt in, since rewriting 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 → driver mapping

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