Python API¶

The reference below is generated from the installed can_motor_control package by mkdocstrings. The prose comes from the docstrings authored in the Rust PyO3 source, so it matches exactly what help() and Jupyter ? show.

Note

This page requires the native extension to be importable. Build it first with maturin develop (the make docs / make docs-build targets do this for you).

Robot and builder¶

Robot ¶

The top-level handle to a configured robot.

Build one from a config file with from_config or in code with builder. The lifecycle is connect → enable → repeated tick → disable; using it as a context manager (with Robot.from_config(...) as r:) connects and enables on entry and disables on exit.

Index by group name to get the corresponding Arm, Gripper, or MotorGroup; use in to test for a group. Control methods on those groups only queue commands — call tick to exchange frames with the hardware.

builder `staticmethod` ¶

builder()

Return a fresh RobotBuilder for assembling a robot in code.

bus_names `method descriptor` ¶

bus_names()

The names of every bus on the robot.

connect `method descriptor` ¶

connect()

Open every bus and prepare the robot for control.

Call once before enable/tick. Raises TransportError if a bus cannot be opened.

disable `method descriptor` ¶

disable()

Disable every motor on the robot.

Safe to call during shutdown; the context-manager exit calls this automatically.

enable `method descriptor` ¶

enable()

Enable every motor on the robot.

For grippers configured for normalized opening control, this also runs the feedback-based opening calibration used by Gripper.set_opening, Gripper.open, and Gripper.close. If calibration cannot observe enough movement or establish a usable span, raises LifecycleError and clears that gripper's opening calibration.

Requires the robot to be connected; otherwise raises LifecycleError.

from_config `staticmethod` ¶

from_config(path)

Load a robot from a TOML config file at path.

Raises ConfigError if the file is missing or invalid.

group_names `method descriptor` ¶

group_names()

The names of every group on the robot.

is_connected `method descriptor` ¶

is_connected()

True once connect has succeeded.

refresh `method descriptor` ¶

refresh()

Send a state-refresh query to every motor in every group (commands no motion).

Send-only — pair with Robot.tick to receive the replies. The GIL is released for its duration. Raises LifecycleError if the robot is not connected, or TransportError on a bus failure.

set_mode `method descriptor` ¶

set_mode(mode)

Set the persistent control mode on every motor in every group. mode is one of "mit", "pos_vel", "vel", "pos_force". Commands no motion; call once after connect and before commanding. The GIL is released for its duration. Raises ValueError for an unknown mode, LifecycleError if not connected.

tick `method descriptor` ¶

tick(per_bus_deadline_us)

Exchange one round of frames with every bus.

Flushes all commands queued on the groups since the last tick and reads back feedback, blocking up to per_bus_deadline_us microseconds per bus. This is the call that drives a realtime control loop; the GIL is released for its duration. Raises LifecycleError if the robot is not connected, or TransportError on a bus failure.

RobotBuilder ¶

Fluent builder for assembling a Robot in code.

Add buses with add_bus, then attach groups with add_arm, add_gripper, or add_generic, and finish with build. Each method returns the builder so calls can be chained. Obtain one from Robot.builder.

add_arm `method descriptor` ¶

add_arm(name, *, bus, motors)

Attach an arm named name on bus bus from a list of MotorSpec. Returns the builder for chaining.

add_bus `method descriptor` ¶

add_bus(name, transport, codec)

Register a named bus from a transport and a codec.

transport is MockCanBus or the platform-native hardware bus, and codec is a can_motor_control.damiao.DamiaoCodec or MockFeedbackCodec. Both are consumed: passing one already added to another bus raises ValueError. Returns the builder for chaining.

add_generic `method descriptor` ¶

add_generic(name, *, bus, motors)

Attach a generic motor group named name on bus bus (no arm/gripper semantics). Returns the builder for chaining.

add_gripper `method descriptor` ¶

add_gripper(name, *, bus, motor, opening_direction=None, default_current=None)

Attach a single-motor gripper named name on bus bus. Optional opening_direction enables normalized opening control, and default_current supplies its default per-unit current. Returns the builder for chaining.

build `method descriptor` ¶

build()

Consume the builder and return the assembled Robot.

Raises ConfigError if the topology is invalid (e.g. a group references an unknown bus).

Groups¶

Arm ¶

A named group of motors driven together as an arm.

Obtained by indexing a Robot by group name (robot["arm"]). len(arm) is the motor count and arm["j1"] returns a Motor. The control methods take a NumPy command array with one row per motor, in declaration order; commands are queued and flushed on the next Robot.tick.

disable_all `method descriptor` ¶

disable_all()

Disable every motor in the arm (queued for the next tick).

