Kiwy-Signage/MIGRATION_GUIDE.md

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:

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:

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

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:

{
  "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:

pkill -f main.py

2. Delete old authentication data (first time only):

rm -f /home/pi/Desktop/Kiwy-Signage/src/player_auth.json

3. Start the updated player:

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:

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

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

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

2. Check network connectivity:

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:

{
  "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:

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:

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:

# 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. 🎉