s6.robotic package

Submodules

s6.robotic.client module

Client for the Robotic REST API.

Thin HTTP client with a background worker thread to serialize commands to the robotic service (s6.robotic.service). This allows callers to enqueue motion and waypoint operations without blocking the UI loop.

Examples

>>> client = RoboticClient("http://localhost:8000")
>>> client.move("x", 1.5)  # distance in axis units (e.g., mm)
>>> client.set_waypoint("inspect")
>>> client.to_waypoint("home")
>>> client.list_waypoints()
[{"name": "home", "positions": {"x": 0, "y": 0}}]

class s6.robotic.client.RoboticClient(base_url: str)

Bases: object

Non-blocking client for robotic motion and waypoint commands.

Parameters:

base_url (str) – Base URL of the server (e.g., "http://localhost:8000"). A trailing slash is stripped.

Notes

All public methods enqueue tasks onto a background worker thread which executes requests sequentially. Use enqueue() to schedule custom callables.

delete_waypoint(name: str)

Enqueue deletion of a named waypoint.

Parameters:

name (str) – Waypoint name to remove.

enqueue(func)

Schedule a callable on the background worker.

The callable is executed sequentially with previously enqueued tasks.

list_waypoints()

Fetch the list of stored waypoints.

Returns:

Each item has keys name and positions. For the Pydantic model, see s6.schema.robotic.Waypoint.

Return type:

list of dict

move(axis: str, offset: float)

Enqueue a relative move for an axis.

Parameters:

• axis (str) – Axis name (e.g., "x", "y").

• offset (float) – Relative distance to move in the axis’s distance units (e.g., millimeters). See s6.robotic.stepper for conversion.

set_waypoint(name: str)

Enqueue saving a named waypoint from current positions.

Parameters:

name (str) – Waypoint identifier. Overwrites if it already exists.

to_waypoint(name: str)

Enqueue moving all axes to a named waypoint.

Parameters:

name (str) – Name of an existing waypoint.

zero()

Enqueue homing to zero for all axes.

s6.robotic.service module

Robotic service utilities and FastAPI endpoints.

This module wires s6.robotic.stepper.Axis instances from configuration (s6.schema.robotic.RoboticConfig) and exposes a set of operations for motion and waypoint management. A small FastAPI router is provided to publish these operations over HTTP.

The top-level helpers (e.g., move(), to_waypoint()) implement the core behavior and can be used directly without running the web service.

class s6.robotic.service.MoveRequest(*, axis: str, offset: int)

Bases: BaseModel

Request body for POST /robotic/move.

axis: str

offset: int

class s6.robotic.service.WaypointNameRequest(*, name: str)

Bases: BaseModel

Request body containing a waypoint name.

name: str

s6.robotic.service.axes() → Dict[str, Axis]

Build and cache axis drivers from configuration.

Returns:

Mapping of axis name to s6.robotic.stepper.Axis driver.

Return type:

Dict[str, Axis]

Notes

Positions are loaded from the config on first access and persisted on interpreter exit. Boundaries are set to [-30, 30] in distance units.

s6.robotic.service.delete_waypoint(name: str) → bool

Delete a waypoint by name and persist the change.

Parameters:

name (str) – Waypoint to remove.

Returns:

True if a waypoint was removed, False if none matched.

Return type:

bool

s6.robotic.service.delete_waypoint_endpoint(name: str)

s6.robotic.service.list_waypoints() → List[Waypoint]

Return the list of stored waypoints.

Returns:

See s6.schema.robotic.Waypoint for the schema.

Return type:

list of Waypoint

s6.robotic.service.list_waypoints_endpoint()

s6.robotic.service.move(axis: str, offset: int)

Move an axis by a relative distance and persist positions.

Parameters:

• axis (str) – Axis name (e.g., "x", "y").

• offset (int) – Relative distance in axis units (e.g., millimeters). Converted to steps via calibration.

s6.robotic.service.move_endpoint(req: MoveRequest)

s6.robotic.service.set_brightness(duty_cycle: float)

Set the IR LED duty cycle.

Notes

This function delegates to an ir_led() provider which is expected to be available in the application runtime. It is left intentionally untyped here since it is an integration point.

s6.robotic.service.set_waypoint(name: str)

Create or update a named waypoint.

The current positions of all axes are stored under name.

Parameters:

name (str) – Waypoint identifier. Replaces any existing waypoint with the same name.

s6.robotic.service.set_waypoint_endpoint(req: WaypointNameRequest)

s6.robotic.service.to_waypoint(name: str)

Move axes to a previously saved named waypoint.

Parameters:

name (str) – Name of an existing s6.schema.robotic.Waypoint.

s6.robotic.service.to_waypoint_endpoint(req: WaypointNameRequest)

s6.robotic.service.zero()

Zero all axes by moving back to position 0.

s6.robotic.service.zero_endpoint()

s6.robotic.stepper module

