Add Wi-Fi onboarding guide for ESP32-C3 setup and recovery

2026-03-13 22:44:43 +00:00
parent ef06b18bdd
commit ea996b332a
1 changed files with 48 additions and 0 deletions
@@ -0,0 +1,48 @@
+# Wi-Fi Onboarding Guide (ESP32-C3 Single-Nail)
+
+Use this guide to get a fresh controller onto your Wi-Fi network.
+
+## What you need
+- Powered ESP32-C3 controller (with flashed `pinail-esp32c3` firmware).
+- A phone or laptop with Wi-Fi.
+- Your 2.4 GHz Wi-Fi SSID/password.
+
+## First-time setup
+1. Power on the controller.
+2. Wait up to 20-30 seconds.
+3. On your phone/laptop, connect to:
+   - SSID: `piNail-Setup`
+   - Password: `pinailsetup`
+4. A captive portal should open automatically.
+   - If not, open `http://192.168.4.1` manually.
+5. Choose your home Wi-Fi SSID and enter password.
+6. Save/apply settings.
+7. Device reboots and joins your Wi-Fi.
+
+## Verify it connected
+After reboot, find the controller IP from your router DHCP list, then open:
+- `http://<device-ip>/api/status`
+- `http://<device-ip>/api/heartbeat`
+
+If JSON loads, onboarding is complete.
+
+## If onboarding portal does not appear
+- Ensure you are near the controller and it has stable power.
+- Disconnect mobile data temporarily (some phones avoid captive portal routing).
+- Connect directly to `piNail-Setup` and browse to `http://192.168.4.1`.
+- If SSID never appears, power cycle controller and retry.
+
+## If it won’t join Wi-Fi
+- Use a 2.4 GHz SSID (ESP32-C3 does not use 5 GHz-only SSIDs).
+- Re-enter password carefully.
+- Avoid WPA Enterprise/802.1X networks.
+
+## Recovery (wipe Wi-Fi credentials)
+If credentials are bad/stale, erase flash and reflash firmware:
+
+```bash
+esptool --chip esp32c3 -p /dev/ttyACM0 erase_flash
+pio run -t upload --upload-port /dev/ttyACM0
+```
+
+Then repeat onboarding from the top.