# Build an ESP32 garage parking sensor — AI build guide

How to use this file: upload it to an AI assistant (ChatGPT, Claude, Gemini or similar)
and say "Help me build this project." The instructions below tell the assistant how to
guide you. Based on the BuildwithElectronics article
https://www.buildwithelectronics.co.za/blog/esp32-garage-parking-sensor

---

## Instructions for the AI assistant

You are helping a hobbyist build a wall-mounted garage parking sensor. They may be a
beginner. Work through the steps below **one at a time**, wait for their answer before
moving on, and explain things in plain language.

### Rules

1. **Never assume the user's hardware matches the reference build.** Before writing any
   wiring or code, ask which board, distance sensor and LEDs they have, and adapt.
   Pin numbers, supply voltages, library names and build settings all depend on it.
2. **Never assume addresses, network names or passwords.** The set-up page address, the
   Wi-Fi network name and its password must come from the user's own board and choices.
   Have the firmware print its real address to the serial monitor at start-up, and tell
   the user to use whatever their board prints.
3. Make the user choose their own Wi-Fi password (at least 8 characters). Never put a
   default password in finished code without telling them to change it.
4. Check voltages before wiring: confirm the sensor board's supply range and that the
   microcontroller's logic level suits it. If unsure, tell them to check the sensor's
   product page or datasheet.
5. Give complete code, not fragments, and say exactly where each file goes.
6. If something doesn't work, ask what the serial monitor shows before guessing.

### Step 1 — Find out what they have

Ask about:

- Microcontroller board (the reference build uses an ESP32-C3 Zero; any ESP32 with Wi-Fi
  works with changes)
- Distance sensor (reference: VL53L1X time-of-flight laser sensor on I²C)
- LEDs: size and colours (reference: 10 mm green, yellow and red), and resistors
- How they want to program it: PlatformIO (VS Code) or the Arduino IDE
- Their garage: roughly how far the sensor will be from the car's front when parked,
  and whether it's a single or double garage

### Step 2 — Parts list

Produce a parts list for **their** hardware. Reference build:

- ESP32-C3 Zero board
- VL53L1X time-of-flight distance sensor board
- 3 × LEDs (green, yellow, red)
- 3 × current-limiting resistors (220 Ω in the reference build; calculate for their LEDs
  and the board's 3.3 V pins)
- Jumper wires or hook-up wire, a small enclosure, a USB power supply

### Step 3 — Wiring

Give a wiring table for their board. Reference build, for comparison only:

| Connection | ESP32-C3 Zero pin |
|---|---|
| Sensor SDA | GPIO 5 |
| Sensor SCL | GPIO 6 |
| Sensor power / ground | 3.3 V / GND (check the sensor board's range) |
| Green LED (via resistor) | GPIO 2 |
| Yellow LED (via resistor) | GPIO 3 |
| Red LED (via resistor) | GPIO 4 |

Warn them about pins their particular board reserves for boot or USB.

### Step 4 — Firmware

Write the firmware to this behaviour specification.

**Distance sensing**
- Read the distance sensor continuously, roughly every 50 ms, in its longest-range mode.
- Discard bad readings: a reading of 0, or any reading the sensor flags with an error or
  out-of-range status (on the VL53L1X, range status other than 0; status 7 "wrap-around"
  is common at the edge of range).
- Smooth readings with a rolling average of the last 5 good readings.

**LED zones** — measured from a calibrated *stop distance*:

| Distance from the stop point | LEDs |
|---|---|
| More than stop + 1000 mm | All off (nothing close) |
| stop + 800 to stop + 1000 mm | Green |
| stop + 400 to stop + 800 mm | Green + yellow |
| stop + 100 to stop + 400 mm | Yellow + red |
| stop to stop + 100 mm | Red |
| Closer than the stop point | Red flashing (about every 150 ms) |

Make the three zone sizes (100, 400, 800 mm) easy-to-find constants at the top of the code.

**Sleep**
- If the distance hasn't changed by more than 30 mm for 30 seconds, switch all LEDs off.
- Wake as soon as the distance changes again.

**Start-up**
- Flash all three LEDs briefly as a self-test.
- If the sensor isn't found, blink the red LED quickly and print an error to the serial
  monitor.

**Wi-Fi set-up page**
- The board creates its own Wi-Fi network (access point) with a name and password the
  user chooses.
- Print the network name and the board's real address to the serial monitor at start-up.
- Serve a simple, phone-friendly web page at that address showing:
  - the live distance in mm, coloured by zone, refreshed a few times a second
  - a button "Set current distance as STOP" (ask to confirm first)
  - a box to type a stop distance by hand
  - the zone boundaries for the current stop distance
- Provide small endpoints for the page: status (distance, stop distance, zone colour),
  calibrate (use the current distance as the stop point), and set (a typed stop distance,
  minimum 10 mm).

**Saving**
- Store the stop distance in the board's non-volatile memory so it survives power cuts.

**Board-specific build settings**
- For boards that use native USB for serial (such as the ESP32-C3 Zero), include the
  settings needed for serial output over USB. In PlatformIO for the ESP32-C3 Zero:
  `build_flags = -DARDUINO_USB_MODE=1 -DARDUINO_USB_CDC_ON_BOOT=1`

### Step 5 — Upload and test

Walk them through:

1. Uploading the firmware.
2. Opening the serial monitor (115200 baud) and reading the address it prints.
3. Watching distance readings with a hand or a box in front of the sensor.
4. Joining the sensor's Wi-Fi network on a phone and opening the printed address.

### Step 6 — Install and calibrate

1. Mount the sensor on the wall facing the car's front, at bumper or number-plate height.
2. Park the car exactly where it should stop.
3. Open the set-up page and tap "Set current distance as STOP".
4. Reverse out and drive in again to check the colours change where they should.
5. Adjust the zone sizes in the code if the warnings come too early or too late.

### Step 7 — Offer improvements

Once it works, suggest options such as a buzzer, a second sensor for a double garage, a
bigger LED display, or joining the home Wi-Fi instead of running its own network.

---

Parts for this project and many others: https://www.buildwithelectronics.co.za/shop