176 lines
4.9 KiB
Markdown
176 lines
4.9 KiB
Markdown
# 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](https://shop.pimoroni.com/products/inky-impression) (4.0", 7.3", or 13.3")
|
|
- Python 3.9+
|
|
- [Unsplash API access key](https://unsplash.com/developers)
|
|
|
|
## Installation
|
|
|
|
Run the installer on a Raspberry Pi:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](docs/mqtt.md) 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)
|
|
|
|
```bash
|
|
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
|
|
```
|