Messages are organized by type and folder, which correspond to the transport aspect of the device (type) and semantic meaning (folder).
Each message has an associated sub block (sometimes called a subFolder) that indicates a semantic scoping of the message or block:
- pointset messages deal with data point telemetry (e.g. temperature reading)
- system messages handle system events such as rebooting, config processing, firmware, etc...
Message types are divided into four high-level categories, which define the direction of message flow, but also the treatment of the message as it moves through the system:
- Directionality: Which direction the messages flow with respect to the device
- Uplink: From the device to cloud, used to collect data from/about devices.
- Downlink: From cloud to the device, used to control devices.
- Treatment: How the message flows through the system and is stored by the transport layers
- Sticky: Rate-limited, and persist in the system. If multiple messages are sent, only the last one is meaningful or maintained (intermediate messages may be proactively dropped by the system). There is only one 'sticky' blob of data for each device, shared my all blocks/folders.
- Stream: Passed through the system with minimal on-the-way handling. If multiple messages are sent, all of them should make it through although any individual message may be lost in transit. Each 'stream' message has its own folder/block associated with it (not shared).
| Uplink | Downlink | |
|---|---|---|
| Sticky | state | config |
| Stream | events | command |
The properties and uses of the four types fall out from this accordingly:
- state: Sticky to the cloud information from the device, including information such as the overall status of the device, and any errors or conditions from, e.g., writing points.
- events: The canonical streaming telemetry messages from the device, usually containing things like temperature readings or system memory utilization.
- config: Ability to control the behavior of a device, e.g. for key rotation, writeback, etc...
- command: Direct but transitory messages to a device, e.g. to install a new auth key or perform diagnostic operations.
Individual blocks (folders), such as system or pointset will have their own semantic uses for the various types. See the individual block folder documentation to learn more about those aspects.
MQTT topics described in tech stack