MQTT Server Documentation

MQTT server overview

The Nexxa MQTT server is the authenticated message entry point for detectors. A detector sends messages through its own cellular connection; it does not send telemetry or alarms directly to Django and does not depend on household Wi-Fi.

The same MQTT contract is used over public cellular internet or a private APN. PostgreSQL is the durable source of truth; Redis holds current device state and last-seen data.

Connection information

The public Nexxa endpoint is mqtt.nexxafire.com. Configure the detector certificate trust and hostname verification for this exact domain.

• Validate the server certificate and hostname. Never disable certificate verification.
• The current client uses the MQTT 3.1.1 baseline. MQTT 5.0 is not enabled by default; confirm compatibility before enabling it in firmware.
• Port 1883 is plaintext MQTT for local development/internal Docker networking only. The production overlay does not expose it publicly.
• Production public availability depends on deployment DNS, firewall, certificate renewal, and cellular/APN routing. See the status section before scheduling a physical pilot.

Device authentication

Every detector has an individual Device ID and a unique password. The Device ID is the MQTT username and is also the device namespace in the topic path. Shared device credentials are not permitted.

Provisioning and broker authentication

1. An authorized Nexxa operator registers and provisions the detector.
2. Nexxa returns a one-time package containing the Device ID, username, password, and topic list through an approved secure channel.
3. The broker validates the credential and device lifecycle state for every connection.
4. The broker applies device-level topic authorization so each detector can use only its own namespace.

The detector connects only to the MQTT endpoint. Provisioning and operator administration are handled separately by Nexxa.

MQTT topic structure

All device topics follow nexxa/v1/devices/{device_id}/{message_type}. Replace {device_id} with the provisioned identifier exactly; do not add or remove path segments.

Namespace isolation: A device cannot publish to or subscribe to another device's namespace. Topic authorization is applied by the broker for every device connection.

Go ingestion subscriptions

Go subscribes to nexxa/v1/devices/+/telemetry, /alarm, /status, /heartbeat, and /ack. The Go service publishes no device telemetry; the command worker publishes commands and simulated acknowledgements only when the configured command mode permits it.

Message formats

Device-originated messages use the Nexxa v1 JSON envelope. Examples below use fake values only and are not credentials or live device records.

{
  "device_id": "NX-TW-EXAMPLE-001",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-08-24T12:00:00Z",
  "type": "telemetry",
  "payload": {}
}

Required envelope fields: device_id, unique message_id, RFC3339 UTC timestamp, topic-matching type, and an object payload. The message device ID must match the topic.

Heartbeat · device publishes

{
  "device_id": "NX-TW-EXAMPLE-001",
  "message_id": "550e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2026-08-24T12:00:00Z",
  "type": "heartbeat",
  "payload": {
    "uptime_seconds": 86400,
    "battery_voltage": 3.6
  }
}

Telemetry · device publishes

{
  "device_id": "NX-TW-EXAMPLE-001",
  "message_id": "550e8400-e29b-41d4-a716-446655440002",
  "timestamp": "2026-08-24T12:00:05Z",
  "type": "telemetry",
  "payload": {
    "temperature_c": 24.5,
    "humidity_percent": 62.0,
    "smoke_density": 0.02,
    "battery_voltage": 3.6,
    "signal_strength_dbm": -65
  }
}

Fire alarm · device publishes

{
  "device_id": "NX-TW-EXAMPLE-001",
  "message_id": "550e8400-e29b-41d4-a716-446655440003",
  "timestamp": "2026-08-24T12:01:00Z",
  "type": "alarm",
  "payload": {
    "alarm_type": "SMOKE",
    "severity": "critical",
    "detection_type": "smoke",
    "confidence": 0.98,
    "location": { "latitude": 5.6037, "longitude": -0.1870 }
  }
}

Alarm examples can create operational events. Send only with an approved test device and an agreed test window. Supported detection types include smoke, heat, manual, and test.

Status · device publishes

{
  "device_id": "NX-TW-EXAMPLE-001",
  "message_id": "550e8400-e29b-41d4-a716-446655440004",
  "timestamp": "2026-08-24T12:02:00Z",
  "type": "status",
  "payload": {
    "status": "online",
    "reason": "boot_complete"
  }
}

The implementation accepts status or state. Accepted values are online, offline, fault, low_battery, and normal.

ACK · device publishes

{
  "device_id": "NX-TW-EXAMPLE-001",
  "message_id": "550e8400-e29b-41d4-a716-446655440005",
  "timestamp": "2026-08-24T12:03:00Z",
  "type": "ack",
  "payload": {
    "command_id": "cmd-example-001",
    "status": "success",
    "result": { "self_test": "passed" }
  }
}

Command · platform publishes, device subscribes

{
  "command_id": "cmd-example-001",
  "device_id": "NX-TW-EXAMPLE-001",
  "timestamp": "2026-08-24T12:03:00Z",
  "expires_at": "2026-08-24T12:13:00Z",
  "type": "SET_CONFIGURATION",
  "payload": {
    "heartbeat_interval_seconds": 60
  }
}

