API Reference

`one_axis_stage.api.StageAPI`

Bases: StageSerialConnection

Direct command interface to the stage controller firmware.

Wraps StageSerialConnection with typed commands for device discovery, position control, velocity, operating mode, and LED feedback. Each method corresponds to one firmware command.

`flash(device_id, duration_ms, repeats)`

Trigger the LED on a device for visual identification.

Parameters:

Name	Type	Description	Default
`device_id`	`int`	Target device ID.	required
`duration_ms`	`int`	On-time of each flash in milliseconds.	required
`repeats`	`int`	Number of times to flash.	required

`get_info(device_id)`

Return a status dict for a single device.

Baud rate and operating mode integer codes are resolved to human-readable strings and added as baud_rate and operating_mode keys alongside the raw integer originals. A connected boolean is set to False when the bus returns the 0xFFFF no-device sentinel for model_number.

Parameters:

Name	Type	Description	Default
`device_id`	`int`	Dynamixel device ID on the serial bus.	required

Returns:

Type	Description
`dict`	Dict with at minimum the keys `connected` (bool), `model_number`,
`dict`	`id`, `baud_rate` (str), `baud_rate_int`, `operating_mode`
`dict`	(str), `operating_mode_int`, `position_raw`, and `velocity_max`.
`dict`	All values reflect firmware state at call time.

`get_info_all(device_ids)`

Return a list of status dicts, one per device ID.

`get_position(device_id)`

Return the current raw position of a device.

`get_stage_id()`

Query and cache the controller's stage ID.

`scan_for_devices(timeout=8.0, idle_timeout=3.0)`

Broadcast a scan and return a newline-separated list of discovered device IDs.

Reads until there has been idle_timeout seconds of silence on the bus or timeout seconds total have elapsed. The firmware scans multiple baud rates in sequence; idle_timeout must be long enough to span the gap between consecutive baud rate scans (default 3 s).

Parameters:

Name	Type	Description	Default
`timeout`	`float`	Maximum total wait time in seconds.	`8.0`
`idle_timeout`	`float`	Stop reading after this many seconds with no new data.	`3.0`

`set_baudrate(device_id, current_baudrate, new_baudrate)`

Change the baud rate stored on a device.

Parameters:

Name	Type	Description	Default
`device_id`	`int`	Target device ID.	required
`current_baudrate`	`int`	Active baud rate used for this transaction.	required
`new_baudrate`	`int`	Baud rate to persist on the device.	required

`set_device_id(current_device_id, new_device_id)`

Reassign the Dynamixel ID stored on a device.

Parameters:

Name	Type	Description	Default
`current_device_id`	`int`	Existing device ID used to address the device.	required
`new_device_id`	`int`	Replacement ID to persist on the device.	required

`set_operating_mode(device_id, op_mode)`

Set the operating mode of a device.

Parameters:

Name	Type	Description	Default
`device_id`	`int`	Target device ID.	required
`op_mode`	`str \| int`	Mode name (e.g. `"OP_POSITION"`) or integer code.	required

`set_position(device_id, position)`

Command a device to move to an absolute raw position.

`set_position_multiple(position_tuples)`

Command multiple devices to move simultaneously.

Parameters:

Name	Type	Description	Default
`position_tuples`	`list[tuple[int, int]]`	List of (device_id, position) pairs sent in a single packet.	required

`set_velocity(device_id, velocity)`

Set the velocity limit for a device (0-254).

`one_axis_stage.controller.StageController`

Coordinates one or more StageAxis instances over a shared serial connection.

Provides named-position storage, multi-axis simultaneous moves, and YAML-based configuration save/load. The recommended entry point is from_config rather than direct construction.

`config` `property` `writable`

Current controller state as a serialisable dictionary.

`add_axis(axis_name, **axis_config)`

Register a new axis on the controller and query its initial state.

Parameters:

Name	Type	Description	Default
`axis_name`	`str`	Logical name used to address the axis (e.g. `"x"`).	required
`**axis_config`		Keyword arguments forwarded to StageAxis (id, position_min, position_max, velocity_max, operating_mode).	`{}`

Returns:

Type	Description
`StageAxis`	The newly created StageAxis instance.

Raises:

Type	Description
`ValueError`	If an axis with the same name already exists.

`connect()`

Open the serial connection and query the stage ID.

`from_config(config_file)` `staticmethod`

Construct a StageController from a YAML config file or a pre-loaded dict.

Parameters:

Name	Type	Description	Default
`config_file`	`str \| Path \| dict`	Path to a YAML configuration file, or a dict with the same structure.	required

Returns:

Type	Description
`StageController`	A connected StageController with axes initialised.

Raises:

Type	Description
`FileNotFoundError`	If a path is given but the file does not exist.
`TypeError`	If config_file is not a str, Path, or dict.

`move_to_known_position(position_name)`

Move to a previously saved named position.

Parameters:

Name	Type	Description	Default
`position_name`	`str`	Key used when the position was saved with `save_as_known_position`.	required

Raises:

Type	Description
`ValueError`	If the position name is not found in `known_positions`.

`move_to_position(position)`

Move one or more axes to target raw positions in a single command.

Parameters:

Name	Type	Description	Default
`position`	`dict`	Mapping of axis name to target position. Value may be an integer raw position or a dict with a `"position_raw"` key.	required

Example

ctrl.move_to_position({"x": 300, "y": 500})

