Public API

cubemarsPyCAN - CAN control for CubeMars AK-series actuators.

Importing this package pulls in python-can and nothing else. In particular it never imports pyserial, which lives behind the [slcan] extra.

Every constant carries its own provenance - the manual page, the datasheet, or the bench run it came from - readable through Sourced and printed by cubemars dump-spec.

Everything below is importable directly from cubemarspycan. The headings are the modules where each name is defined, which is also the only place it is documented — see the note on Motors for why that matters.

Motors and transport

MotorBus(transport)

Routes frames between a transport and a set of motors.

MitMotor(bus, motor_id, spec, *[, policy, ...])	An AK actuator in MIT (impedance) mode.
MitReplyMode(*values)	Which arbitration id the driver answers on.

ServoMotor(bus, motor_id, spec, *[, policy, ...])

An AK actuator in servo mode over CAN.

CanTransport(bus, *[, owns_bus])

Wraps an injected can.BusABC and fans received frames out to sinks.

The motor data model

MotorSpec(name, model, mit, drivetrain, ...)	Everything known about one motor variant.
Sourced(value, source[, ref, note])	A constant together with its provenance.
Source(*values)	Where a number came from, loosely ordered by how much it should be trusted.
FieldRange(lo, hi, bits)	The scaling of one CAN bit-field.
PhysicalLimits(peak_torque_nm, ...)	What the motor can actually do.
Drivetrain(gear_ratio, pole_pairs, ...)	Constants that relate the rotor to the output shaft and current to torque.
Capabilities(encoders, inner_encoder_bits, ...)	What this variant's hardware supports.
MitFields(position, velocity, torque, kp, kd)	The five MIT command fields.
ServoScaling(feedback_deg_per_lsb, ...)	Servo-mode wire scaling.
Side(*values)	Which side of the gearbox a mechanical quantity refers to.
WrapMode(*values)	What the driver does when position leaves the field's range.

State and faults

MitState(spec, position_rad, velocity_radps, ...)	One decoded MIT feedback frame.
ServoStatus(spec, position_deg, ...)	One decoded servo feedback frame (function id 0x29).
ServoEvent(kind, function_id, payload, ...)	A servo frame that is not state.
FaultEvent(code, text, fault, source, ...)	A latched driver fault.

CanFault(*values)	Fault code from a CAN feedback frame (MIT and servo).
SerialFault(*values)	mc_fault_code from the serial GET_VALUES reply.
describe_can_fault(code)	Map a raw fault byte to (enum_or_None, human_text).

Policy, frames and tracking

SafetyPolicy(max_temp_c, clamp, on_fault, ...)	Limits and reactions chosen by the caller, not read off the motor.
ClampMode(*values)	What to do with a command outside the usable range.
ClampReport(field_name, requested, applied, ...)	What a command had to be changed to before it could be sent.
FaultAction(*values)	What update() does when the driver reports a non-zero fault code.

Frame(arbitration_id, data[, is_extended_id])

One classic-CAN data frame: an arbitration id, up to 8 payload bytes, and a flag.

TurnCounter(field[, mode])

Turns a wrapping field reading into a continuous value.

OriginMode(*values)

Argument to SET_ORIGIN.

Exceptions

CubemarsError	Base class for every error this library raises.
MotorError	Base for runtime problems with a specific motor.
MotorFault	The driver reported a non-zero fault code.
StaleFeedbackError	No fresh feedback within the configured window; the motor may be gone.
NotInControlMode	Commanded a motor that is not inside its control() block.
CapabilityError	This motor variant does not support the requested operation.
ProtocolError	Something on the wire did not match the protocol.
MalformedFrame	A frame could not be decoded.
ServoModeNotConfirmed	The driver never confirmed it is in servo mode.
SpecError	The motor specification cannot support what was asked of it.
SpecIncompleteError	A conversion needs a constant this spec does not know.
UnresolvedFrameError	The value exists on the wire but which side of the gearbox it refers to is unknown.
TransportError	The CAN link failed.
SendFailed	A frame could not be put on the bus.
UnsupportedPlatform	The requested backend does not exist on this platform (e.g. socketcan on macOS).

The registry

models()	Model names as the manual's field-range table spells them.
variants()	Variant keys that carry datasheet-verified physical constants.

get_spec is the public name for the registry’s get; the alias exists because a bare get reads badly at a call site. It is documented here rather than under Core data model, so that there is exactly one entry for it.

get_spec(name: str) → MotorSpec

Look up a spec by variant key or model name, with a helpful error.