43 lines
1.3 KiB
Markdown
43 lines
1.3 KiB
Markdown
# Box Lifecycle
|
|
|
|
## Purpose
|
|
Defines the virtual box lifecycle: identity, WiFi states, and restart behavior.
|
|
|
|
## Prerequisites
|
|
- Box started with `python3 box/main.py run`
|
|
|
|
## Step-by-step
|
|
### Box identity
|
|
- Generated on first start if `box/data/box.json` has no `box_id`.
|
|
- Format: `klangkiste-<10 chars a-z0-9>`
|
|
- Stored in `box/data/box.json`
|
|
|
|
### WiFi states (logical)
|
|
- `WIFI_UNCONFIGURED`: no profiles stored
|
|
- `WIFI_CONNECTING`: reserved for future; not emitted in mock
|
|
- `WIFI_ONLINE`: profile exists and mock is "connected"
|
|
- `WIFI_OFFLINE`: profile exists but not connected
|
|
|
|
### IP model (informational)
|
|
- Setup/AP mode: `192.168.4.1`
|
|
- Normal mode: `127.0.0.1`
|
|
|
|
### Restart behavior
|
|
- Box reloads `box_id`, resume state, and WiFi profiles from `box/data/`
|
|
- Playback resume and WiFi status are preserved
|
|
|
|
### Resets
|
|
- WiFi reset: clears WiFi profiles only (`wifi_reset` command)
|
|
- Factory reset: delete `box/data/box.json`, `box/data/state.json`, `box/data/secrets.enc`
|
|
|
|
## Checklist
|
|
- ✅ After first boot, `box/data/box.json` contains `box_id`
|
|
- ✅ `GET /status` returns `wifi_state` and `ip_address`
|
|
- ✅ WiFi reset clears profiles, `wifi_state=WIFI_UNCONFIGURED`
|
|
|
|
## Troubleshooting
|
|
- `wifi_state` not changing:
|
|
- Add a WiFi profile via setup UI or API.
|
|
- Missing `box_id`:
|
|
- Ensure `box/data/box.json` is writable.
|