49 lines
1.6 KiB
Markdown
49 lines
1.6 KiB
Markdown
# 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.
|