# 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.