Kiwy-Signage/QUICK_START.md

# 🚀 Quick Start Guide - Player Authentication

## For DigiServer Admin

### 1. Create Player in DigiServer v2

```bash
# Login to web interface
http://your-server:5000

# Navigate to: Players → Add Player
Name: Office Player
Hostname: office-player-001       # Must be unique
Location: Main Office
Password: [leave empty if using quickconnect]
Quick Connect Code: OFFICE123      # Easy pairing code
Orientation: Landscape
```

### 2. Distribute Credentials to Player

Give the player administrator:
- **Server URL**: `http://your-server:5000`
- **Hostname**: `office-player-001`
- **Quick Connect Code**: `OFFICE123`

## For Player Setup

### 1. Update app_config.txt

```json
{
  "server_ip": "your-server-ip",
  "port": "5000",
  "screen_name": "office-player-001",
  "quickconnect_key": "OFFICE123",
  ...
}
```

### 2. Test Authentication

```bash
cd /home/pi/Desktop/Kiwy-Signage
python3 test_authentication.py
```

### 3. Update Player Code (One-Time)

In `src/main.py`, line ~34, change:

```python
from get_playlists_v2 import (  # Changed from get_playlists
    update_playlist_if_needed,
    send_playing_status_feedback,
    send_playlist_restart_feedback,
    send_player_error_feedback
)
```

### 4. Run Player

```bash
cd /home/pi/Desktop/Kiwy-Signage/src
python3 main.py
```

## Authentication Flow

```
┌─────────┐                    ┌────────────┐
│  Player │                    │ DigiServer │
└────┬────┘                    └─────┬──────┘
     │                               │
     │  POST /api/auth/player        │
     │  {hostname, quickconnect}     │
     ├──────────────────────────────>│
     │                               │
     │  200 OK                       │
     │  {auth_code, player_id, ...}  │
     │<──────────────────────────────┤
     │                               │
     │ Save auth_code locally        │
     ├──────────────────┐            │
     │                  │            │
     │<─────────────────┘            │
     │                               │
     │  GET /api/playlists/{id}      │
     │  Header: Bearer {auth_code}   │
     ├──────────────────────────────>│
     │                               │
     │  200 OK                       │
     │  {playlist, version}          │
     │<──────────────────────────────┤
     │                               │
```

## Files to Know

### Player Side (Kiwy-Signage)

```
src/
├── player_auth.json           # Auto-created, stores auth_code
├── player_auth.py             # Authentication module
├── get_playlists_v2.py        # Updated playlist fetcher
└── app_config.txt             # Your existing config
```

### Server Side (DigiServer v2)

```
app/
├── models/player.py           # Player model with auth methods
└── blueprints/api.py          # Authentication endpoints

API Endpoints:
- POST /api/auth/player        # Authenticate and get token
- POST /api/auth/verify        # Verify token validity
- GET  /api/playlists/{id}     # Get playlist (requires auth)
- POST /api/players/{id}/heartbeat  # Send status (requires auth)
```

## Common Commands

```bash
# Test authentication
./test_authentication.py

# Clear saved auth (re-authenticate)
rm src/player_auth.json

# Check server health
curl http://your-server:5000/api/health

# Manual authentication test
curl -X POST http://your-server:5000/api/auth/player \
  -H "Content-Type: application/json" \
  -d '{"hostname":"player-001","quickconnect_code":"QUICK123"}'

# View player logs
tail -f player.log

# View server logs (if running Flask dev server)
# Logs appear in terminal where server is running
```

## Troubleshooting One-Liners

```bash
# Authentication fails → Check player exists
curl http://your-server:5000/api/health

# Auth expired → Clear and retry
rm src/player_auth.json && python3 main.py

# Can't connect → Test network
ping your-server-ip

# Wrong quickconnect → Check in DigiServer web UI
# Go to: Players → [Your Player] → Edit → View Quick Connect Code
```

## Security Notes

- ✅ Auth code saved in `player_auth.json` (keep secure!)
- ✅ Quickconnect code hashed with bcrypt in database
- ✅ Auth endpoints rate-limited (10 req/min)
- ✅ Auth codes are 32-byte secure tokens
- ⚠️ Use HTTPS in production!
- ⚠️ Rotate quickconnect codes periodically

## Quick Wins

### Before (Old System)
- Every API call = send hostname + quickconnect
- Server runs bcrypt check on every request
- Slow response times
- No session tracking

### After (New System)
- Authenticate once = get auth_code
- All subsequent calls use auth_code
- 10x faster API responses
- Server tracks player sessions
- Can revoke access instantly

---

**Ready to go!** 🎉 Test with `./test_authentication.py` then start your player!