MQTT API

Native firmware publishes device state and motion events through an MQTT broker. Clients can also track availability and send the supported commands.

MQTT uses the shared device protocol. Its resource payloads, operations, validation rules, and result codes match Direct HTTP. MQTT topics and broker delivery replace HTTP paths and responses; sensing semantics stay the same.

Find the device topic

The default device root is espectre/v1/devices/<device-id>. A custom topic prefix changes the first part, while the stable device ID remains the final segment. Subscribe to the retained capabilities topic first; its catalog is authoritative for that device.

mosquitto_sub -h <broker> \
  -t 'espectre/v1/devices/+/capabilities' -v

Native firmware includes the MQTT API. SDK products can expose it by integrating the MQTT adapter. ESPHome and Matter use their own transports.

Subscribe to state and events

Suffix	Retained	Purpose
`health`	yes	Availability, uptime, and Last Will
`device`	yes	Device identity and build
`capabilities`	yes	Protocol negotiation and supported surface
`sensing`	yes	Sensing state, readiness, detector, and controls
`wifi`	yes	Redacted radio state
`ota`	yes	Firmware update state
`motion`	no	Per-evaluation motion event
`fault`	no	Runtime fault event
`commands/result`	no	Correlated command result

The retained health message is also the Home Assistant availability topic. After an ungraceful disconnect, the broker publishes the retained offline Last Will. There is no application heartbeat in addition to MQTT keepalive.

mosquitto_sub -h <broker> \
  -t 'espectre/v1/devices/<device-id>/#' -v

Send a command

Publish JSON commands to commands/request. Every request has a unique command_id and a command. Operation parameters remain at the top level.

mosquitto_pub -h <broker> \
  -t 'espectre/v1/devices/<device-id>/commands/request' \
  -m '{"command_id":"cmd-42","command":"update_sensing","threshold":0.5}'

Subscribe to commands/result before publishing so the client receives the reply. The response repeats command_id and command, then reports whether the device accepted the request:

{
  "command_id":"cmd-42",
  "command":"update_sensing",
  "accepted":true,
  "code":"ok",
  "message":"sensing updated"
}

Command	Parameters	Purpose
`update_device`	`label`	Set or clear the device label
`update_sensing`	Supported sensing subset	Update detector and traffic settings
`recalibrate`	none	Start detector recalibration
`read_diagnostics`	none	Return an on-demand diagnostics snapshot in `data`
`check_ota`	optional `channel`	Check a firmware channel
`start_ota`	optional `channel`	Start an update from a firmware channel

A command payload is limited to 2,048 bytes. An unsupported command returns accepted: false with code forbidden. Validation and runtime failures use the same result codes as HTTP.

Use HTTP for Direct-only access

MQTT has no topics for broker configuration, discovery results, raw CSI, or retained diagnostics. Configure MQTT through Direct HTTP or the device settings tool. Use read_diagnostics for an on-demand snapshot, and use Direct HTTP for peer discovery and CSI collection.

Home Assistant MQTT Discovery publishes entity definitions under homeassistant/. Those topics are separate from the canonical ESPectre device topics.

Protect the broker

The MQTT wifi resource omits the SSID, BSSID, and IP address. Other messages contain a stable pseudonymous device ID, user-provided labels, movement data, and operational telemetry. Restrict broker access and use per-device credentials.

Use mqtt for explicit plaintext TCP on a trusted local broker. Use mqtts for TLS with hostname verification. Native does not support MQTT over WebSockets.

Protocol reference

The MQTT contract in API.md defines the payload fields, constraints, result codes, and compatibility rules. The HTTP API documents the shared resources and Direct-only capabilities.