pub struct Robot { /* private fields */ }Expand description
A two-motor differential-drive robot controller.
The robot smoothly ramps motor speeds from the current value to the target
in a background task. Call drive to set target speeds and
stop to decelerate to zero.
§Shutdown
Await shutdown to close command admission, join the
adjustment task and finish the final stop attempt. Stop failures are logged
and retained in status.
Dropping the last public handle requests best-effort asynchronous cleanup
while the Tokio runtime remains alive; it does not wait for motor I/O.
Implementations§
Source§impl Robot
impl Robot
Sourcepub fn new(
motor_board: Arc<Mutex<dyn MotorDriver>>,
config: RobotConfig,
) -> Result<Arc<Self>, RobotError>
pub fn new( motor_board: Arc<Mutex<dyn MotorDriver>>, config: RobotConfig, ) -> Result<Arc<Self>, RobotError>
Create a new robot with the given motor driver and configuration.
Spawns an adjustment task and its cleanup task. They share internal state without retaining the public handle. Shutdown or last-handle drop requests cancellation; cleanup joins adjustment before attempting to stop all motors.
§Errors
Returns RobotError::Motor wrapping MotorError::Init if the
configuration is invalid. No controller task or driver writes are started
on validation failure; constructing the driver itself may access hardware.
Sourcepub async fn drive(&self, left: f32, right: f32) -> Result<(), RobotError>
pub async fn drive(&self, left: f32, right: f32) -> Result<(), RobotError>
Set target motor speeds.
Finite values are clamped to [-1.0, 1.0], multiplied by the motor factors
from RobotConfig, then clamped again to the supported output range.
A non-finite input rejects the entire command without changing targets.
Both targets are accepted atomically; success means target acceptance,
not hardware application. The task ramps each motor independently and
writes the motors sequentially from one paired target snapshot.
§Errors
Returns RobotError::Shutdown if admission closed without a fault.
A latched failure returns RobotError::Motor wrapping MotorError::Pwm
with the retained diagnostic; it takes precedence over shutdown.
Returns RobotError::Motor wrapping MotorError::Pwm for a non-finite
input, retaining the existing error API.
Sourcepub async fn stop(&self) -> Result<(), RobotError>
pub async fn stop(&self) -> Result<(), RobotError>
Atomically set both target speeds to zero (motors ramp down independently).
§Errors
Returns RobotError::Shutdown after normal admission closure, or
RobotError::Motor wrapping MotorError::Pwm with a latched failure.
Sourcepub async fn status(&self) -> RobotStatus
pub async fn status(&self) -> RobotStatus
Read a consistent snapshot of lifecycle, output certainty and failures.
Does not perform I/O. A successful drive accepts targets only; it does not confirm hardware application. A fault stays visible after cleanup and explicit shutdown, even when the final stop succeeds.
Sourcepub async fn shutdown(&self)
pub async fn shutdown(&self)
Close command admission, join adjustment, then finish the final stop attempt.
Repeated/concurrent calls wait for the same cleanup. Once admission closes, dropping a shutdown future does not cancel cleanup. No adjustment writes occur after this method returns. It does not ramp down before stopping.
Driver failures are logged and retained in status;
the legacy () return value does not
confirm electrical stopping or mechanical standstill. An in-flight driver
operation must finish before cleanup can proceed; blocked I/O can delay
shutdown indefinitely. The Tokio runtime must remain alive for cleanup.