Stepper axis drivers over RS-485 serial.

Implements a minimal driver for a stepper controller board accessed via a shared serial connection. The Axis class provides convenient motion primitives in distance units; conversion to integer steps is handled via calibration parameters.

Notes

• Positions are tracked in integer steps. Distances (e.g., millimeters) are converted using distance_per_revolution and step_per_revolution.

• Commands are serialized to the controller and acknowledgements are awaited. See LinearController.wait_for_ack() for timing behavior.

class s6.robotic.stepper.Axis(address, distance_per_revolution, step_per_revolution, nominal_speed=32, nominal_acceleration=32, name='')

Bases: LinearController

High-level axis controller with distance-based helpers.

goto(position)

Move to an absolute position in steps.

property max_boundary_steps

Maximum allowed position in steps (relative to zero).

property min_boundary_steps

Minimum allowed position in steps (relative to zero).

move(distance, max_speed=-1, acceleration=-1)

Move by a relative linear distance.

Parameters:

• distance (float) – Travel in distance units (e.g., mm). Converted to steps internally.

• max_speed (int, default -1) – Optional speed override.

• acceleration (int, default -1) – Optional acceleration override.

round_trip(distance, max_speed=-1, acceleration=-1)

Context manager for a symmetric outbound and return motion.

Parameters:

• distance (float) – Outbound distance before yielding control.

• max_speed (int, default -1) – Optional speed override.

• acceleration (int, default -1) – Optional acceleration override.

Yields:

None – Control is returned to the caller between outbound and return legs.

run_boundary()

Context manager to traverse from min to max boundaries.

sweep(step_size=1, delay=0.01)

Iterate positions across the boundary range.

Parameters:

• step_size (float, default 1) – Step size in distance units between samples.

• delay (float, default 0.01) – Sleep time between moves, in seconds.

Yields:

None – After each move, yields control to the caller.

zero(max_speed=-1, acceleration=-1)

Move back to absolute position 0 and reset the tracker.

class s6.robotic.stepper.LinearController(address, distance_per_revolution, step_per_revolution, nominal_speed=32, nominal_acceleration=32, name='')

Bases: object

Base controller implementing low-level step and boundary logic.

Parameters:

• address (int) – Device address on the bus.

• distance_per_revolution (float) – Linear travel per motor revolution (e.g., mm/rev).

• step_per_revolution (int) – Controller steps per revolution.

• nominal_speed (int, default 32) – Default step speed (device-specific units).

• nominal_acceleration (int, default 32) – Default acceleration (device-specific units).

• name (str, default "") – Optional label for logging.

BWD = 0

FWD = 128

distance_to_step(distance)

Convert a linear distance to integer steps.

Parameters:

distance (float) – Travel in the same units as distance_per_revolution.

Returns:

Number of controller steps.

Return type:

int

set_boundaries(min_boundary, max_boundary)

Set motion boundaries in distance units.

The provided limits are converted to steps and enforced on subsequent motions.

Parameters:

• min_boundary (float) – Minimum allowable position (distance units).

• max_boundary (float) – Maximum allowable position (distance units).

step(steps, speed: int = -1, start_acc: int = -1)

Issue a step command with optional speed/acceleration overrides.

Parameters:

• steps (int) – Signed number of steps. Positive moves forward; negative backward.

• speed (int, default -1) – Override for speed; when <= 0 uses nominal_speed.

• start_acc (int, default -1) – Override for acceleration; when <= 0 uses nominal_acceleration.

Notes

Boundaries are enforced; if the motion would exceed limits the step count is clipped so the final position lies on the boundary.

wait_for_ack(delay_time)

Wait for an acknowledgement frame or timeout.

Parameters:

delay_time (float) – Maximum time (seconds) to wait before returning 0.

Returns:

Non-zero code on success; 0 on timeout.

Return type:

int

class s6.robotic.stepper.SerialConnection(port, baudrate, timeout)

Bases: object

Thread-safe singleton for a shared serial port.

Parameters:

• port (str) – Serial device path (e.g., "COM4" or "/dev/ttyUSB0").

• baudrate (int) – Port speed in baud.

• timeout (float) – Read timeout in seconds.

Notes

All instances return the same underlying connection. Use the :pyattr:`connection` property to access the configured serial.Serial object.

property connection

Return the underlying serial.Serial connection.

s6.robotic.test_service module

class s6.robotic.test_service.TestRoboticService(methodName='runTest')

Bases: TestCase

Unit tests for robotic RPC service waypoint endpoints.

setUp()

Hook method for setting up the test fixture before exercising it.

tearDown()

Hook method for deconstructing the test fixture after testing it.

test_delete_nonexistent_waypoint()

test_delete_waypoint()

test_list_initial_waypoints()

test_set_waypoint_and_list()

test_to_waypoint_moves_axes()

s6.robotic.test_stepper module

class s6.robotic.test_stepper.FakeSerial(port=None, baudrate=None, timeout=None)

