100 lines
2.5 KiB
Markdown
100 lines
2.5 KiB
Markdown
# Debugging Guide
|
|
|
|
## Purpose
|
|
Fast diagnosis guide: "If X happens, check Y" with separate paths for Simulation and Real Box.
|
|
|
|
## Prerequisites
|
|
- Box running (simulation or device)
|
|
- Access to `/status` and data files
|
|
|
|
## Step-by-step
|
|
Use the sections below by symptom.
|
|
|
|
## Simulation (IDE)
|
|
### If GUI shows "Failed to fetch"
|
|
- Check API is running:
|
|
```
|
|
curl http://127.0.0.1:8000/status
|
|
```
|
|
- Verify GUI API base:
|
|
- `VITE_BOX_API_URL` or default `http://localhost:8000`
|
|
|
|
### If playback does not start
|
|
- Check tags:
|
|
```
|
|
cat box/data/box.json
|
|
```
|
|
- Check media files:
|
|
```
|
|
ls -la box/data/media
|
|
```
|
|
- Check `/status`:
|
|
```
|
|
curl http://127.0.0.1:8000/status
|
|
```
|
|
|
|
### If resume does not persist
|
|
- Check state file:
|
|
```
|
|
cat box/data/state.json
|
|
```
|
|
- Ensure playback was stopped via `nfc_off` or end-of-media.
|
|
|
|
### If setup UI not reachable
|
|
- Check port 9000 free.
|
|
- Ensure Box is running.
|
|
|
|
### If box not recognized by server
|
|
- Not testable with current code: no announce/pairing implemented.
|
|
|
|
### If box appears multiple times
|
|
- Not testable with current code: no announce/pairing implemented.
|
|
|
|
### If fingerprint changes
|
|
- Not testable with current code: fingerprint not implemented.
|
|
|
|
### If pairing hangs
|
|
- Not testable with current code: pairing flow not implemented.
|
|
|
|
## Real Box (Hardware)
|
|
### If device not reachable in browser
|
|
- Ensure it is powered on and connected to the same network.
|
|
- Check the IP shown by your router.
|
|
|
|
### If NFC does nothing
|
|
- Confirm tag UID exists in `box.json`.
|
|
- Confirm NFC hardware is working (not implemented in code).
|
|
|
|
### If audio is silent
|
|
- Audio backend is mock in current code.
|
|
- Not testable with current code.
|
|
|
|
### If box not recognized by server
|
|
- Not testable with current code: no announce/pairing implemented.
|
|
|
|
### If box appears multiple times
|
|
- Not testable with current code: no announce/pairing implemented.
|
|
|
|
### If fingerprint changes
|
|
- Not testable with current code: fingerprint not implemented.
|
|
|
|
### If pairing hangs
|
|
- Not testable with current code: pairing flow not implemented.
|
|
|
|
## Files to inspect
|
|
- `box/data/box.json`: identity, tags, settings
|
|
- `box/data/state.json`: resume and wifi state
|
|
- `box/data/secrets.enc`: encrypted secrets
|
|
|
|
## Status fields to watch
|
|
- `wifi_state`, `ip_address`, `connected_ssid`
|
|
- `playback_state.state`, `playback_state.active_uid`
|
|
- `playback_state.position`, `playback_state.file_index`
|
|
- `playback_state.last_error`
|
|
|
|
## Troubleshooting
|
|
- 400 from `/command`:
|
|
- Check required payload fields in `docs/api.md`.
|
|
- No change after command:
|
|
- Poll `/status` after sending.
|