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:

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.

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:

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

{
  "action": "connected",
  "status": "ok"
}

Command acknowledgements (published after processing each command):

{
  "action": "refresh",
  "status": "triggered"
}

On error (e.g. invalid image ID):

{
  "action": "show",
  "status": "error",
  "error": "image_not_found"
}

Heartbeat (published every 5 minutes):

{
  "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:

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.

[{"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:

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 for rc meanings).

3.8 KiB Raw Blame History