Bases: object

Fake serial.Serial replacement for testing.

flush()

property in_waiting

read(size=1)

write(data)

class s6.robotic.test_stepper.TestAxis(methodName='runTest')

Bases: TestCase

Unit tests for Axis extension of LinearController.

setUp()

Hook method for setting up the test fixture before exercising it.

tearDown()

Hook method for deconstructing the test fixture after testing it.

test_goto_calls_step()

test_min_max_boundary_steps()

test_move_calls_step()

test_round_trip_context_manager()

test_run_boundary_context_manager()

test_sweep_generator()

test_zero_resets_position()

class s6.robotic.test_stepper.TestLinearController(methodName='runTest')

Bases: TestCase

Unit tests for LinearController methods.

setUp()

Hook method for setting up the test fixture before exercising it.

tearDown()

Hook method for deconstructing the test fixture after testing it.

test_distance_to_step()

test_set_boundaries()

test_step_positive_and_negative()

test_step_respects_boundaries()

test_wait_for_ack_success()

test_wait_for_ack_timeout()

class s6.robotic.test_stepper.TestSerialConnection(methodName='runTest')

Bases: TestCase

Tests for the SerialConnection singleton behavior.

setUp()

Hook method for setting up the test fixture before exercising it.

tearDown()

Hook method for deconstructing the test fixture after testing it.

test_connection_property_returns_serial()

test_singleton_same_instance()

Module contents

Robotic control package.

Provides high-level client and server utilities plus a low-level stepper axis driver for Sense Core’s robotic subsystem.

Key concepts

• Axes are modeled by s6.robotic.stepper.Axis with positions in integer steps; distances are converted via per-axis calibration.

• A REST API (see s6.robotic.service) exposes motion and waypoint operations for remote control.

• s6.robotic.client.RoboticClient offers a simple, non-blocking HTTP client with a background worker queue.

Typical usage involves constructing axes from configuration (s6.schema.robotic.RoboticConfig), moving to named waypoints, and persisting positions on exit.

class s6.robotic.Axis(address, distance_per_revolution, step_per_revolution, nominal_speed=32, nominal_acceleration=32, name='')

Bases: LinearController

High-level axis controller with distance-based helpers.

goto(position)

Move to an absolute position in steps.

property max_boundary_steps

Maximum allowed position in steps (relative to zero).

property min_boundary_steps

Minimum allowed position in steps (relative to zero).

move(distance, max_speed=-1, acceleration=-1)

Move by a relative linear distance.

Parameters:

• distance (float) – Travel in distance units (e.g., mm). Converted to steps internally.

• max_speed (int, default -1) – Optional speed override.

• acceleration (int, default -1) – Optional acceleration override.

round_trip(distance, max_speed=-1, acceleration=-1)

Context manager for a symmetric outbound and return motion.

Parameters:

• distance (float) – Outbound distance before yielding control.

• max_speed (int, default -1) – Optional speed override.

• acceleration (int, default -1) – Optional acceleration override.

Yields:

None – Control is returned to the caller between outbound and return legs.

run_boundary()

Context manager to traverse from min to max boundaries.

sweep(step_size=1, delay=0.01)

Iterate positions across the boundary range.

Parameters:

• step_size (float, default 1) – Step size in distance units between samples.

• delay (float, default 0.01) – Sleep time between moves, in seconds.

Yields:

None – After each move, yields control to the caller.

zero(max_speed=-1, acceleration=-1)

Move back to absolute position 0 and reset the tracker.

class s6.robotic.RoboticClient(base_url: str)

Bases: object

Non-blocking client for robotic motion and waypoint commands.

Parameters:

base_url (str) – Base URL of the server (e.g., "http://localhost:8000"). A trailing slash is stripped.

Notes

All public methods enqueue tasks onto a background worker thread which executes requests sequentially. Use enqueue() to schedule custom callables.

delete_waypoint(name: str)

Enqueue deletion of a named waypoint.

Parameters:

name (str) – Waypoint name to remove.

enqueue(func)

Schedule a callable on the background worker.

The callable is executed sequentially with previously enqueued tasks.

list_waypoints()

Fetch the list of stored waypoints.

Returns:

Each item has keys name and positions. For the Pydantic model, see s6.schema.robotic.Waypoint.

Return type:

list of dict

move(axis: str, offset: float)

Enqueue a relative move for an axis.

Parameters:

• axis (str) – Axis name (e.g., "x", "y").

• offset (float) – Relative distance to move in the axis’s distance units (e.g., millimeters). See s6.robotic.stepper for conversion.

set_waypoint(name: str)

Enqueue saving a named waypoint from current positions.

Parameters:

name (str) – Waypoint identifier. Overwrites if it already exists.

to_waypoint(name: str)

Enqueue moving all axes to a named waypoint.

Parameters:

name (str) – Name of an existing waypoint.

zero()

Enqueue homing to zero for all axes.