# 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).