enable_all `method descriptor` ¶

enable_all()

Enable every motor in the arm (queued for the next tick).

mit_control `method descriptor` ¶

mit_control(cmds)

Queue an MIT-mode (impedance) command for every motor.

cmds is a (n, 5) float64 array with one row [kp, kd, q, dq, tau] per motor, in declaration order: position gain, velocity gain, target position (rad), target velocity (rad/s), and feed-forward torque (N·m). A wrong shape raises ValueError. The command is sent on the next Robot.tick.

pos_force_control `method descriptor` ¶

pos_force_control(cmds)

Queue a position-force command for every motor.

cmds is a (n, 3) float64 array with one row [q, dq, i_pu] per motor, in declaration order: target position (rad), target velocity (rad/s), and current in per-unit. A wrong shape raises ValueError. The command is sent on the next Robot.tick.

pos_vel_control `method descriptor` ¶

pos_vel_control(cmds)

Queue a position-velocity command for every motor.

cmds is a (n, 2) float64 array with one row [q, dq] per motor, in declaration order: target position (rad) and target velocity (rad/s). A wrong shape raises ValueError. The command is sent on the next Robot.tick.

positions `method descriptor` ¶

positions()

Latest measured positions (radians) as a (n,) float64 array, one entry per motor in declaration order.

refresh `method descriptor` ¶

refresh()

Send a state-refresh query to every motor in the arm (commands no motion). Pair with Robot.tick to receive the replies — this is how a read loop keeps state fresh without driving the motors.

set_mode `method descriptor` ¶

set_mode(mode)

Set the persistent control mode on every motor in the arm. mode is one of "mit", "pos_vel", "vel", "pos_force". Commands no motion; call once at startup (after connect, before commanding) so the matching control commands take effect. Raises ValueError for an unknown mode.

set_zero_all `method descriptor` ¶

set_zero_all()

Set the current position of every motor as its new zero reference.

torques `method descriptor` ¶

torques()

Latest estimated torques (N·m) as a (n,) float64 array, one entry per motor in declaration order.

vel_control `method descriptor` ¶

vel_control(cmds)

Queue a velocity command for every motor.

cmds is a (n,) float64 array of target velocities (rad/s), one per motor in declaration order. A wrong shape raises ValueError. The command is sent on the next Robot.tick.

velocities `method descriptor` ¶

velocities()

Latest measured velocities (rad/s) as a (n,) float64 array, one entry per motor in declaration order.

Gripper ¶

A single-motor group driven as a gripper.

Obtained by indexing a Robot by group name. Unlike Arm, the control methods take scalar arguments for the one motor. Commands are queued and flushed on the next Robot.tick.

motor `property` ¶

motor

The gripper's underlying Motor.

opening `property` ¶

opening

Normalized opening from feedback received by the most recent Robot.tick, where 0.0 is fully closed and 1.0 is fully open.

Call Gripper.refresh followed by Robot.tick before reading when fresh feedback is required. The automatic opening calibration performed by Robot.enable must have completed, otherwise this property raises LifecycleError. Reading the property does not send CAN frames.

close `method descriptor` ¶

close(*, current=None)

Queue a fully-closed normalized opening command.

Requires the automatic opening calibration performed by Robot.enable. current uses the same configured-default-then-library-default fallback as set_opening when omitted.

disable `method descriptor` ¶

disable()

Disable the gripper motor (queued for the next tick).

enable `method descriptor` ¶

enable()

Enable the gripper motor (queued for the next tick).

mit_control `method descriptor` ¶

mit_control(kp, kd, q, dq, tau)

Queue an MIT-mode (impedance) command for the gripper motor.

kp/kd are the position and velocity gains, q/dq the target position (rad) and velocity (rad/s), and tau the feed-forward torque (N·m). Sent on the next Robot.tick.

open `method descriptor` ¶

open(*, current=None)

Queue a fully-open normalized opening command.

Requires the automatic opening calibration performed by Robot.enable. current uses the same configured-default-then-library-default fallback as set_opening when omitted.

pos_force_control `method descriptor` ¶

pos_force_control(q, dq, i_pu)

Queue a position-force command for the gripper motor.

q is target position (rad), dq is target velocity (rad/s), and i_pu is current in per-unit. Sent on the next Robot.tick.

pos_vel_control `method descriptor` ¶

pos_vel_control(q, dq)

Queue a position-velocity command (target position q rad, target velocity dq rad/s) for the gripper motor.

refresh `method descriptor` ¶

refresh()

Send a state-refresh query to the gripper motor (commands no motion). Pair with Robot.tick to receive the reply.

set_mode `method descriptor` ¶

set_mode(mode)

