216 lines
5.6 KiB
Markdown
216 lines
5.6 KiB
Markdown
# Spectra
|
|
|
|
Display random Unsplash photos on an Inky Impression e-paper display, with a web
|
|
interface for uploading your own images.
|
|
|
|
---
|
|
|
|
- [Requirements](#requirements)
|
|
- [Quick start](#quick-start)
|
|
- [Configuration](#configuration)
|
|
- [Display orientation](#display-orientation)
|
|
- [MQTT](#mqtt)
|
|
- [Usage](#usage)
|
|
- [Display loop](#display-loop)
|
|
- [Web interface](#web-interface)
|
|
- [systemd services](#systemd-services)
|
|
- [Running tests](#running-tests)
|
|
- [Project structure](#project-structure)
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Raspberry Pi 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)
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# Install
|
|
cp config.example.yaml config.yaml # edit with your Unsplash key
|
|
pip install -r requirements.txt
|
|
pip install -e .
|
|
|
|
# Run once in simulation mode
|
|
spectra --once --simulate
|
|
|
|
# Start the web interface
|
|
spectra web
|
|
|
|
# Run the display loop continuously
|
|
spectra
|
|
```
|
|
|
|
Or on a Pi with systemd:
|
|
|
|
```bash
|
|
sudo ./install.sh
|
|
sudo systemctl start spectra spectra-web
|
|
```
|
|
|
|
## Configuration
|
|
|
|
spectra looks for `config.yaml` in this order:
|
|
|
|
1. `$PWD/config.yaml`
|
|
2. `~/.config/spectra/config.yaml`
|
|
3. `/etc/spectra/config.yaml`
|
|
|
|
Pass a custom path with `spectra -c /path/to/config.yaml`.
|
|
|
|
```yaml
|
|
unsplash:
|
|
access_key: "your_access_key_here"
|
|
query: "nature"
|
|
collections: ""
|
|
|
|
display:
|
|
saturation: 0.5
|
|
orientation: 0
|
|
resolution:
|
|
width: 1600
|
|
height: 1200
|
|
|
|
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
|
|
```
|
|
|
|
### Display orientation
|
|
|
|
Set `display.orientation` to match how the panel is physically mounted. The
|
|
Unsplash orientation filter (`landscape`/`portrait`/`squarish`) is derived
|
|
automatically — the old `unsplash.orientation` config key is ignored.
|
|
|
|
| Value | Unsplash filter | Effect |
|
|
|-------|----------------|--------|
|
|
| 0 | landscape | Default horizontal mount |
|
|
| 90 | portrait | Vertical mount |
|
|
| 180 | landscape | Upside-down horizontal |
|
|
| 270 | portrait | Upside-down vertical |
|
|
|
|
Images are cropped to the effective aspect ratio, resized, then rotated for the
|
|
physical panel. Preview and thumbnails reflect the configured orientation.
|
|
Change it live from Settings > Display Orientation or via config hot-reload.
|
|
|
|
### MQTT
|
|
|
|
When enabled, the display loop subscribes to `{prefix}/command/#` and publishes
|
|
status to `{prefix}/status`. See [MQTT integration docs](docs/mqtt.md) for
|
|
commands, Home Assistant examples, and debugging.
|
|
|
|
## Usage
|
|
|
|
### Display loop
|
|
|
|
```bash
|
|
spectra # run continuously
|
|
spectra --once # fetch one photo and exit
|
|
spectra --once --simulate # save to /tmp/spectra_last.png
|
|
spectra --simulate --width 800 --height 480
|
|
spectra -c /path/to/config.yaml
|
|
```
|
|
|
|
### Web interface
|
|
|
|
```bash
|
|
spectra web # http://0.0.0.0:5000
|
|
spectra web --port 8080
|
|
spectra web -v # verbose (debug mode only on localhost)
|
|
```
|
|
|
|
| Page | What it does |
|
|
|------|-------------|
|
|
| **Dashboard** | Display status, schedule, quick actions (refresh, clear) |
|
|
| **Gallery** | Browse images, trigger "show now", delete |
|
|
| **Upload** | Drag-and-drop multi-file upload with progress |
|
|
| **Settings** | Live-edit Unsplash, display, schedule, MQTT |
|
|
| **Preview** | See how an image looks on the display |
|
|
|
|
## systemd services
|
|
|
|
Two units are installed by `install.sh`:
|
|
|
|
- `spectra.service` — display loop
|
|
- `spectra-web.service` — web interface
|
|
|
|
```bash
|
|
sudo systemctl start spectra
|
|
sudo systemctl stop spectra-web
|
|
journalctl -u spectra -f
|
|
journalctl -u spectra-web -f
|
|
```
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
pytest tests/
|
|
```
|
|
|
|
107 tests covering config loading, display processing (crop, resize, rotation),
|
|
trigger atomicity, MQTT parsing, and all 19 API routes.
|
|
|
|
A [Gitea Actions](.gitea/workflows/test.yml) workflow runs tests on every push.
|
|
|
|
See [bug-tracking.md](bug-tracking.md) for known issues and recent fixes.
|
|
|
|
## Project structure
|
|
|
|
```
|
|
spectra/
|
|
├── config.example.yaml
|
|
├── .gitignore
|
|
├── install.sh
|
|
├── pyproject.toml
|
|
├── requirements.txt
|
|
├── spectra/
|
|
│ ├── cli.py # CLI, display loop, config hot-reload
|
|
│ ├── config.py # Config loader with deep-merge
|
|
│ ├── config_manager.py # Config read/write
|
|
│ ├── display.py # Image processing, rotation, hardware abstraction
|
|
│ ├── fetcher.py # Unsplash API client
|
|
│ ├── library.py # Unsplash image caching to SQLite
|
|
│ ├── mqtt.py # MQTT client (commands + heartbeat)
|
|
│ ├── trigger.py # Thread-safe trigger file (web → display loop)
|
|
│ └── web/
|
|
│ ├── server.py # Flask app, 19 API routes
|
|
│ ├── models.py # SQLAlchemy models
|
|
│ ├── templates/ # 6 Jinja2 pages
|
|
│ └── static/ # CSS + JS
|
|
├── .gitea/
|
|
│ └── workflows/
|
|
│ └── test.yml # CI workflow
|
|
├── tests/
|
|
│ ├── test_api.py
|
|
│ ├── test_config.py
|
|
│ ├── test_display.py
|
|
│ ├── test_gallery.py
|
|
│ ├── test_mqtt.py
|
|
│ ├── test_orientation.py
|
|
│ ├── test_trigger.py
|
|
│ └── conftest.py
|
|
├── systemd/
|
|
│ ├── spectra.service
|
|
│ └── spectra-web.service
|
|
└── docs/
|
|
├── display-orientation.md
|
|
├── web-interface.md
|
|
└── mqtt.md
|
|
```
|