Kiwy-Signage/documentation/dev-notes/QUICK_START.md

🚀 Quick Start Guide - Player Authentication

For DigiServer Admin

1. Create Player in DigiServer v2

# 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

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

2. Test Authentication

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

3. Update Player Code (One-Time)

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

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

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

# 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

# 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!