Topic Structure

This article aims to explain the expected topic structure for data sent/received via the MQTT service. The topic structure is designed to be hierarchical, allowing for easy organization and filtering of messages.

Devices & Hubs

The devices topic is used to subscribe to data from devices and hubs. This data could be used to monitor the status of devices such as traffic lights, terminals, and weighbridges/scales.

The topic structure for the devices and hubs topic is as follows:

mqtt.centrix.world
    <application_id>
        devices
            <device_id>
                <item> = VALUE
                <item> = VALUE
                $[...] = VALUE
            <device_id>
                <item> = VALUE
                <item> = VALUE
                $[...] = VALUE
        hubs
            <hub_id>
                status = VALUE
            <hub_id>
                status = VALUE

Devices

For devices each <device_id> is displayed as a separate topic, then each <item> is displayed as another topic under the <device_id>.

This way you can subscribe to all events via the <application_id>/devices/# topic, a specific device via the <application_id>/devices/<device_id> topic, and/or a specific item via the <application_id>/devices/<device_id>/<item> topic.

Each <device_id> topic will contain a number of <item> topics, each of which will have a value representing the current value of the device item. The names of <item> topics are specified during development of the Centrix application, and may be different for each application. The value of each <item> topic can be any data type (string, number, boolean, JSON object, JSON array).

mqtt.centrix.world
    6a73249d1821a8343deef8ad
        devices
            65c0a84b374a54e06b709bb3
                A.weight = 12680
                A.stable = true
                A.belowMin = false
                A.response = { ... }
                $timestamp = 2024-03-01T12:09:03.7819875Z
                $outbound = ""

Items such as A.weight above are specified by the developer of the application you are subscribing to. These keys will be specific to the application, device, and/or device type.

For more information about the items available in your application, please contact your authorized reseller.

System Topics

All keys beginning with a $ are reserved for system values, some of the system topics are as follows:

Key	Description
$timestamp	An ISO date string representing the date and time of the last message/connection.
$raw	The raw data injested by the hub/gateway the device communicates with.
$native	Any values that can be derived from a device driver or native protocol.
$outbound	Used for publishing messages to the device.

Hubs

The value received in the status topic is a JSON object. The object details diagnostic information about the hub, such as current CPU and memory usage, as well as a timestamp of the last message/connection.

mqtt.centrix.world
    6a73249d1821a8343deef8ad
        hubs
            646fc6a5ff1eab23b82fb87a4
                status = {"cup":{ ... },"$timestamp":"2024-03-01T08:26:23.2654245Z"}

note

This is typically used for diagnostic purposes, and is not intended to be used by 3rd-party integrations or applications. Due to this, the exact structure of the JSON object is not documented here.

Documents

The documents topic is used to subscribe to data indicating what changes have been made via our user interface or API, to a collection within the application you are subscribed to.

The events emitted by the platform are:

Event Type	Description
insert	Indicates that a new document has been added to a collection.
update	Indicates that a partial update of a document has taken place in a collection.
replace	Indicates that a full document replacement has taken place in a collection.
delete	Indicates that a document has been deleted from a collection.

The topic structure for the documents topic is as follows:

mqtt.centrix.world
    6a73249d1821a8343deef8ad
        documents
            653900c0afa5a498e4c5c738 = VALUE
            647955c1bfa7c457f5c5c711 = VALUE

Under documents, each event emitted by the platform is seperated by <collection_id>. This allows you to subscribe to all events via the <application_id>/documents/# topic, a specific collection via the <application_id>/documents/<collection_id> topic.

note

It is not possible to subscribe to a specific event type.

Document Event Structure

The value received in the topic is a JSON object, which has the following structure:

Key	Description
action	The event emitted by the platfom (insert, update, replace, delete ).
applicationId	The ID of the applcication which was effected by the event.
collectionId	The ID Of the collection which was effected by the event.
principal	The ID related to the access token used by the client causing the event.
document._id	The ID of the document that was modified.
document._hash	A unique identifier for the document, which can be used to check if the document has changed since it was last retrieved.

Using the applicationId, collectionId, and document._id values, a request can then be made to the API to retrieve the changed document data. Retreival of the document may not be possible if a delete event has been emitted.

{
    "action": "<event>",
    "applicationId": "<application_id>",
    "collectionId": "<collection_id>",
    "principal": "<access_principal>",
    "document": {
        "_id": "<document_id>",
        "_hash": "<document_hash>"
    }
}

You can then make a request to the following URL:

https://api.centrix.world/<application_id>/collections/<collection_id>/documents/<document_id>

tip

See our API documentation for more information on the Get Document endpoint.