pinail-esp32c3/WIFI_ONBOARDING.md

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:

esptool --chip esp32c3 -p /dev/ttyACM0 erase_flash
pio run -t upload --upload-port /dev/ttyACM0

Then repeat onboarding from the top.