`ping_axes()`

Refresh device info for all registered axes.

`remove_known_position(position_name)`

Delete a named position from the known positions registry.

`save_as_known_position(position_name)`

Query all axes and store their current positions under a named key.

Parameters:

Name	Type	Description	Default
`position_name`	`str`	Label for the saved position.	required

`save_config(config_file, overwrite=True)`

Write the current controller configuration to a YAML file.

Parameters:

Name	Type	Description	Default
`config_file`	`str \| Path`	Destination path.	required
`overwrite`	`bool`	If False, raise FileExistsError when the file already exists.	`True`

Returns:

Type	Description
`bool`	True if the file was written successfully.

`one_axis_stage.axis.StageAxis`

Represents one motor axis with configurable position limits and velocity cap.

Wraps StageAPI calls for a specific device ID and enforces min/max position bounds on every move command before sending it to the controller.

`get_info()`

Query the device and update local state (position, velocity, operating mode).

Returns:

Type	Description
`dict`	Status dict from the firmware for this device.

`get_position()`

Query and return the current raw position, updating the local cache.

`set_operating_mode(op_mode)`

Set the operating mode for this axis.

Parameters:

Name	Type	Description	Default
`op_mode`	`str \| int`	Mode name (e.g. `"OP_POSITION"`) or integer code.	required

`set_position(position)`

Move to an absolute raw position, clamped to [position_min, position_max].

Parameters:

Name	Type	Description	Default
`position`	`int`	Target raw position in device units.	required

Raises:

Type	Description
`AssertionError`	If position is outside the configured bounds.

`set_velocity(velocity)`

Set the velocity limit, clamped to [0, velocity_max].

Parameters:

Name	Type	Description	Default
`velocity`	`int`	Target velocity in device units.	required

Raises:

Type	Description
`AssertionError`	If velocity exceeds the axis velocity_max.

`to_dict()`

Return axis configuration and current state as a plain dictionary.

`one_axis_stage.interface.MoveInterface`

Attaches per-axis increment helpers to a StageController.

For each axis registered on the controller, four bound methods are created dynamically at construction time:

<axis>p - move forward by small_increment
<axis>m - move backward by small_increment
<axis>pp - move forward by large_increment
<axis>mm - move backward by large_increment

Example

With axes x and y registered, the following are available::

move.xp()   # small step forward on x
move.ymm()  # large step backward on y

`move_axis_by_increment(axis_name, direction_forward=True, fast_mode=False)`

Move a named axis by one increment step.

Uses small_increment when fast_mode is False, large_increment otherwise. Out-of-bounds moves are silently swallowed and logged as errors.

Parameters:

Name	Type	Description	Default
`axis_name`	`str`	Name of the axis to move.	required
`direction_forward`	`bool`	True to increase position, False to decrease.	`True`
`fast_mode`	`bool`	If True, use large_increment instead of small_increment.	`False`

Raises:

Type	Description
`ValueError`	If axis_name is not registered on the controller.

API Reference

one_axis_stage.api.StageAPI

flash(device_id, duration_ms, repeats)

get_info(device_id)

get_info_all(device_ids)

get_position(device_id)

get_stage_id()

scan_for_devices(timeout=8.0, idle_timeout=3.0)

set_baudrate(device_id, current_baudrate, new_baudrate)

set_device_id(current_device_id, new_device_id)

set_operating_mode(device_id, op_mode)

set_position(device_id, position)

set_position_multiple(position_tuples)

set_velocity(device_id, velocity)

one_axis_stage.controller.StageController

config property writable

add_axis(axis_name, **axis_config)

connect()

from_config(config_file) staticmethod

move_to_known_position(position_name)

move_to_position(position)

ping_axes()

remove_known_position(position_name)

save_as_known_position(position_name)

save_config(config_file, overwrite=True)

one_axis_stage.axis.StageAxis

get_info()

get_position()

set_operating_mode(op_mode)

set_position(position)

set_velocity(velocity)

to_dict()

one_axis_stage.interface.MoveInterface

move_axis_by_increment(axis_name, direction_forward=True, fast_mode=False)

`one_axis_stage.api.StageAPI`

`flash(device_id, duration_ms, repeats)`

`get_info(device_id)`

`get_info_all(device_ids)`

`get_position(device_id)`

`get_stage_id()`

`scan_for_devices(timeout=8.0, idle_timeout=3.0)`

`set_baudrate(device_id, current_baudrate, new_baudrate)`

`set_device_id(current_device_id, new_device_id)`

`set_operating_mode(device_id, op_mode)`

`set_position(device_id, position)`

`set_position_multiple(position_tuples)`

`set_velocity(device_id, velocity)`

`one_axis_stage.controller.StageController`

`config` `property` `writable`

`add_axis(axis_name, **axis_config)`

`connect()`

`from_config(config_file)` `staticmethod`

`move_to_known_position(position_name)`

`move_to_position(position)`

`ping_axes()`

`remove_known_position(position_name)`

`save_as_known_position(position_name)`

`save_config(config_file, overwrite=True)`

`one_axis_stage.axis.StageAxis`

`get_info()`

`get_position()`

`set_operating_mode(op_mode)`

`set_position(position)`

`set_velocity(velocity)`

`to_dict()`

`one_axis_stage.interface.MoveInterface`

`move_axis_by_increment(axis_name, direction_forward=True, fast_mode=False)`