Topics

MQTT topic structure and naming conventions

Overview

The Stream API publishes device data to structured MQTT topics. Each topic follows a consistent naming pattern that includes integration identifiers and data types.

Topic Structure

haltian-iot/events/{integration-id}/{api-key-id}/{event-kind}/{event-type}/{device-id}

Topic Parameters

Parameter	Description
`integration-id`	UUID matching the MQTT subscription integration
`api-key-id`	UUID matching the API key attached to the integration
`event-kind`	One of: `measurements`, `messages`, `notifications`
`event-type`	Specific measurement/message/notification type
`device-id`	UUID of the device (optional for notifications)

Event Kinds

measurements

Device sensor readings and telemetry data.

Example topic:

haltian-iot/events/{integration-id}/{api-key-id}/measurements/ambientTemperature/{device-id}

messages

Binary message content from devices.

Example topic:

haltian-iot/events/{integration-id}/{api-key-id}/messages/rawData/{device-id}

notifications

System alerts and alarms (not device-specific).

Example topic:

haltian-iot/events/{integration-id}/{api-key-id}/notifications/deviceOffline

Supported Measurement Types

Type	Description
`systemTemperature`	Internal device temperature
`ambientTemperature`	Environmental temperature
`batteryVoltage`	Battery voltage levels
`batteryPercentage`	Battery level percentage
`CO2`	Carbon dioxide concentration
`TVOC`	Total Volatile Organic Compounds
`occupancyStatus`	Room/space occupancy status
`occupantsCount`	Number of occupants detected
`position`	Device location data
`distance`	Distance measurements
`directionalMovement`	Entry/exit detection

Topic Wildcards

MQTT supports wildcards for subscribing to multiple topics:

Single-Level Wildcard (+)

Subscribe to a specific measurement type from all devices:

haltian-iot/events/{integration-id}/{api-key-id}/measurements/ambientTemperature/+

Multi-Level Wildcard (#)

Subscribe to all measurements:

haltian-iot/events/{integration-id}/{api-key-id}/measurements/#

Subscribe to all events:

haltian-iot/events/{integration-id}/{api-key-id}/#

Payload Format

All payloads are JSON-formatted:

Temperature Measurement

{
  "value": 23.5,
  "measured_at": "2024-03-07T06:53:46.059000+00:00"
}

Occupancy Status

{
  "value": true,
  "measured_at": "2024-03-07T06:53:46.059000+00:00"
}

Position

{
  "value": {
    "type": "Point",
    "coordinates": [17.5, 35.4]
  },
  "measured_at": "2024-03-07T06:53:46.059000+00:00",
  "space_id": "55a0a3d0-84b6-4ace-b131-0b2420053e91"
}

Access Control

Topic access is controlled by API key configuration:

API key determines the integration-id and api-key-id in topics
Space permissions filter which devices’ data is published
Keyword filters further restrict data based on device keywords

Next Steps

Examples - Code samples for subscribing to topics
Stream API Overview - Complete API documentation