Motor accessor

MotorAccessor and MotorState provide typed motor read/move and state for the BCSz connection.

class resonance.api.core.motors.MotorState(position: float, goal: float, status: int, time: float)

Bases: object

Snapshot of a single motor’s state from BCS.

Parameters:

• position (float) – Current encoder position reported by BCS.

• goal (float) – Commanded target position.

• status (int) – Raw BCS status code for the motor.

• time (float) – Timestamp of the reading as reported by BCS.

goal: float

position: float

status: int

time: float

class resonance.api.core.motors.MotorAccessor(conn: BCSz.BCSServer)

Bases: object

High-level async interface for reading and commanding BCS motors.

Wraps the BCSz.BCSServer motor API with name validation, typed return values, and cooperative cancellation support.

Parameters:

conn (BCSz.BCSServer) – Active BCS server connection.

Examples

>>> motors = MotorAccessor(server)
>>> state = await motors.read("Sample X", "Sample Y")
>>> await motors.set("Sample X", 10.0)
>>> await motors.wait(["Sample X"])

async read(*names: str) → dict[str, MotorState]

Read the current state of one or more motors.

Parameters:

*names (str) – One or more motor names to query.

Returns:

Mapping of motor name to its current MotorState snapshot.

Return type:

dict[str, MotorState]

Raises:

KeyError – If any name is not in the valid motor list.

Examples

>>> states = await accessor.read("Sample X", "Sample Y")
>>> print(states["Sample X"].position)

async set(name: str, value: float, *, command: Command = 'Backlash Move') → None

Command a single motor to a target position.

Parameters:

• name (str) – Motor name to move.

• value (float) – Target position.

• command (Command, optional) – BCS command string, by default “Backlash Move”.

Return type:

None

Raises:

• KeyError – If name is not a valid motor.

• ValueError – If command is not a valid BCS command string.

Examples

>>> await accessor.set("Sample X", 5.0)
>>> await accessor.set("Sample X", 5.0, command="Normal Move")

async set_many(targets: dict[str, float], *, command: Command = 'Backlash Move') → None

Command multiple motors to target positions simultaneously.

Parameters:

• targets (dict[str, float]) – Mapping of motor name to target position.

• command (Command, optional) – BCS command string applied to all motors, by default “Backlash Move”.

Return type:

None

Raises:

• KeyError – If any motor name in targets is not valid.

• ValueError – If command is not a valid BCS command string.

Examples

>>> await accessor.set_many({"Sample X": 5.0, "Sample Y": -2.5})

async wait(names: list[str], timeout: float = 30.0, abort: AbortFlag | None = None) → None

Wait for one or more motors to reach their target positions.

Parameters:

• names (list[str]) – Motor names to wait on.

• timeout (float, optional) – Maximum seconds to wait before raising MotorTimeoutError, by default 30.0.

• abort (AbortFlag or None, optional) – If provided, the wait will raise ScanAbortedError when the flag is set.

Return type:

None

Raises:

• KeyError – If any name is not a valid motor.

• MotorTimeoutError – If any motor does not reach its target within timeout seconds.

• ScanAbortedError – If abort flag is set during the wait.

Notes

Delegates to wait_for_motors from resonance.api.core.primitives. Pass an AbortFlag to enable cooperative cancellation from Jupyter or programmatic interfaces: set the flag from another task/cell to stop waiting and raise ScanAbortedError.

Examples

>>> flag = AbortFlag()
>>> await accessor.set_many({"Sample X": 10.0, "Sample Y": 5.0})
>>> await accessor.wait(["Sample X", "Sample Y"], timeout=60.0, abort=flag)