Richard
b3deb0036f
ESP32-C3 Zero + VL53L1X ToF sensor + 3x LEDs with WiFi AP web calibration UI, rolling average smoothing, auto-sleep, and NVS persistence. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
59 lines
2.9 KiB
Markdown
59 lines
2.9 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
Car parking distance sensor using an ESP32-C3 Zero, VL53L1X Time-of-Flight laser sensor, and 3x 10mm LEDs (green/yellow/red). Wall-mounted in a garage, it measures distance to an approaching car and displays proximity via LED states. Includes a WiFi AP with web UI for remote calibration.
|
||
|
||
## Build & Flash Commands
|
||
|
||
- `pio run` — compile firmware
|
||
- `pio run -t upload` — flash to ESP32-C3 (port: `/dev/ttyACM0`)
|
||
- `pio device monitor` — serial monitor (115200 baud)
|
||
- `pio run -t upload && pio device monitor` — flash and monitor in one shot
|
||
|
||
Note: close the serial monitor before flashing, or the port will be busy.
|
||
|
||
## Architecture
|
||
|
||
Single-file firmware (`src/main.cpp`) using Arduino framework on PlatformIO. Three subsystems:
|
||
|
||
1. **Sensor** — VL53L1X on I2C (GPIO 5 SDA, GPIO 6 SCL), continuous mode at 50ms intervals
|
||
2. **LEDs** — 3x 10mm through-hole on GPIO 2 (green), GPIO 3 (yellow), GPIO 4 (red), active HIGH with 220Ω resistors
|
||
3. **WiFi/Web** — ESP32 runs as AP (SSID: `ParkingSensor`, pass: `carpark1`). Web server on `192.168.4.1` provides:
|
||
- Live distance readout (polls `/api/status` at 300ms)
|
||
- One-tap calibration (`POST /api/calibrate`) — sets current distance as the stop point
|
||
- Manual stop distance input (`POST /api/set?stop=N`)
|
||
|
||
## LED Behaviour
|
||
|
||
LEDs off when distance > stop + 1000mm (ZONE_GREEN + 200mm headroom). Within range, zones are calculated as offsets above the calibrated stop distance:
|
||
|
||
| Zone | Distance | LEDs |
|
||
|------|----------|------|
|
||
| Far | > stop + 800mm | Green |
|
||
| Approaching | stop + 400 – stop + 800mm | Green + Yellow |
|
||
| Close | stop + 100 – stop + 400mm | Yellow + Red |
|
||
| Very close | stop – stop + 100mm | Red solid |
|
||
| STOP | < stop | Red flashing |
|
||
|
||
## Signal Processing
|
||
|
||
- **Rolling average**: 5-sample moving average of valid readings smooths jitter
|
||
- **Bad reading filter**: readings with `range_status != 0` are discarded (status 7 = wrap-around is common at range edges)
|
||
- **Zero filter**: distance 0 (no target) is discarded
|
||
- **Auto-sleep**: LEDs turn off after 30s of stable distance (30mm tolerance), wake on movement
|
||
|
||
## Calibration & Persistence
|
||
|
||
The stop distance is stored in NVS (ESP32 flash) via the `Preferences` library. It survives power cycles. Zone offsets are `#define` constants (`ZONE_RED` 100, `ZONE_YELLOW` 400, `ZONE_GREEN` 800) at the top of `src/main.cpp`. Stable tolerance (`STABLE_TOLERANCE` 30mm) and sleep timeout (`SLEEP_TIMEOUT` 30000ms) are also tuneable.
|
||
|
||
## Hardware
|
||
|
||
- **Board**: ESP32-C3 Zero (board target: `esp32-c3-devkitm-1`)
|
||
- **Sensor**: VL53L1X ToF (I2C, Pololu library `pololu/VL53L1X@^1.3.1`)
|
||
- **LEDs**: 10mm through-hole (green, yellow, red) with 220Ω resistors
|
||
- **Power**: USB-C
|
||
- **Build flags**: `-DARDUINO_USB_MODE=1 -DARDUINO_USB_CDC_ON_BOOT=1` (required for serial over USB on C3 Zero)
|