First commit with entire first rendition of the project
This commit is contained in:
Your Name
175
README.md
Normal file
175
README.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user