Restore safety cutoff to 800F, faster PID loop timing, enhanced simple UI with stats/charts/flight controls, compact TTY display

2026-03-13 00:36:10 +00:00
parent 2853fa3f8a
commit 24c57beda8
11 changed files with 486 additions and 133 deletions
@@ -0,0 +1,66 @@
+# Raspberry Pi Implementation Draft
+
+This is a concrete implementation plan for Pi-based piNail onboarding.
+
+## Components
+- `Flask` app (already present in `piNail2`) for setup endpoints/pages.
+- `hostapd` for AP mode.
+- `dnsmasq` for DHCP + captive DNS in setup mode.
+- `avahi-daemon` for `pinail.local` mDNS in normal mode.
+
+## Modes
+- `normal`:
+  - Connect to configured WiFi.
+  - Run control server at `0.0.0.0:5000`.
+- `setup`:
+  - Start AP on wlan0 (`192.168.4.1/24`).
+  - Start captive portal UI.
+
+## Suggested State Rules
+- Enter setup mode when:
+  - no wifi config exists, or
+  - join fails N times over T seconds, or
+  - user holds setup/reset button at boot.
+- Exit setup mode when:
+  - credentials validate and connection succeeds.
+
+## Boot Sequence
+1. Start `pinail-network-bootstrap.service` (Before `pinail2.service`).
+2. Bootstrap checks `/home/pi/piNail2/wifi_config.json`.
+3. If valid and connectable, ensure normal mode and continue boot.
+4. If not, bring up setup mode and start setup UI.
+
+## Setup AP Parameters (draft)
+- SSID: `piNail-Setup-<last4mac>`
+- Security: WPA2 PSK (device label) or open AP (if easier UX).
+- AP IP: `192.168.4.1`
+- DHCP range: `192.168.4.20-192.168.4.120`
+
+## Captive Portal Endpoints (draft)
+- `GET /setup`: setup form page
+- `POST /setup`: submit WiFi/network settings
+- `GET /setup/status`: async connection progress
+- `POST /setup/reset`: clear saved creds and return to setup mode
+
+## Config Write Path
+1. Validate form values server-side.
+2. Write to temp file then atomic rename:
+   - `/home/pi/piNail2/wifi_config.json.tmp`
+   - `/home/pi/piNail2/wifi_config.json`
+3. Apply network config.
+4. Show success page with hostname and assigned IP.
+5. Reboot or restart networking services.
+
+## Normal Mode Addressing
+- Primary URL: `http://pinail.local:5000`
+- Secondary URL: `http://<dhcp-ip>:5000`
+- Optional static mode if user enters:
+  - IP
+  - subnet
+  - gateway
+  - DNS
+
+## Security Notes
+- Do not log WiFi password.
+- Restrict setup endpoints to setup mode only.
+- Optionally disable setup AP once normal mode succeeds.
@@ -0,0 +1,36 @@
+# 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.
@@ -0,0 +1,36 @@
+# Recovery and Support Runbook
+
+Use this when users report they cannot reach the web UI.
+
+## User-Facing Recovery
+1. Power cycle device.
+2. Try `http://pinail.local:5000`.
+3. If unavailable, check router client list for `pinail` host and use IP.
+4. If still unavailable, hold setup/reset button (5-10s) to force setup AP.
+5. Rejoin `piNail-Setup-XXXX` and re-enter WiFi credentials.
+
+## Technician Quick Checks (SSH)
+- Service status:
+  - `sudo systemctl status pinail2`
+- Logs:
+  - `sudo journalctl -u pinail2 -n 150 --no-pager`
+- WLAN status:
+  - `ip addr show wlan0`
+  - `iwgetid`
+- Reachability:
+  - `ping -c 3 192.168.0.1`
+
+## Common Failure Cases
+- Wrong SSID/password:
+  - force setup mode, re-enter credentials.
+- Router changed subnet:
+  - use mDNS or router client list to discover new IP.
+- Stale browser cache:
+  - hard refresh (`Ctrl+Shift+R` / `Cmd+Shift+R`).
+- Service stuck after network transitions:
+  - `sudo systemctl restart pinail2`.
+
+## Recommended Production Defaults
+- DHCP + router reservation.
+- mDNS hostname advertised (`pinail.local`).
+- Physical setup/reset button available without opening enclosure.
@@ -0,0 +1,20 @@
+{
+  "mode": "dhcp",
+  "hostname": "pinail",
+  "wifi": {
+    "ssid": "YourSSID",
+    "password": "YourPassword"
+  },
+  "static": {
+    "ip": "192.168.0.159",
+    "prefix": 24,
+    "gateway": "192.168.0.1",
+    "dns": [
+      "192.168.0.153",
+      "8.8.8.8"
+    ]
+  },
+  "web": {
+    "port": 5000
+  }
+}