Referencemakiina.actuator

makiina.actuator

Every function, property and mode for talking to one MAKIINA drive over CAN.

Python

from makiina.actuator import Actuator, list_channels, ping, StateFrame

Direct CAN control of one drive, in plain Python over python-can. The library logs to the makiina_drive logger and never prints; call logging.basicConfig(level=logging.INFO) to watch it work. Drive a single actuator shows these calls in use.

Adapters and boards

Call	Returns
`list_channels()`	every USB CAN adapter, with its serial number
`default_interface()`	the natural backend for this platform
`ping(board_ids, interface=None, channel=None, timeout_s=2.0)`	`{id: position or None}` for the ids you name, one after the other; read only
`makiina.calibration.discovery.sweep_boards(interface, channel)`	every board id on the bus, in about a second; read only
`makiina.calibration.discovery.discover_bus(interface, channel)`	every board with its firmware, part and joint

A candle channel is "<serial>:0", or 0 when only one adapter is plugged in. A drive answers on an even 11-bit id and sends its state frames on the odd id next to it.

`Actuator(board_id, interface=None, channel=None, bitrate=1000000, fd=False)`

Opens the bus, or joins it if it is already open, so several actuators can share one adapter. Use it as a context manager, or call close(), which releases the bus without sending anything to the drive.

State

Member	Returns
`get_states()`	`StateFrame(position, velocity, current, torque, temperature)`; torque and temperature are NaN on classic CAN frames
`current_pos`, `actual_velocity`, `current_draw`, `estimated_torque`	one value each, one round trip each; `None` on timeout
`start_broadcast(hz=1600.0)`	the drive sends its state on its own at `hz`
`stop_broadcast()`	back to asking
`get_next_broadcast_frame(timeout_s=0.0001)`	the next frame in order, for recording
`get_latest_velocity()`, `get_latest_current()`, `get_virtual_torque()`, `get_temperature_c()`	the newest broadcast value, without waiting
`last_state_frame_perf`	`time.perf_counter()` when the newest frame arrived

Targets and limits

Settable properties; reading one asks the drive (firmware 2.04 and later).

Property	Unit	Meaning
`target_pos`	rad	position mode target
`target_velocity`	rad/s	velocity mode target
`target_current`	A	current mode target
`target_torque`	N m	torque mode target
`max_velocity`	rad/s	speed limit while tracking a position
`max_current`	A	the current limit, and the main safety setting
`output_ramp`	rad/s²	how fast the controller output may change
`position_filter_amount`	0 to 1	smoothing of incoming targets; 0 is none

Modes

set_position_mode(), set_velocity_mode(), set_current_mode(), set_torque_mode(), set_free_mode(enabled=True). Free mode commands zero current plus cogging compensation, so the shaft turns freely by hand.

Gains

Properties	Loop
`kp_angle`, `ki_angle`, `kd_angle`	position
`kp_velocity`, `ki_velocity`, `kd_velocity`	velocity; with adaptive gains on, P and I are the maximum
`adaptive_vpid_enabled`, `adaptive_vpid_p_min`, `adaptive_vpid_p_max`, `adaptive_vpid_i_min`, `adaptive_vpid_i_max`, `adaptive_vpid_vel_min`, `adaptive_vpid_vel_max`	adaptive velocity gains; `configure_adaptive_vpid(...)` sets several at once
`kp_current`, `ki_current`, `kd_current`	current
`motor_kt`, `motor_gear_ratio`, `motor_efficiency`	the constants torque mode uses
`cogging_`, `ripple_`, `torque_estimator_*`	compensation tables and the torque estimate; `configure_cogging(...)` sets several at once

Reading settings back

Firmware 2.04 and later.

Call	Returns
`read_setting(name)`	the value the drive runs for one setting
`read_settings(names=None)`	a dict of several, or of every setting
`supports_readback()`	whether this drive answers setting reads
`get_firmware_version()`, `firmware_version`	`(major, minor)`
`get_boot_report()`, `get_boot_log()`, `get_foc_ok()`	what the drive found when it last started

SETTINGS lists every setting; reading one from older firmware raises SettingUnsupported.

Identity and calibration

These write the drive's permanent memory and are set at the factory. They belong to Calibration and firmware.

Call	Does
`set_motor_preset(preset)`, `get_motor_preset()`	`"small"` or `"medium"` motor constants, applied at start
`set_angle_zero()`, `clear_angle_zero()`, `get_zero_offset()`	the current position becomes the joint's zero
`set_user_direction(sign)`, `get_user_direction()`	the joint's direction, +1 or -1
`set_part_id(part)`, `get_part_id()`	1 left arm, 2 right arm, 3 head
`set_aux_id(joint)`, `get_aux_id()`	the joint number: 1 to 6, gripper 7, head 1
`set_arm_calibrated(flag)`, `get_arm_calibrated()`	the calibrated flag
`set_can_termination(enabled)`, `get_can_termination()`	the drive's bus terminator
`set_can_id(id)`, `get_uid_can_id()`, `resolve_id_collision(new_id)`	move a drive to another CAN id (firmware 2.05)
`restart_board()`, `enter_bootloader()`	restart the drive, or restart it into its firmware loader

`makiina.actuator.dfu`

Call	Does
`flash_firmware(board_id, firmware, *, interface=None, channel=None, progress=None, log=None)`	loads a firmware image onto one drive
`wait_for_application(board_id, *, interface=None, channel=None, timeout=15.0)`	`True` once the drive answers again

Errors

ActuatorError, BusError, AmbiguousChannelError (several adapters and no channel given), SettingUnsupported, dfu.DfuError.

`makiina.actuator.protocol`

The CAN wire format: command bytes, frame layouts, the checksum, and StateFrame. Start here to drive a MAKIINA actuator from your own stack.