From ea996b332acc8ce28bf21639d3eee5043abdb843 Mon Sep 17 00:00:00 2001 From: Seth Freiberg Date: Fri, 13 Mar 2026 22:44:43 +0000 Subject: [PATCH] Add Wi-Fi onboarding guide for ESP32-C3 setup and recovery --- WIFI_ONBOARDING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 WIFI_ONBOARDING.md diff --git a/WIFI_ONBOARDING.md b/WIFI_ONBOARDING.md new file mode 100644 index 0000000..60779eb --- /dev/null +++ b/WIFI_ONBOARDING.md @@ -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:///api/status` +- `http:///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.