147 lines
3.8 KiB
Markdown
147 lines
3.8 KiB
Markdown
# 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).
|