Concepts

Skills

Skills are higher-level behaviors built on tools, registered when their prerequisites are present. The flagship is drive_until_obstacle — it drives forward while a second thread polls the ultrasonic sensor, stopping when an obstacle is within target_cm. Drive and sensing run on separate threads sharing a stop event.

drive_until_obstacle(target_cm=5.0, max_speed=25.0, timeout_s=15.0)

Param	Default	Range	Meaning
`target_cm`	5.0	2.0–100.0	Stop when an obstacle is this close
`max_speed`	25.0	10.0–60.0	Top speed; eased down on approach
`timeout_s`	15.0	0.5–30.0	Hard wall-clock cap on the run

Behavior

Approach-speed curve (v3.9.1): full speed when far, ~60% between 1.5× and 3× target, ~35% below 1.5× (floored at 10). Decel starts early so overshoot stays small.
Continuous motion (v3.9.3): with the live SunFounder adapter the motor runs continuously, re-issuing only when the speed band changes — no start/stop jitter. Falls back to a pulsed path otherwise.
Obstacle confirmation: requires 2 consecutive sub-threshold reads, with a target_cm + 2 cm trigger margin.
Sensor-noise tolerance (v3.9.5): halts on consecutive bad reads (_MAX_CONSECUTIVE_BAD_READS = 20 ≈ 1.0 s), not a lifetime count — tolerating motor-EMI bursts while still catching sustained faults.

Result field	Meaning
`success`	`True` unless a prerequisite tool was unavailable
`stop_reason`	`"obstacle at X cm"`, `"sensor failing"`, `"timeout"`, or `"stopped"`
`final_distance_cm`	Last sensor reading
`stop_distance_cm`	Distance at which the obstacle was confirmed
`sensor_failures`	Cumulative bad-read count (diagnostics)