HiveMQ · AsyncAPI Specification
HiveMQ MQTT Broker
Version 4.x
AsyncAPI description of the message-oriented surface of a HiveMQ enterprise MQTT broker. HiveMQ implements MQTT 3.1, MQTT 3.1.1, and MQTT 5 over plain TCP, TLS, WebSocket, and Secure WebSocket listeners. MQTT is a publish and subscribe protocol — topics are defined by the deploying organization rather than predefined by the broker. This document therefore models the standard transport bindings, the WebSocket subprotocol, the supported QoS levels, and a generic application topic plus the optional Sparkplug B namespace that is commonly deployed on HiveMQ for industrial IoT use cases.
Channels
{topic}
Publish a message to an MQTT topic.
Generic MQTT application topic. MQTT topics are UTF-8 strings organised as hierarchical levels separated by `/`. Wildcards `+` (single level) and `#` (multi level) are valid only in subscriptions. The actual topic tree is defined by the application that uses HiveMQ.
spBv1.0/{group_id}/NBIRTH/{edge_node_id}
Sparkplug B Edge Node BIRTH certificate. Published by an Edge of Network (EoN) node when it comes online. Payload is a Sparkplug B protobuf encoded `Payload` message containing the node's metrics. Sparkplug B is an OASIS standard commonly deployed on HiveMQ for industrial IoT.
spBv1.0/{group_id}/NDEATH/{edge_node_id}
Sparkplug B Edge Node DEATH certificate. Registered as the MQTT Last Will and Testament for the EoN node so the broker publishes it when the node disconnects ungracefully.
spBv1.0/{group_id}/NDATA/{edge_node_id}
Sparkplug B Edge Node DATA — runtime metric updates from the EoN node.
spBv1.0/{group_id}/NCMD/{edge_node_id}
Sparkplug B Edge Node COMMAND — write commands targeted at the EoN node.
spBv1.0/{group_id}/DBIRTH/{edge_node_id}/{device_id}
Sparkplug B Device BIRTH certificate for a device attached to an EoN node.
spBv1.0/{group_id}/DDEATH/{edge_node_id}/{device_id}
Sparkplug B Device DEATH certificate for an attached device.
spBv1.0/{group_id}/DDATA/{edge_node_id}/{device_id}
Sparkplug B Device DATA — runtime metric updates from a device.
spBv1.0/{group_id}/DCMD/{edge_node_id}/{device_id}
Sparkplug B Device COMMAND — write commands targeted at a device.
spBv1.0/STATE/{scada_host_id}
Sparkplug B primary application (SCADA host) STATE message. Indicates whether the primary host application is ONLINE or OFFLINE.
Messages
MqttApplicationMessage
Generic MQTT Application Message
An MQTT PUBLISH payload. Payload is opaque to the broker; HiveMQ forwards bytes unchanged. MQTT 5 adds user properties, payload format indicator, content type, response topic, and correlation data which are modeled in the message headers.
SparkplugPayload
Sparkplug B Payload
Sparkplug B protobuf-encoded `Payload` message as defined by the Eclipse Tahu / OASIS Sparkplug specification. Contains a timestamp, sequence number, and a list of metrics with names, datatypes, and values.
Servers
mqtt
tcp
localhost:1883
Default plain TCP MQTT listener on IANA port 1883. Accepts MQTT 3.1, MQTT 3.1.1, and MQTT 5 clients.
secure-mqtt
tls
localhost:8883
Default TLS-secured MQTT listener on IANA port 8883.
ws
websocket
ws://localhost:8000/mqtt
MQTT over WebSocket listener. HiveMQ uses the WebSocket subprotocol identifier `mqtt`, which carries both MQTT 3.1.1 and MQTT 5. The default path is `/mqtt` and the typical port is 8000.
wss
secure-websocket
wss://localhost:8884/mqtt
MQTT over TLS-secured WebSocket. Subprotocol `mqtt`, default path `/mqtt`, typical port 8884.
AsyncAPI Specification
Work with this as data
Every AsyncAPI spec here is available over the APIs.io API and to AI agents over MCP.