277 lines
6.5 KiB
Markdown
277 lines
6.5 KiB
Markdown
# Kiwy-Signage Player Migration Guide
|
|
## Updating to DigiServer v2 Authentication
|
|
|
|
This guide explains how to update your Kiwy-Signage player to use the new secure authentication system with DigiServer v2.
|
|
|
|
## What Changed?
|
|
|
|
### Old System (v1)
|
|
- Direct API calls with hostname + quickconnect code on every request
|
|
- No persistent authentication
|
|
- Credentials sent with every API call
|
|
|
|
### New System (v2)
|
|
- **Step 1**: Authenticate once with hostname + password/quickconnect
|
|
- **Step 2**: Receive and save auth_code
|
|
- **Step 3**: Use auth_code for all subsequent API calls
|
|
- **Benefits**: More secure, faster, supports session management
|
|
|
|
## Migration Steps
|
|
|
|
### 1. Copy New Files
|
|
|
|
Copy the authentication modules to your Kiwy-Signage project:
|
|
|
|
```bash
|
|
cd /home/pi/Desktop/Kiwy-Signage/src/
|
|
|
|
# New files are already created:
|
|
# - player_auth.py (authentication module)
|
|
# - get_playlists_v2.py (updated playlist fetcher)
|
|
```
|
|
|
|
### 2. Update main.py Imports
|
|
|
|
In `main.py`, replace the old import:
|
|
|
|
```python
|
|
# OLD:
|
|
from get_playlists import (
|
|
update_playlist_if_needed,
|
|
send_playing_status_feedback,
|
|
send_playlist_restart_feedback,
|
|
send_player_error_feedback
|
|
)
|
|
|
|
# NEW:
|
|
from get_playlists_v2 import (
|
|
update_playlist_if_needed,
|
|
send_playing_status_feedback,
|
|
send_playlist_restart_feedback,
|
|
send_player_error_feedback
|
|
)
|
|
```
|
|
|
|
### 3. Add Authentication on Startup
|
|
|
|
In `main.py`, add authentication check in the `SignagePlayer` class:
|
|
|
|
```python
|
|
def build(self):
|
|
"""Build the application UI"""
|
|
# Load configuration
|
|
self.config = self.load_config()
|
|
|
|
# NEW: Authenticate with server
|
|
from player_auth import PlayerAuth
|
|
auth = PlayerAuth()
|
|
|
|
if not auth.is_authenticated():
|
|
Logger.info("First time setup - authenticating...")
|
|
from get_playlists_v2 import ensure_authenticated
|
|
if not ensure_authenticated(self.config):
|
|
Logger.error("❌ Failed to authenticate with server!")
|
|
# Show error popup or retry
|
|
else:
|
|
Logger.info(f"✅ Authenticated as: {auth.get_player_name()}")
|
|
|
|
# Continue with normal startup...
|
|
return SignagePlayerWidget(config=self.config)
|
|
```
|
|
|
|
### 4. Update Server Configuration
|
|
|
|
Your existing `app_config.txt` works as-is! The new system uses the same fields:
|
|
|
|
```json
|
|
{
|
|
"server_ip": "your-server-ip",
|
|
"port": "5000",
|
|
"screen_name": "player-001",
|
|
"quickconnect_key": "QUICK123",
|
|
...
|
|
}
|
|
```
|
|
|
|
**Note**: `screen_name` is now used as `hostname` for authentication.
|
|
|
|
### 5. Testing
|
|
|
|
1. **Stop the old player**:
|
|
```bash
|
|
pkill -f main.py
|
|
```
|
|
|
|
2. **Delete old authentication data** (first time only):
|
|
```bash
|
|
rm -f /home/pi/Desktop/Kiwy-Signage/src/player_auth.json
|
|
```
|
|
|
|
3. **Start the updated player**:
|
|
```bash
|
|
cd /home/pi/Desktop/Kiwy-Signage/src/
|
|
python3 main.py
|
|
```
|
|
|
|
4. **Check logs for authentication**:
|
|
- Look for: `✅ Authentication successful`
|
|
- Or: `❌ Authentication failed: [error message]`
|
|
|
|
## Troubleshooting
|
|
|
|
### Authentication Fails
|
|
|
|
**Problem**: `❌ Authentication failed: Invalid credentials`
|
|
|
|
**Solution**:
|
|
1. Verify player exists in DigiServer v2:
|
|
- Login to http://your-server:5000
|
|
- Go to Players → check if hostname exists
|
|
|
|
2. Verify quickconnect code:
|
|
- In DigiServer, check player's Quick Connect Code
|
|
- Update `app_config.txt` with correct code
|
|
|
|
3. Check server URL:
|
|
```python
|
|
# Test connection
|
|
import requests
|
|
response = requests.get('http://your-server:5000/api/health')
|
|
print(response.json()) # Should show: {'status': 'healthy'}
|
|
```
|
|
|
|
### Auth Code Expired
|
|
|
|
**Problem**: Player was working, now shows auth errors
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Clear saved auth and re-authenticate
|
|
rm /home/pi/Desktop/Kiwy-Signage/src/player_auth.json
|
|
# Restart player - will auto-authenticate
|
|
```
|
|
|
|
### Can't Connect to Server
|
|
|
|
**Problem**: `Cannot connect to server`
|
|
|
|
**Solution**:
|
|
1. Check server is running:
|
|
```bash
|
|
curl http://your-server:5000/api/health
|
|
```
|
|
|
|
2. Check network connectivity:
|
|
```bash
|
|
ping your-server-ip
|
|
```
|
|
|
|
3. Verify server URL in `app_config.txt`
|
|
|
|
## Configuration Files
|
|
|
|
### player_auth.json (auto-created)
|
|
|
|
This file stores the authentication token:
|
|
|
|
```json
|
|
{
|
|
"hostname": "player-001",
|
|
"auth_code": "rrX4JtM99e4e6ni0VCsuIstjTVQQqILXeRmGu_Ek2Ks",
|
|
"player_id": 1,
|
|
"player_name": "Demo Player",
|
|
"group_id": 5,
|
|
"orientation": "Landscape",
|
|
"authenticated": true,
|
|
"server_url": "http://your-server:5000"
|
|
}
|
|
```
|
|
|
|
**Important**: Keep this file secure! It contains your player's access token.
|
|
|
|
## Advanced: Custom Authentication
|
|
|
|
If you need custom authentication logic:
|
|
|
|
```python
|
|
from player_auth import PlayerAuth
|
|
|
|
# Initialize
|
|
auth = PlayerAuth(config_file='custom_auth.json')
|
|
|
|
# Authenticate with password instead of quickconnect
|
|
success, error = auth.authenticate(
|
|
server_url='http://your-server:5000',
|
|
hostname='player-001',
|
|
password='your_secure_password' # Use password instead
|
|
)
|
|
|
|
if success:
|
|
print(f"✅ Authenticated as: {auth.get_player_name()}")
|
|
|
|
# Get playlist
|
|
playlist_data = auth.get_playlist()
|
|
|
|
# Send heartbeat
|
|
auth.send_heartbeat(status='playing')
|
|
|
|
# Send feedback
|
|
auth.send_feedback(
|
|
message="Playing video.mp4",
|
|
status="playing",
|
|
playlist_version=5
|
|
)
|
|
else:
|
|
print(f"❌ Failed: {error}")
|
|
```
|
|
|
|
## Rollback to Old System
|
|
|
|
If you need to rollback:
|
|
|
|
```bash
|
|
cd /home/pi/Desktop/Kiwy-Signage/src/
|
|
|
|
# Rename new files
|
|
mv get_playlists_v2.py get_playlists_v2.py.backup
|
|
mv player_auth.py player_auth.py.backup
|
|
|
|
# Use old get_playlists.py (keep as-is)
|
|
# Old system will continue working with DigiServer v1
|
|
```
|
|
|
|
## Benefits of New System
|
|
|
|
✅ **More Secure**: Auth tokens instead of passwords in every request
|
|
✅ **Better Performance**: No bcrypt verification on every API call
|
|
✅ **Session Management**: Server tracks player sessions
|
|
✅ **Easier Debugging**: Auth failures vs API failures are separate
|
|
✅ **Future-Proof**: Ready for token refresh, expiration, etc.
|
|
|
|
## Next Steps
|
|
|
|
Once migration is complete:
|
|
|
|
1. **Monitor player logs** for first 24 hours
|
|
2. **Verify playlist updates** are working
|
|
3. **Check feedback** is being received in DigiServer
|
|
4. **Update other players** one at a time
|
|
|
|
## Support
|
|
|
|
If you encounter issues:
|
|
|
|
1. **Check player logs**: `tail -f player.log`
|
|
2. **Check server logs**: DigiServer v2 logs in `instance/logs/`
|
|
3. **Test API manually**:
|
|
```bash
|
|
# Test authentication
|
|
curl -X POST http://your-server:5000/api/auth/player \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"hostname":"player-001","quickconnect_code":"QUICK123"}'
|
|
```
|
|
|
|
---
|
|
|
|
**Migration completed!** Your Kiwy-Signage player now uses secure authentication with DigiServer v2. 🎉
|