Update README and docs for settings page, PIN manager, and auto-config

- README: Added settings page, secure PIN/token, auto-config, startup scripts
- configuration-design.md: Documented PIN system, API token, auto-config, settings page
- Updated architecture diagram references
This commit is contained in:
Kareem Horstink
2026-07-03 08:33:44 +00:00
parent 331de4bc9e
commit 9fc6809f97
+60 -10
View File
@@ -68,15 +68,18 @@ flowchart TD
- **Hardware Telemetry** — CPU/GPU core temps, VRAM usage from HWiNFO64
- **Hardware Fallbacks** — Startup check reports which subsystems are available/unavailable
- **Custom Notifications** — External scripts can push progress bars or rich text alerts via `POST /api/v1/notify`
- **Settings Screen** — Change PIN and API token via the web client (protected by API token)
- **Settings Page** — Localhost-only web UI at `/settings` (accessed via tray icon) to edit PIN, token, host, port, log level, and PIN TTL
- **Secure PIN System** — 6-digit codes with 5-minute TTL, single-use, auto-generated on startup
- **Cryptographic API Token** — 256-bit entropy via `secrets.token_urlsafe(32)`
- **Auto-Configuration** — `config.yaml` created automatically on first run with detected local IP
- **Configuration Files** — Use `config.yaml`, `.env`, or environment variables
- **E-Ink Optimized UI** — High-contrast styling, discrete zone gestures, minimal refresh
- **System Tray .exe** — Runs unobtrusively in the Windows notification bar with a quit option
- **System Tray .exe** — Runs unobtrusively in the Windows notification bar with Settings and Quit options
## Authentication
1. **Dashboard UI (Boox Tablet):** Shared PIN authentication via WebSocket handshake (`?pin=XXXX`)
2. **External Scripts/CLI:** Static Bearer Token via `Authorization: Bearer <SECRET_TOKEN>` header
1. **Dashboard UI (Boox Tablet):** Time-limited PIN authentication via WebSocket handshake (`?pin=XXXX`). PINs are 6-digit, expire after 5 minutes (configurable), and can only be used once.
2. **External Scripts/CLI:** Cryptographic Bearer Token via `Authorization: Bearer <SECRET_TOKEN>` header (32 bytes / 256 bits of entropy)
## Project Structure
@@ -88,12 +91,17 @@ e-ink-dash/
├── server/ # Python FastAPI server
│ ├── main.py # Application entry point
│ ├── config.py # Configuration management (YAML/.env/env vars)
│ ├── pin_manager.py # Time-limited single-use PIN generation
│ ├── audio_mixer.py # Audio mixer abstraction (Windows + Voicemeeter)
│ ├── media.py # Media playback tracking (GSMTC)
│ ├── notifications.py # Notification system (progress + alerts)
│ ├── telemetry.py # Hardware telemetry (HWiNFO)
│ ├── tray_wrapper.py # System tray .exe wrapper
│ ├── settings.html # Settings page (localhost-only)
│ ├── settings.css # Settings page stylesheet
│ ├── build_exe.py # PyInstaller build script
│ ├── start.bat # Windows development startup
│ ├── start.sh # Linux/macOS development startup
│ ├── .env.example # Example environment file
│ ├── requirements.txt
│ └── tests/ # Test suite
@@ -108,7 +116,23 @@ e-ink-dash/
## Getting Started
### Server
### Quick Start (Development)
```bash
cd server
python start.bat # Windows
# or
bash start.sh # Linux/macOS
```
The scripts create a venv, install dependencies, and start the server. On first run, `config.yaml` is auto-generated with:
- A random 6-digit PIN (logged to console)
- A random API token (logged to console)
- Detected local IP address
- Default port 8921
### Manual Setup
```bash
cd server
@@ -121,24 +145,50 @@ python -m uvicorn main:app --host 0.0.0.0 --port 8921
Configure via one of:
1. **Environment variables:**
- `DASHBOARD_PIN`4-digit PIN for the E-Ink client
- `DASHBOARD_PIN`(optional, auto-generated if missing)
- `API_TOKEN` — Bearer token for external scripts
- `PIN_TTL` — PIN expiration in seconds (default: 300)
- `HOST` — Server bind address (default: detected local IP)
- `PORT` — Server port (default: 8921)
- `LOG_LEVEL` — Logging level (default: INFO)
2. **`.env` file** (in project root or exe directory):
```
DASHBOARD_PIN=1234
API_TOKEN=your-token-here
PIN_TTL=300
HOST=192.168.1.100
PORT=8921
LOG_LEVEL=INFO
```
3. **`config.yaml`** (in project root or exe directory):
3. **`config.yaml`** (auto-created on first run, or manually):
```yaml
dashboard_pin: "1234"
api_token: "your-token-here"
pin_ttl: 300
host: "192.168.1.100"
port: 8921
log_level: "INFO"
```
See `.env.example` and `config.yaml.example` for reference.
### Settings Page
Access the settings UI via the system tray icon → **Settings**. This opens `http://127.0.0.1:8921/settings` in your browser.
**Available only from localhost** — you must be on the PC running PaperDash.
Edit: PIN, API token, host, port, log level, and PIN TTL. Changes are saved to `config.yaml` and take effect on next restart.
### Build .exe
```bash
cd server
python build_exe.py
# Output: server/dist/PaperDash.exe
```
The `.exe` bundles `settings.html` and `settings.css` for the settings page.
### Build .exe