The Go command worker uses command_id, device_id, timestamp, expires_at, type, and payload. Physical command execution is not enabled by the production template until manufacturer capability approval.

Device connection process

1. Register the device. An authorized operator creates the device record using the serial number, model, country, and approved hardware details.
2. Provision the device. The authenticated provisioning endpoint generates the Device ID and unique password and returns a one-time package.
3. Secure the package. Deliver the Device ID, username, and password to the manufacturer through the approved encrypted channel. Never commit or email secrets in plain text.
4. Configure cellular transport. Install the approved SIM/GSM/LTE profile or private APN. The detector should not require household Wi-Fi.
5. Configure MQTT. Set host mqtt.nexxafire.com, port 8883, MQTT 3.1.1, TLS enabled, certificate verification enabled, username equal to Device ID, and the one-time password.
6. Connect and publish a heartbeat. Publish a valid v1 envelope to the device heartbeat topic. Then publish status online if the firmware contract requires an explicit state update.
7. Verify online state. The Nexxa platform validates and persists the envelope, updates the device last-seen state, and displays the resulting state in the authenticated command center.

Manufacturer setup

For each detector, the Taiwan manufacturer needs the following configuration values from the approved provisioning package:

Coordinate physical tests with the Nexxa integration owner and use only an approved test detector.

Testing with Mosquitto

Set placeholders in a protected shell. Use the operating system trust store or the approved public CA certificate; never use --insecure.

export MQTT_HOST=mqtt.nexxafire.com
export MQTT_PORT=8883
export DEVICE_ID=<DEVICE_ID>
export DEVICE_PASSWORD=<DEVICE_PASSWORD>
export CA_CERT_PATH=<CA_CERT_PATH>
export BASE_TOPIC="nexxa/v1/devices/${DEVICE_ID}"
export CLIENT_ID="nexxa-${DEVICE_ID}"

Test TLS and hostname verification

openssl s_client \
  -connect "${MQTT_HOST}:${MQTT_PORT}" \
  -servername "${MQTT_HOST}" \
  -CAfile "${CA_CERT_PATH}" </dev/null

Subscribe to the device command topic

mosquitto_sub \
  -h "${MQTT_HOST}" -p "${MQTT_PORT}" \
  --cafile "${CA_CERT_PATH}" --tls-version tlsv1.2 \
  -i "${CLIENT_ID}-sub" -u "${DEVICE_ID}" -P "${DEVICE_PASSWORD}" \
  -q 1 -t "${BASE_TOPIC}/command"

Publish a heartbeat

mosquitto_pub \
  -h "${MQTT_HOST}" -p "${MQTT_PORT}" \
  --cafile "${CA_CERT_PATH}" --tls-version tlsv1.2 \
  -i "${CLIENT_ID}-heartbeat" -u "${DEVICE_ID}" -P "${DEVICE_PASSWORD}" \
  -q 0 -t "${BASE_TOPIC}/heartbeat" \
  -m '{"device_id":"<DEVICE_ID>","message_id":"<UUID>","timestamp":"2026-08-24T12:00:00Z","type":"heartbeat","payload":{"uptime_seconds":10,"battery_voltage":3.6}}'

Publish telemetry

mosquitto_pub \
  -h "${MQTT_HOST}" -p "${MQTT_PORT}" \
  --cafile "${CA_CERT_PATH}" --tls-version tlsv1.2 \
  -i "${CLIENT_ID}-telemetry" -u "${DEVICE_ID}" -P "${DEVICE_PASSWORD}" \
  -q 1 -t "${BASE_TOPIC}/telemetry" \
  -m '{"device_id":"<DEVICE_ID>","message_id":"<UUID>","timestamp":"2026-08-24T12:00:05Z","type":"telemetry","payload":{"temperature_c":24.5,"smoke_density":0.02,"battery_voltage":3.6,"signal_strength_dbm":-65}}'

Publish a controlled test alarm

mosquitto_pub \
  -h "${MQTT_HOST}" -p "${MQTT_PORT}" \
  --cafile "${CA_CERT_PATH}" --tls-version tlsv1.2 \
  -i "${CLIENT_ID}-alarm-test" -u "${DEVICE_ID}" -P "${DEVICE_PASSWORD}" \
  -q 1 -t "${BASE_TOPIC}/alarm" \
  -m '{"device_id":"<DEVICE_ID>","message_id":"<UUID>","timestamp":"2026-08-24T12:01:00Z","type":"alarm","payload":{"alarm_type":"TEST","severity":"warning","detection_type":"test","confidence":1.0}}'

A valid alarm is processed as an operational event. Use this command only with an approved test detector and test window.

Security requirements

• Never commit passwords, integration secrets, private keys, certificate account keys, or populated production environment files to Git.
• Never copy a real device password into firmware source, tickets, screenshots, browser storage, or this documentation.
• Never use a device credential to access another device's topic namespace.
• Do not expose platform administration, databases, monitoring, or plaintext MQTT to detector networks.

Troubleshooting

Production status

Quick reference

Keep this reference with the approved Nexxa device integration package. Example values are fictional and must be replaced only by the secure provisioning process.