First commit with entire first rendition of the project

2026-06-25 21:18:07 -06:00
commit 551322a94b
42 changed files with 4346 additions and 0 deletions
--- a/docs/mqtt.md
+++ b/docs/mqtt.md
@@ -0,0 +1,146 @@
+# MQTT Integration
+
+Spectra can be controlled and monitored over MQTT. The MQTT client runs as a background thread in the display loop process (`spectra` service) and connects to any standard MQTT broker.
+
+## Configuration
+
+Enable MQTT in `config.yaml`:
+
+```yaml
+mqtt:
+  enabled: true
+  broker: 192.168.1.100
+  port: 1883
+  topic_prefix: spectra
+  client_id: spectra-display
+  username: ""
+  password: ""
+```
+
+- **enabled** — set to `true` to start the MQTT client
+- **broker** — hostname or IP of your MQTT broker
+- **port** — broker port (default: 1883)
+- **topic_prefix** — prefix for all MQTT topics (default: `spectra`)
+- **client_id** — unique client identifier for the MQTT connection
+- **username / password** — optional credentials for authenticated brokers
+
+Changes to MQTT settings are hot-reloaded by the display loop — no service restart needed. If you disable MQTT, the client disconnects cleanly.
+
+## Topics
+
+All topics use the configured `topic_prefix`. The examples below assume the default prefix `spectra`.
+
+### Commands (subscribe)
+
+Spectra subscribes to `spectra/command/#` and dispatches based on the command suffix.
+
+| Topic | Payload | Action |
+|-------|---------|--------|
+| `spectra/command/refresh` | *(ignored)* | Triggers an Unsplash refresh on the next display cycle |
+| `spectra/command/clear` | *(ignored)* | Clears the display to white on the next cycle |
+| `spectra/command/show/<id>` | *(ignored)* | Shows a library image by its database ID |
+| `spectra/command/status` | *(ignored)* | Publishes a fresh status message |
+
+Example commands:
+
+```bash
+# Refresh from Unsplash
+mosquitto_pub -h 192.168.1.100 -t "spectra/command/refresh" -n
+
+# Clear the display
+mosquitto_pub -h 192.168.1.100 -t "spectra/command/clear" -n
+
+# Show a specific image from the library (ID 5)
+mosquitto_pub -h 192.168.1.100 -t "spectra/command/show/5" -n
+
+# Request a status update
+mosquitto_pub -h 192.168.1.100 -t "spectra/command/status" -n
+```
+
+### Status (publish)
+
+Spectra publishes JSON status messages to `spectra/status`.
+
+**Connection event** (published on successful connect):
+
+```json
+{
+  "action": "connected",
+  "status": "ok"
+}
+```
+
+**Command acknowledgements** (published after processing each command):
+
+```json
+{
+  "action": "refresh",
+  "status": "triggered"
+}
+```
+
+On error (e.g. invalid image ID):
+
+```json
+{
+  "action": "show",
+  "status": "error",
+  "error": "image_not_found"
+}
+```
+
+**Heartbeat** (published every 5 minutes):
+
+```json
+{
+  "action": "heartbeat",
+  "status": "running",
+  "timestamp": 1719334800.0
+}
+```
+
+## Home Assistant integration
+
+You can integrate Spectra into Home Assistant using MQTT. Add the following to your `configuration.yaml`:
+
+```yaml
+mqtt:
+  sensor:
+    - name: "Spectra Status"
+      state_topic: "spectra/status"
+      value_template: "{{ value_json.action }}"
+
+  button:
+    - name: "Spectra Refresh"
+      command_topic: "spectra/command/refresh"
+      payload_press: ""
+    - name: "Spectra Clear"
+      command_topic: "spectra/command/clear"
+      payload_press: ""
+```
+
+## Example: Node-RED flow
+
+A Node-RED flow can listen for commands via HTTP (from a web dashboard) and forward them to MQTT, or forward MQTT status events to a database.
+
+```json
+[{"id":"spectra-mqtt","type":"mqtt in","topic":"spectra/command/#","name":"Spectra Commands"}]
+```
+
+Subscribe to `spectra/status` to build a real-time dashboard with display state, last action, and connectivity status.
+
+## Debugging
+
+Check the display service logs for MQTT connection events:
+
+```bash
+journalctl -u spectra -f | grep MQTT
+```
+
+A successful connection logs:
+```
+MQTT connected to 192.168.1.100:1883
+MQTT subscribed to spectra/command/#
+```
+
+A failed connection logs the return code (see [MQTT spec](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718035) for rc meanings).