RP2040 Competition Simulator

Help & Reference

Import once at the top of every challenge:

from aidriver import AIDriver, hold_state
import aidriver

aidriver.DEBUG_AIDRIVER = False    # set True for verbose logs
my_robot = AIDriver("left")        # or AIDriver("right")

Sensors

my_robot.read_distance() Front ultrasonic. Returns mm (20–2000) or -1 if out of range / no echo.

my_robot.read_distance_2() Side ultrasonic (the wall-follow sensor). Same units, same -1 sentinel — used to detect outside corners.

Driving

my_robot.drive(right_speed, left_speed) Preferred for PID. Signed speeds (-255…255): positive = forward, negative = backward. Anything with abs(speed) < 100 stops that wheel (MIN_MOTOR_SPEED dead zone).

my_robot.drive_forward(right_speed, left_speed) Both wheels forward at unsigned speeds (0–255).

my_robot.drive_backward(right_speed, left_speed) Both wheels backward at unsigned speeds (0–255).

my_robot.rotate_left(turn_speed) Spin in place counter-clockwise at turn_speed.

my_robot.rotate_right(turn_speed) Spin in place clockwise at turn_speed.

my_robot.brake() Cut power to both motors.

State / Diagnostics

my_robot.wall_sign Property: -1 when constructed with "left", +1 for "right". Multiply your steering term by it so the same code mirror-solves both modes.

my_robot.get_motor_speeds() Returns the last commanded (right_speed, left_speed) tuple.

my_robot.is_moving() Returns True if either wheel is currently powered.

my_robot.service() Tick the safety heartbeat. Called for you by hold_state() — only call it directly if you write your own busy loop.

Module Helpers

hold_state(seconds) Pause for seconds while servicing the heartbeat and logging current state. Use this — never time.sleep().

aidriver.DEBUG_AIDRIVER = True / False Toggle verbose [AIDriver] log output. Off by default in answers; turn it on while debugging your own code.

aidriver.heartbeat(period_ms=1000) Manual LED + safety heartbeat tick (advanced — normally handled automatically by hold_state).

Constants

MIN_MOTOR_SPEED = 100 — wheels below this stall. Any BASE_SPEED - MAX_STEERING must stay ≥ 100.
Ultrasonic range: 20 mm – 2000 mm. Outside this range both read_distance() and read_distance_2() return -1.

Speed Guidelines

0–99: Below dead zone — wheel stops
100–140: Slow / careful
141–200: Normal cruise
201–255: Fast — watch for slip on turns

Keyboard Shortcuts

Ctrl+Enter - Run code
Ctrl+. - Stop execution
Ctrl+Shift+R - Reset robot

Troubleshooting

Having issues? Download a debug log to share with your teacher or for troubleshooting.