A universal client for displaying images from a FrameSync server on various display devices. Supports e-paper displays, desktop monitors, tablets, smart displays, and more through a modular display handler system.

• Universal Display Support - Works with any display through configurable handlers
• Automatic Updates - Periodically fetches and displays new images
• Modular Architecture - Easy to add support for new display types
• Systemd Integration - Runs as a service with auto-start on boot
• Robust - Automatic reconnection and error recovery
• Lightweight - Minimal dependencies and resource usage

• E-Paper Displays - Waveshare and compatible e-ink screens
• X11 Desktops - Using feh image viewer
• Chromium Kiosk - For tablets and smart displays
• Linux Framebuffer - For headless LCD displays
• Custom Handlers - Easy to add your own

# Clone or copy the repository
git clone <repository-url>
cd framesync-client

# Install dependencies
pip3 install requests python-dotenv
# Or on Debian/Ubuntu:
sudo apt install python3-requests python3-dotenv

# Copy environment template
cp .env.example .env

Edit .env with your settings:

nano .env

Required settings:

• FRAMESYNC_SERVER_URL - URL of your FrameSync server
• FRAMESYNC_DEVICE_ID - Unique identifier for this display
• FRAMESYNC_DISPLAY_HANDLER - Command to display images

See .env.example for all available options.

# Test connection and display one image
python3 client.py --once

# Copy the systemd service file (modify paths as needed)
sudo cp framesync-client.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable framesync-client
sudo systemctl start framesync-client

The client uses configurable display handlers to support different hardware. Set FRAMESYNC_DISPLAY_HANDLER in your .env file:

FRAMESYNC_DISPLAY_HANDLER=python3 {script_dir}/display_image.py {image_path}

Requires: Waveshare e-paper library

FRAMESYNC_DISPLAY_HANDLER={script_dir}/display_handlers/feh_fullscreen.sh {image_path}

Requires: sudo apt install feh

FRAMESYNC_DISPLAY_HANDLER={script_dir}/display_handlers/chromium_kiosk.sh {image_path}

Requires: sudo apt install chromium-browser

FRAMESYNC_DISPLAY_HANDLER={script_dir}/display_handlers/framebuffer.sh {image_path}

Requires: sudo apt install fbi

FRAMESYNC_DISPLAY_HANDLER=/path/to/your/script.sh {image_path}

All configuration is stored in .env:

python3 client.py --configure

python3 client.py --once

python3 client.py

# Start service
sudo systemctl start framesync-client

# Stop service
sudo systemctl stop framesync-client

# Restart service
sudo systemctl restart framesync-client

# View status
sudo systemctl status framesync-client

# View logs
sudo journalctl -u framesync-client -f

1. Install e-paper library (follow manufacturer's instructions)
2. Configure .env:

FRAMESYNC_SERVER_URL=http://your-server:5000
FRAMESYNC_DEVICE_ID=epaper-display-001
FRAMESYNC_DISPLAY_HANDLER=python3 {script_dir}/display_image.py {image_path}

3. Install as service (see above)

1. Install feh: sudo apt install feh
2. Configure .env using the feh handler
3. Run: python3 client.py

1. Install Chromium
2. Configure .env using the Chromium kiosk handler
3. Install as service for auto-start

Display handlers are simple scripts that take an image path and display it:

#!/bin/bash
IMAGE_PATH="$1"

# Your display logic here
# Example: copy to a specific location
cp "$IMAGE_PATH" /path/to/display/

exit 0  # Return 0 on success

Make it executable and reference it in .env:

chmod +x my_handler.sh

FRAMESYNC_DISPLAY_HANDLER=/path/to/my_handler.sh {image_path}

• Verify FRAMESYNC_SERVER_URL is correct
• Test connectivity: curl http://your-server:5000
• Check firewall rules

• Ensure images are uploaded to the server
• Verify images are assigned to your device ID
• Check device registration on server

• Test handler manually: ./display_handlers/your_handler.sh /path/to/test.jpg
• Check logs: sudo journalctl -u framesync-client -f
• Verify handler dependencies are installed

• Check service status: sudo systemctl status framesync-client
• Verify paths in service file
• Check file permissions

┌─────────────────────┐
│  FrameSync Server   │
│  (Remote/Local)     │
└──────────┬──────────┘
           │ HTTP API
           │
┌──────────▼──────────┐
│  FrameSync Client   │
│  - Register device  │
│  - Fetch images     │
│  - Download         │
└──────────┬──────────┘
           │
┌──────────▼──────────┐
│  Display Handler    │
│  - E-Paper          │
│  - feh              │
│  - Chromium         │
│  - Custom           │
└─────────────────────┘

• Python 3.7+
• requests library
• python-dotenv library
• Display-specific dependencies (varies by handler)

MIT License - See LICENSE file for details

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Test your changes
4. Submit a pull request

• Never commit .env files (already in .gitignore)
• Use HTTPS for remote servers when possible
• Restrict network access to trusted sources
• Use unique device IDs to prevent conflicts

For issues or questions:

• Check the troubleshooting section
• Review logs: sudo journalctl -u framesync-client -f
• Test manually: python3 client.py --once