Hardware interface, safety and runtime#

Running the system on a robot: a hardware interface, an independent safety filter and a fixed-rate control loop.

Nothing in this module has been run on real hardware. SimulatedHardware implements the interface on the simulator so the loop, the safety filter and the failure handling are tested; a dev-kit driver has to implement MotorHardware (three methods) and be validated on the bench.

The safety filter (SafetyLayer) sits between every command and the motor and does not depend on the learned model, the agent, the supervisor or a language model: it clamps the command, limits its rate of change, refuses to drive past soft position limits, and latches a stop that only a human releases. If the loop raises for any reason the runtime calls hardware.stop() before the exception leaves it.

Sensors the agent needs: a position encoder (workspace units, -1..1) and an accelerometer on the moving part (a_mems, m/s^2). A drive with an encoder only cannot run MotorAgent as it is; ControlRuntime refuses to start rather than run degraded without saying so. The quantum accelerometer (a_q) is optional, and no quantum accelerometer exists on a dev kit: it is simulated.

Classes

`MotorHardware`	What a dev-kit driver must provide.
`SimulatedHardware`	The simulator behind the `MotorHardware` interface.
`SafetyLimits`
`SafetyLayer`	Last line of defence between any command and the motor; independent of the AI.
`ControlRuntime`	Fixed-rate loop: read, estimate, control, supervise, filter for safety, write.

class MotorHardware(*args, **kwargs)[source]#

Bases: Protocol

What a dev-kit driver must provide.

read()[source]#

{'t': seconds, 'enc': position in -1..1 or None, 'a_mems': m/s^2 or None, 'a_q': m/s^2 or None} (latest values).

Return type:: dict

write(u)[source]#

Send a normalised command in [-1, 1] (the driver maps it to voltage, PWM or current).

Parameters:: u (float)
Return type:: None

stop()[source]#

Cut torque / apply the brake. Must be safe to call at any time, repeatedly.

Return type:: None

class SimulatedHardware(faults=(), seed=0, theta0=0.0, drop_telemetry_at=None, **kw)[source]#

Bases: object

The simulator behind the MotorHardware interface.

class SafetyLimits(u_max: 'float' = 0.8, slew: 'float' = 0.25, soft_limit: 'float' = 0.95)[source]#

Bases: object

Parameters:

u_max (float)
slew (float)
soft_limit (float)

class SafetyLayer(limits=None)[source]#

Bases: object

Last line of defence between any command and the motor; independent of the AI.

release()[source]#: Human action only.

class ControlRuntime(hardware, act, brain=None, safety=None, heal=True, dt=0.05)[source]#

Bases: object

Fixed-rate loop: read, estimate, control, supervise, filter for safety, write. One step() is one control period.

run(steps, schedule=None)[source]#: Run steps periods; schedule maps a step index to a new target.