MQTT API

Native firmware publishes device state and motion events through an MQTT broker. Clients can also see whether the device is online and send commands.

One protocol, two transports. Messages, operations, validation rules, and result codes are the same as in Direct HTTP. Only the delivery changes: topics instead of paths, and a broker instead of HTTP responses.

Sections

Find the device topic

By default, each device publishes under espectre/v1/devices/<device-id>. A custom topic prefix replaces the first part; the device ID always comes last. Subscribe to the retained capabilities topic first to see what the device supports.

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

Native firmware includes the MQTT API, and SDK products can add it with the MQTT adapter. ESPHome and Matter use their own protocols.

Suffix	Retained	Purpose
`health`	yes	Online or offline, and uptime
`device`	yes	Device identity and build
`capabilities`	yes	Protocol version and supported features
`sensing`	yes	Sensing state, readiness, detector, and controls
`wifi`	yes	Radio state, without network names or addresses
`ota`	yes	Firmware update state
`motion`	no	Motion event, one per decision
`fault`	no	Error event
`commands/result`	no	Result of a command

Home Assistant also uses health to know if the device is online. If the device drops off without saying goodbye, the broker publishes its offline message (MQTT Last Will). There is no separate heartbeat besides MQTT keepalive.

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

Send a command

Publish JSON commands to commands/request. Each one needs a unique command_id and a command; parameters go at the top level too.

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 you don't miss the reply. It repeats command_id and command, and says 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`	Sensing settings to change	Update detector and traffic settings
`recalibrate`	none	Start detector recalibration
`read_diagnostics`	optional `fields` array	Return the list of values, the selected values, or all of them with `["*"]`, in `data`
`check_ota`	optional `channel`	Check a firmware channel
`start_ota`	optional `channel`	Start an update from a firmware channel

A command can be at most 2,048 bytes. A command outside the MQTT list returns accepted: false with code forbidden. An operation this firmware leaves out of its capabilities returns unsupported. Other errors use the same codes as HTTP.

What needs Direct HTTP

MQTT cannot change the broker settings, list nearby devices, or stream raw CSI. Use Direct HTTP or Device settings for those. For diagnostics, send read_diagnostics with the fields you want.

The Home Assistant discovery messages under homeassistant/ are separate from the ESPectre topics above.

Protect the broker

The MQTT wifi message leaves out the network name, access point, and IP address. Other messages still include the device ID, your device label, movement data, and diagnostics. Limit who can use the broker, and give each device its own credentials.

Use mqtt (unencrypted) only with a trusted local broker, and mqtts for TLS with hostname checking. MQTT over WebSockets is not supported.

Protocol reference

The MQTT section of the API reference defines every field, limit, result code, and compatibility rule. The HTTP API describes the shared resources and the HTTP-only features.

SDK guide