First commit

2026-07-30 16:19:15 -04:00
parent fbc5b3d4d3
commit d51ad8db38
12 changed files with 888 additions and 0 deletions
@@ -0,0 +1,128 @@
+# Distance-Driven Robot with Tilt Detection
+
+This project controls a small two-wheel robot that travels toward a target based on an ultrasonic distance measurement. The robot waits for the user to press a button, calculates the required number of motor steps, drives both stepper motors, and continuously checks its accelerometer for unsafe tilt.
+
+The OLED screen, LED, and buzzer provide clear status feedback throughout the process.
+
+## Features
+
+- Button-controlled start
+- Ultrasonic distance measurement
+- Automatic distance-to-step conversion
+- Synchronized left and right stepper-motor movement
+- Continuous Y-axis tilt monitoring
+- OLED status and result messages
+- Audible success and warning signals
+- LED warning when the robot tilts
+- Repeating operation for multiple runs
+
+## Hardware
+
+The program expects the hardware objects configured in `main.py`:
+
+- LED
+- Push button
+- Buzzer
+- Two stepper motors (left and right)
+- Ultrasonic distance sensor
+- OLED display
+- Accelerometer
+
+Refer to the object initialization section at the top of `main.py` for the GPIO pins, I²C addresses, and other board-specific configuration used by your build.
+
+> **Safety:** Place the robot on a clear, level surface before pressing the button. Be ready to lift or power off the robot if it approaches an obstacle or edge.
+
+## How it works
+
+The main control loop runs continuously:
+
+1. The warning LED is turned off.
+2. The OLED is cleared and displays **Press button to start**.
+3. `wait_button_press()` blocks execution until the user presses the button.
+4. The buzzer beeps once to confirm the start.
+5. The ultrasonic sensor measures the distance to the target.
+6. `get_steps_from_distance(distance)` converts that measurement into a motor-step count.
+7. The OLED displays the measured distance and calculated steps.
+8. A `reached` flag is initialized to `True`.
+9. The program repeats once for every calculated step:
+   - Move the right motor one step.
+   - Move the left motor one step.
+   - Read the accelerometer's Y-axis value (`AcY`).
+   - If the tilt threshold is exceeded, set `reached` to `False` and stop driving.
+10. The robot reports the result:
+    - **REACHED:** Display the message and beep once.
+    - **TILTED:** Turn on the LED, display the warning, and beep three times with short pauses.
+11. The final message remains visible for 2–3 seconds before the loop resets.
+
+## Program flow
+
+```text
+Idle / LED off
+      |
+Display "Press button to start"
+      |
+Wait for button press
+      |
+Beep and measure distance
+      |
+Convert distance to motor steps
+      |
+Move both motors one step at a time
+      |
+Check AcY after every step
+      |
+  +---+------------------+
+  |                      |
+Tilt detected        All steps completed
+  |                      |
+Stop movement        Display "REACHED"
+LED on               Beep once
+Display "TILTED"
+Beep three times
+  |                      |
+  +----------+-----------+
+             |
+      Pause, then reset
+```
+
+## Core functions
+
+### `wait_button_press()`
+
+Waits until the physical button is pressed. The function deliberately blocks so the robot cannot begin moving before user confirmation.
+
+### `get_steps_from_distance(distance)`
+
+Converts the ultrasonic sensor's distance measurement into the number of steps required by the motors. Keeping this calculation in a separate function makes it easy to recalibrate the robot for different wheels, motors, or measurement units.
+
+## Tilt detection
+
+After every pair of motor movements, the program reads `AcY`. A reading outside the permitted range indicates that the robot has tilted and may no longer be driving safely.
+
+The intended check is equivalent to:
+
+```python
+if AcY > 12000 or AcY < -12000:
+    reached = False
+    break
+```
+
+This detects a magnitude greater than `12000` in either direction. A condition such as `AcY > 12000 or AcY > -12000` is not equivalent and would be true for most normal readings.
+
+The threshold is a test value and may require calibration for the specific accelerometer orientation and chassis.
+
+## Status indicators
+
+| State | OLED | LED | Buzzer |
+|---|---|---|---|
+| Waiting | `Press button to start` | Off | Silent |
+| Starting | Distance and step count | Off | One beep |
+| Target reached | `REACHED` | Off | One beep |
+| Excessive tilt | `TILTED` | On | Three beeps |
+
+## Notes
+
+- The program intentionally uses an infinite loop so the robot returns to its waiting state after each run.
+- The `reached` flag separates successful completion from an interrupted movement.
+- Modular helper functions make the control logic easier to test, reuse, and adapt in future projects.
+- Keep comments concise and consistent, especially around hardware initialization, calibration values, and safety checks.