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.weightron.cloud
    <application_id>
        devices
            <device_id> = VALUE
            <device_id> = VALUE
        hubs
            <hub_id> = VALUE
            <hub_id> = VALUE

Under devices and hubs, each deviceId or hubId connected will be displayed as a speerate topic under the respective section. You can subscribe to all events via the <application_id>/devices/# (or <application_id>/hubs/#) topic, or a specific device via the <application_id>/devices/<device_id> (or <application_id>/hubs/<hub_id>) topic.

Devices

Each deviceId listed has a value representing the current status/values of the device. The value received in the topic is a JSON object, which has the following structure. All keys beginning with a $ are reserved for system values.

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 this device communicates with.
$native	Any values that can be

note

The additionalKeys key below represents any additional values that are specified by the developer of the application you are subscribing to. These keys will be specific to the application and device, and will not be documented here. The value of additional keys can be any type (string, number, boolean, object, array).

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

{
    "$timestamp": "<ISO_date>",
    "$raw": {
        // Raw data from the device
    },
    "$native": {
        // Native data from the device
    },
    "additionalKeys": "<value>"
}

Hubs

The value received in the 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.

note

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

Processes

note

This documentation is still under construction and is not yet fully supported.

Documents

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

The events emitted by the platform are:

Event	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.weightron.cloud
    <application_id>
        documents
            <collection_id> = VALUE
            <collection_id> = 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, or a specific collection via the <application_id>/documents/<collection_id> topic.

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

Key	Description
action	The event emitted by the platfom.
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.

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

Using the highlighted values above 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.

The request would be made to the following URL:

https://api.weightron.cloud/<application_id>/collections/<collection_id>/documents/<document_id>

tip

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