Spectra

Display random Unsplash photos on an Inky Impression e-paper display, with a web interface for uploading your own images.

Features

• Fetches random high-resolution photos from Unsplash (cached to gallery)
• Upload your own images via the web interface (drag-and-drop, multi-file)
• Centres and scales images to fit the display resolution
• Colour saturation tuning for e-paper
• Web dashboard with preview, gallery, rotation queue, and config editor
• MQTT integration for remote commands and status reporting
• Simulation mode for testing without hardware (configurable resolution)
• systemd integration for automatic updates on a schedule
• Randomised update intervals to avoid predictable refreshes
• Config hot-reload — no service restart needed for setting changes

Requirements

• Raspberry Pi (any model with GPIO)
• Pimoroni Inky Impression (4.0", 7.3", or 13.3")
• Python 3.9+
• Unsplash API access key

Installation

Run the installer on a Raspberry Pi:

./install.sh

The installer will:

1. Install the Pimoroni Inky library (skipped if not a Raspberry Pi)
2. Install Python dependencies (including web server and MQTT)
3. Install the spectra package
4. Copy the default config to /etc/spectra/config.yaml
5. Install and enable both the display and web interface systemd services

Manual installation

pip install -r requirements.txt
pip install -e .

Configuration

Edit /etc/spectra/config.yaml (or ~/.config/spectra/config.yaml or config.yaml in the current directory):

unsplash:
  access_key: "your_access_key_here"
  query: "nature"
  orientation: "landscape"
  collections: ""

display:
  saturation: 0.5
  # resolution:
  #   width: 800
  #   height: 480

schedule:
  interval_hours: 1
  random_delay_seconds: 300

mqtt:
  enabled: false
  broker: localhost
  port: 1883
  topic_prefix: spectra
  client_id: spectra-display
  username: ""
  password: ""

paths:
  cache: /var/cache/spectra

Usage

Display loop

# Run once and exit
spectra --once

# Run once in simulation mode
spectra --once --simulate

# Simulate at a specific resolution
spectra --once --simulate --width 800 --height 480

# Run with a custom config
spectra -c /path/to/config.yaml

# Run continuously
spectra

Web interface

# Start the web interface (default: http://0.0.0.0:5000)
spectra web

# With custom host/port
spectra web --host 0.0.0.0 --port 5000

# Verbose logging
spectra web -v

The web interface provides:

• Dashboard — display status, schedule info, quick actions (refresh, clear)
• Gallery — browse all uploaded and cached Unsplash images, trigger "show now"
• Upload — drag-and-drop multiple image files with progress tracking
• Settings — live-edit Unsplash, display, schedule, and MQTT configuration

MQTT

When MQTT is enabled in the config, the display loop subscribes to commands and publishes status. See MQTT integration docs for details.

systemd services

Two systemd services are installed:

• spectra.service — the display loop (fetches Unsplash, processes triggers)
• spectra-web.service — the web interface (Flask + htmx)

sudo systemctl start spectra
sudo systemctl stop spectra-web
sudo systemctl status spectra-web

# View logs
journalctl -u spectra -f
journalctl -u spectra-web -f

Project structure

spectra/
├── config.yaml              # Example configuration
├── install.sh               # Installer script
├── pyproject.toml           # Package metadata
├── requirements.txt         # Python dependencies
├── spectra/
│   ├── __init__.py
│   ├── __main__.py          # python -m spectra entry point
│   ├── cli.py               # CLI argument parsing and main loop
│   ├── config.py            # Configuration loader
│   ├── config_manager.py    # Config read/write with YAML write-back
│   ├── display.py           # Inky display abstraction and image processing
│   ├── fetcher.py           # Unsplash API client
│   ├── library.py           # Unsplash image caching to SQLite library
│   ├── mqtt.py              # MQTT client (commands + status)
│   ├── trigger.py           # Shared trigger file (web server → display loop)
│   └── web/
│       ├── server.py        # Flask app factory and API routes
│       ├── models.py        # SQLAlchemy models
│       ├── templates/       # Jinja2 templates (6 pages)
│       ├── static/          # CSS and JS
│       └── __init__.py
├── systemd/
│   ├── spectra.service      # Display loop systemd unit
│   └── spectra-web.service  # Web interface systemd unit
└── docs/
    ├── web-interface.md     # Web interface documentation
    └── mqtt.md              # MQTT integration documentation