Set the gripper motor's persistent control mode ("mit", "pos_vel", "vel", "pos_force"). Commands no motion. Raises ValueError for an unknown mode.

set_opening `method descriptor` ¶

set_opening(opening, *, current=None)

Queue a normalized opening command where 0.0 is fully closed and 1.0 is fully open. Opening-enabled grippers are calibrated automatically during Robot.enable; calling this before calibration raises LifecycleError. current is an optional per-unit motor current; if omitted, the gripper's configured default opening current is used, falling back to the library default when no default was configured.

MotorGroup ¶

A generic, named group of motors with no arm/gripper semantics.

Created via RobotBuilder.add_generic and obtained by indexing a Robot by group name. Currently exposes only its motor count.

Motor ¶

A live view of one motor's most recent feedback.

Obtained by indexing an Arm by motor name (arm["j1"]) or via Gripper.motor. Every attribute access reads the latest values decoded by the most recent Robot.tick; the object holds no state of its own.

fault `property` ¶

fault

The motor's fault code, or None if it reports no fault.

is_enabled `property` ¶

is_enabled

True if the motor reported itself enabled at the last tick.

name `property` ¶

name

The motor's name, as declared in its MotorSpec.

position `property` ¶

position

Latest measured shaft position, in radians.

recv_id `property` ¶

recv_id

The CAN id this motor sends its feedback replies on.

send_id `property` ¶

send_id

The CAN id the host sends commands to this motor on.

temperature_mos `property` ¶

temperature_mos

Latest MOSFET temperature, in degrees Celsius.

temperature_rotor `property` ¶

temperature_rotor

Latest rotor temperature, in degrees Celsius.

torque `property` ¶

torque

Latest estimated output torque, in newton-metres.

velocity `property` ¶

velocity

Latest measured shaft velocity, in radians per second.

Specs and frames¶

MotorSpec ¶

Declaration of one motor on a bus: its name, SKU, and CAN ids.

Used when building a robot in code to describe the motors of an arm or gripper (see RobotBuilder.add_arm). The type is a can_motor_control.damiao.MotorType; send_id is the id the host sends commands on and recv_id is the id the motor replies on.

name `property` ¶

name

The motor's name.

recv_id `property` ¶

recv_id

The CAN id this motor sends its feedback replies on.

send_id `property` ¶

send_id

The CAN id the host sends commands to this motor on.

CanFrame ¶

A single CAN frame: an arbitration id, a payload, and flags.

Construct frames with classical (classical CAN, up to 8 payload bytes) or fd (CAN-FD, up to 64 bytes). The id, flags and len attributes are read-only.

flags `property` ¶

flags

The raw frame flag bits (FD, extended id, ...).

id `property` ¶

id

The CAN arbitration id.

len `property` ¶

len

The payload length in bytes.

classical `staticmethod` ¶

classical(id, payload)

Build a classical CAN frame.

payload must be at most 8 bytes; a longer payload raises TransportError.

fd `staticmethod` ¶

fd(id, payload)

Build a CAN-FD frame.

payload must be at most 64 bytes; a longer payload raises TransportError.

is_extended `method descriptor` ¶

is_extended()

True if this frame uses a 29-bit extended id.

is_fd `method descriptor` ¶

is_fd()

True if this is a CAN-FD frame.

payload `method descriptor` ¶

payload()

Return the payload as bytes.

Transports¶

MockCanBus ¶

An in-memory CAN bus for tests and dry runs.

Drop-in replacement for SocketCanBus that talks to no hardware, so robot code can be exercised without a real CAN interface. Pass it to RobotBuilder.add_bus. A bus is consumed by the builder and may be added to only one robot.

The default constructor is classical-CAN; use MockCanBus.new_fd for an FD-capable mock that accepts and loops back CAN-FD frames.

new_fd `staticmethod` ¶

new_fd(name)

Create a CAN-FD-capable mock bus. It advertises FD capabilities and loops back FD frames, so the FD send/receive path is testable without an FD-capable interface.

SocketCanBus ¶

A CAN bus backed by a Linux SocketCAN interface.

Opens interface (e.g. "can0") on construction; a failure to open raises TransportError. Pass it to RobotBuilder.add_bus. A bus is consumed by the builder and may be added to only one robot.

SocketCanBus is present on Linux. macOS builds replace it with GsUsbBus; see Native macOS gs_usb for its constructor and counters.

Damiao codec¶

DamiaoCodec ¶

The Damiao protocol codec.

Encodes commands to and decodes feedback from Damiao-family motors. Pass an instance to RobotBuilder.add_bus to bind a bus to the Damiao protocol. A codec is consumed by the builder and may be added to only one bus.