piNail/wifi-onboarding-draft/README.md

WiFi Onboarding Draft

This folder contains a draft onboarding design for getting a piNail device onto WiFi and giving the user the correct webserver address with minimal friction.

Goals

• Zero SSH required for end users.
• Works on first boot with no preloaded WiFi credentials.
• Reliable recovery if router/SSID/password changes later.
• Stable web UI address after setup.

User Flow (Target UX)

1. User powers on device.
2. Device attempts connection using saved WiFi config.
3. If connection fails (or no config), device starts setup AP: piNail-Setup-XXXX.
4. User joins setup AP from phone/laptop.
5. Captive portal opens (or user browses to http://192.168.4.1).
6. User enters:
   • WiFi SSID
   • WiFi password
   • Optional hostname (default pinail)
   • Network mode: DHCP (recommended) or static IP
7. Device validates, saves config, reboots.
8. On success, user opens:
   • http://pinail.local:5000 (preferred)
   • fallback LAN IP shown on success page or label.

Recommended Network Strategy

• Default: DHCP + router DHCP reservation (best supportability).
• Expose both mDNS and IP to users:
  • pinail.local
  • 192.168.x.y

Files in this folder

• PI_IMPLEMENTATION.md: concrete Raspberry Pi setup design.
• RECOVERY_AND_RUNBOOK.md: failure handling and support steps.
• wifi_config.example.json: suggested stored config schema.