fix: improve ultrasonic sensor reliability with retry logic and timing optimizations

- Add retry logic: sensor attempts reading twice with 20ms delay on failure
- Add echo pin pre-check to detect stuck-high wiring issues early
- Move eventlog calls after timing-sensitive measurements to prevent interference
- Update distance calculation to use integer math (duration * 100 // 582)
- Increase timeout from 14.5ms to 30ms for better sensor tolerance
- Optimize trigger pulse timing (5μs stabilization, removed 30ms pre-delay)
- Correct GPIO pin assignments and documentation (trig=GP6, echo=GP7)
- Add diagnostic test script for ultrasonic sensor debugging
- Fix Assembly_Instructions.md test script to call main()

These changes address intermittent sensor readings while maintaining student-friendly debugging features.

Author: benpaddlejones

_Firmware/AI_Driver_RP2040.uf2

@@ -1,4 +1,4 @@
-Build Date: Thu Feb 12 06:29:17 UTC 2026
+Build Date: Fri Feb 20 05:35:39 UTC 2026
 MicroPython Version: v1.28.0-preview-62-g0fd084363 (0fd084363, 2026-01-09)
 Custom Modules: 4 files
 Build Host: codespaces-35b014

_Firmware/build_info.txt

@@ -136,4 +136,8 @@ def main():
         hold_state(0.5)
 
     print("All hardware tests completed.")
+
+
+if __name__ == "__main__":
+    main()
 ```

docs/Assembly_Instructions.md

@@ -290,10 +290,9 @@ def __init__(self, trig_pin, echo_pin):
         self.trig_pin.off()
 
         # Sensor configuration
-        self.sound_speed_mm_us = 0.343  # Speed of sound in mm/μs
         self.max_distance_mm = 2000  # Max sensor range in mm
-        # Calculate timeout based on max distance
-        self.timeout_us = int(self.max_distance_mm * 2.5 / self.sound_speed_mm_us)
+        # Timeout: 30,000μs allows ~2x longer echo wait (500 * 2 * 30)
+        self.timeout_us = 30000
 
     def read_distance_mm(self):
         """
@@ -302,46 +301,69 @@ def read_distance_mm(self):
         Returns:
             int: Distance in millimeters, or -1 if the reading is out of range or fails.
         """
-        # Add a delay to allow the sensor to settle between readings.
-        sleep_ms(30)
+        # Pre-check: ensure echo pin is LOW (not stuck high from wiring issue)
+        if self.echo_pin.value() != 0:
+            _ultrasonic_warn_inline("Echo pin stuck HIGH – check wiring")
+            if _ultrasonic_fail_count <= 3 and eventlog is not None:
+                try:
+                    eventlog.log_event("ultrasonic echo pin stuck high")
+                except Exception:
+                    pass
+            return -1
 
-        # Send a 10μs trigger pulse
+        # Send a 10μs trigger pulse with 5μs stabilization
         self.trig_pin.off()
-        sleep_us(2)
+        sleep_us(5)
         self.trig_pin.on()
         sleep_us(10)
         self.trig_pin.off()
 
         try:
-            # Measure the duration of the echo pulse
+            # Measure the duration of the echo pulse (with retry on failure)
             duration = time_pulse_us(self.echo_pin, 1, self.timeout_us)
 
             # time_pulse_us returns -1 on timeout and -2 on invalid state
             if duration < 0:
-                _ultrasonic_warn_inline("Sensor error – check wiring")
-                # Only log to eventlog on first few failures to avoid log spam
-                if _ultrasonic_fail_count <= 3 and eventlog is not None:
-                    try:
-                        eventlog.log_event("ultrasonic timeout or invalid echo")
-                    except Exception:
-                        pass
-                return -1
-
-            # Calculate distance in mm: (duration * speed_of_sound) / 2
-            distance_mm = (duration * self.sound_speed_mm_us) / 2
+                # Retry once after brief delay to handle transient issues
+                sleep_ms(20)  # Let sensor settle
+                self.trig_pin.off()
+                sleep_us(5)
+                self.trig_pin.on()
+                sleep_us(10)
+                self.trig_pin.off()
+                duration = time_pulse_us(self.echo_pin, 1, self.timeout_us)
+                
+                # If still failing after retry, report error
+                if duration < 0:
+                    _ultrasonic_warn_inline("Sensor error – check wiring")
+                    # Only log to eventlog on first few failures to avoid log spam
+                    if _ultrasonic_fail_count <= 3 and eventlog is not None:
+                        try:
+                            eventlog.log_event("ultrasonic timeout or invalid echo")
+                        except Exception:
+                            pass
+                    return -1
+
+            # Calculate distance in mm using integer math (avoids floating point)
+            # Sound speed: 343.2 m/s = 0.3432 mm/μs
+            # distance = (time * speed) / 2, so: time * 100 // 582
+            distance_mm = duration * 100 // 582
 
             # Check if the reading is within the valid range (20mm to 2000mm)
             if 20 <= distance_mm <= self.max_distance_mm:
                 # Clear any inline warning since we got a good reading
                 _ultrasonic_warn_clear()
+                result = int(distance_mm)
+                
+                # Log AFTER timing-sensitive measurement is complete
                 if eventlog is not None:
                     try:
                         eventlog.log_event(
-                            "distance reading: {} mm".format(int(distance_mm))
+                            "distance reading: {} mm".format(result)
                         )
                     except Exception:
                         pass
-                return int(distance_mm)
+                return result
 
             # Out of range – likely too close, too far, or pointing into open space
             _ultrasonic_warn_inline("Out of range ({}mm)".format(int(distance_mm)))
@@ -467,26 +489,26 @@ class AIDriver:
 
     def __init__(
         self,
-        right_speed_pin=3,  # GP2 (PWM capable)
-        left_speed_pin=11,  # GP3 (PWM capable)
-        right_dir_pin=12,  # GP4
-        right_brake_pin=9,  # GP5
-        left_dir_pin=13,  # GP6
-        left_brake_pin=8,  # GP7
-        trig_pin=6,  # GP8
-        echo_pin=7,  # GP9
+        right_speed_pin=3,  # GP3 (PWM capable)
+        left_speed_pin=11,  # GP11 (PWM capable)
+        right_dir_pin=12,  # GP12
+        right_brake_pin=9,  # GP9
+        left_dir_pin=13,  # GP13
+        left_brake_pin=8,  # GP8
+        trig_pin=6,  # GP6
+        echo_pin=7,  # GP7
     ):
         """Initialize RP2040 based AIDriver differential drive robot.
 
         Args:
-            right_speed_pin: PWM pin for right motor speed (default GP2)
-            left_speed_pin: PWM pin for left motor speed (default GP3)
-            right_dir_pin: Digital pin for right motor direction (default GP4)
-            right_brake_pin: Digital pin for right motor brake (default GP5)
-            left_dir_pin: Digital pin for left motor direction (default GP6)
-            left_brake_pin: Digital pin for left motor brake (default GP7)
-            trig_pin: Ultrasonic sensor trigger pin (default GP8)
-            echo_pin: Ultrasonic sensor echo pin (default GP9)
+            right_speed_pin: PWM pin for right motor speed (default GP3)
+            left_speed_pin: PWM pin for left motor speed (default GP11)
+            right_dir_pin: Digital pin for right motor direction (default GP12)
+            right_brake_pin: Digital pin for right motor brake (default GP9)
+            left_dir_pin: Digital pin for left motor direction (default GP13)
+            left_brake_pin: Digital pin for left motor brake (default GP8)
+            trig_pin: Ultrasonic sensor trigger pin (default GP6)
+            echo_pin: Ultrasonic sensor echo pin (default GP7)
         """
 
         # Library-side preflight: log pin config and attempt a quick sensor ping

project/lib/aidriver.py

@@ -0,0 +1,44 @@
+"""
+Raw ultrasonic sensor diagnostic test
+Upload this to your Pico and run it to diagnose the sensor readings.
+"""
+
+from machine import Pin, time_pulse_us
+from time import sleep_us, sleep_ms
+
+print("\n=== Ultrasonic Sensor Raw Test ===")
+print("Testing with current pin configuration:")
+print("  Trigger: GPIO 6")
+print("  Echo:    GPIO 7")
+print()
+
+echo = Pin(7, Pin.IN)   # Echo on GPIO 7
+trig = Pin(6, Pin.OUT)  # Trigger on GPIO 6
+
+# Initial state check
+print(f"Initial echo pin state: {echo.value()} (should be 0)")
+print()
+
+# Take 5 raw readings
+print("Taking 5 readings...")
+for i in range(5):
+    trig.off()
+    sleep_us(5)
+    trig.on()
+    sleep_us(10)
+    trig.off()
+    
+    duration = time_pulse_us(echo, 1, 30000)
+    
+    if duration < 0:
+        print(f"Reading {i+1}: TIMEOUT (duration={duration})")
+    else:
+        distance = duration * 100 // 582
+        print(f"Reading {i+1}: duration={duration:5d} μs, distance={distance:4d} mm")
+    
+    sleep_ms(100)  # 100ms between readings
+
+print()
+print("=== Test Complete ===")
+print("If all readings show same value, try moving obstacle closer/farther")
+print("If all show TIMEOUT, check wiring")