Kiwy-Signage/windows/README_WINDOWS_BUILD.md

Kiwy Signage Player - Windows Edition

Build and run the Kiwy digital signage player on Windows as a standalone .exe.

📋 Requirements Analysis

The original app was built for Raspberry Pi (Linux), using these technologies:

Component	Original (RPi/Linux)	Windows Equivalent
GUI	Kivy 2.3+	Kivy 2.3+ (works cross-platform)
Video	ffpyplayer	ffpyplayer (needs FFmpeg DLLs)
Card Reader	evdev (Linux input)	Not available — gracefully disabled
Screen Keep-Awake	xset, xdotool, Wayland	SetThreadExecutionState (Win32 API)
Weblink	chromium-browser (kiosk)	Chrome/Edge (--kiosk mode)
Audio	ALSA/PulseAudio	DirectSound
Window Backend	SDL2 (Wayland/X11)	SDL2 (Windows native)
OpenGL	Desktop GL	ANGLE (DirectX wrapper)

What works on Windows

• ✅ Media playback (images, videos via ffpyplayer)
• ✅ Playlist sync from DigiServer (HTTP/HTTPS)
• ✅ Touch & mouse controls
• ✅ Settings popup
• ✅ Image editing/annotation
• ✅ Password-protected exit
• ✅ Web links (opens in Chrome/Edge kiosk)
• ✅ Network monitoring
• ✅ Auto-update playlist

What is disabled on Windows

• ❌ Card reader (evdev is Linux-only; EVDEV_AVAILABLE = False)
• ❌ HDMI power management (tvservice is RPi-specific)
• ❌ WiFi restart (uses Linux nmcli)

🚀 Quick Start (Development)

Prerequisites

1. Python 3.10+ (64-bit) — python.org
2. FFmpeg — for video codec support
   • Download from ffmpeg.org
   • Add bin\ folder to your PATH
3. Visual C++ Redistributable — latest

Install & Run

cd windows

REM Create virtual environment
python -m venv venv
venv\Scripts\activate

REM Install dependencies
pip install -r requirements_win.txt

REM Run in development mode
python run_win.py

📦 Building the .exe

One-Command Build

cd windows
build_win.bat

Manual Build

cd windows
venv\Scripts\activate
pip install -r requirements_win.txt
pyinstaller build.spec --clean --noconfirm

Output

windows\dist\KiwySignagePlayer\
    ├── KiwySignagePlayer.exe     # Main executable
    ├── config/                    # Config files (auto-copied)
    ├── resources/                 # Icons, intro video
    └── ... (supporting DLLs)

For a single-file .exe, edit build.spec — uncomment the exe_onefile section and comment out the coll = COLLECT(...) section.

⚙️ Configuration

1. On first run, config files are created in %APPDATA%\KiwySignage\
2. Edit %APPDATA%\KiwySignage\config\app_config.json to set your server:

{
  "server_ip": "192.168.0.109",
  "port": "8080",
  "screen_name": "Birou_IT",
  "quickconnect_key": "8887779",
  "orientation": "Landscape",
  "touch": "True",
  "max_resolution": "1920x1080",
  "edit_feature_enabled": true,
  "use_https": false,
  "verify_ssl": false
}

🧪 Testing

cd windows
venv\Scripts\activate
python run_win.py

🔧 Troubleshooting

Problem	Solution
"ffpyplayer not found"	Install: pip install ffpyplayer
"No video" / black screen	Install FFmpeg and add to PATH. Try KIVY_GL_BACKEND=angle_sdl2 or KIVY_GL_BACKEND=gl
Kivy window doesn't open	Run from command prompt to see error messages. Ensure GPU drivers are up to date.
Weblinks not opening	Install Google Chrome or Microsoft Edge
Can't connect to server	Check firewall. Try use_https: false and verify_ssl: false for testing
Antivirus flags .exe	Add the output folder to antivirus exclusions. This is a false positive common with PyInstaller.

📁 Project Structure (Build)

Kiwy-Signage/
├── windows/
│   ├── run_win.py              # Windows entry point (patches platform differences)
│   ├── build.spec              # PyInstaller configuration
│   ├── build_win.bat           # One-click build script
│   ├── pyi_runtime_hook.py     # PyInstaller runtime hook
│   ├── requirements_win.txt    # Windows Python dependencies
│   └── README_WINDOWS_BUILD.md # This file
├── src/
│   ├── main.py                 # Main application (original)
│   ├── get_playlists_v2.py     # Playlist sync
│   ├── player_auth.py          # Authentication
│   ├── ssl_utils.py            # SSL/HTTPS
│   ├── keyboard_widget.py      # On-screen keyboard
│   ├── network_monitor.py      # Network monitoring
│   ├── edit_popup.py           # Image editing
│   └── signage_player.kv       # Kivy UI layout
├── config/
│   ├── app_config.json         # Player configuration
│   └── resources/              # Icons, images, intro video
├── media/                      # Downloaded media (created at runtime)
├── playlists/                  # Playlist files (created at runtime)
└── logs/                       # Log files (created at runtime)