Skip to main content
Version: DeepHub 2024 R2 - 2.6.0

MQTT Topics

Overview​

MQTT allows for decentralized communication between devices, services and the DeepHub. This fulfills common requirements in the IoT context, such as low energy consumption and high scalability. To configure the DeepHub to connect to an MQTT broker, see the MQTT configuration.

Below, the first two sections describe the omlox™ MQTT extension and the corresponding topics. The third section documents DeepHub-specific topics for object change events, and last, but not least, the final section explains how the DeepHub can be used in the context of a Unified Namespace.

The omlox™ MQTT Extension​

The MQTT Extension is an optional omlox™ v2 component. In principle it works similar to the WebSocket publish / subcribe mechanism. There are two main modes of operation, distinguished by the source of the location information:

  • Process and (re-)publish location_updates and proximity_updates received via MQTT
  • Process and publish location_updates and proximity_updates received via any other means than MQTT, i.e. location information received via the REST- or WebSocket-API

In both cases, the processed location information is published to the configured MQTT broker and can be consumed there. Due to the nature of an MQTT architecture, sender and receiver of data are not aware of each other and therefore it is especially not possible for the publisher of location information to know, in which projection a potential consumer wants the location information to be. Publishing location information in all known projections, on the other hand, would have a significant performance impact. Therefore an omlox™ hub publishes location information only in the most relevant formats and these are local coordinates and WGS84 coordinates.

Another notable difference between consuming location information and events via MQTT in contrast to the WebSocket API, is the filtering options that e.g. allow to filter trackable_motion events via a specific provider_id which are not available in MQTT.

Topics of the omlox™ MQTT Extension​

location_updates​

This topic handles location updates of location providers. The updates are separated between updates that have already been processed by the DeepHub, and updates that still need to be processed.

Unprocessed location updates are sent to the broker via the following topic: omlox/json/location_updates/pub/{provider_id}.

Processed location updates can be retrieved via omlox/json/location_updates/local/{provider_id} for updates that are in local coordinates of the zone referenced by the location and omlox/json/location_updates/epsg4326/{provider_id} for updates in geographic (WGS 84) coordinates.

The format is JSON and the data object is an omlox™ Location object.

proximity_updates​

The proximity_updates topic handles updates from proximity locating systems.

Similar to the location_updates topic, unprocessed omlox™ Proximity objects are sent to the following topic: omlox/json/proximity_updates/{source}/{provider_id}. Processed proximity updates result in concrete locations and are therefore sent to the location_updates topic.

trackable_motions​

This topic informs subscribers about movements of an omlox™ Trackable. Trackable Motion updates can be retrieved via omlox/json/trackable_motions/local/{trackable_id} for updates in local coordinates of the zone referenced by the location of the trackable motion and omlox/json/trackable_motions/epsg4326/{trackable_id} for updates in geographic (WGS 84) coordinates.

The format is JSON and the data object is an omlox™ TrackableMotion object.

fence_events​

This topic is used to inform subscribers about geofence entry and exit events. The DeepHub checks location providers and trackables for fence events and sends appropriate events to the general topic based on the fence's id, and the corresponding subtopic(s) for trackables or providers for each fence entry and exit event. These are the topics, respectively:

  • omlox/json/fence_events/{fence_id}
  • omlox/json/fence_events/trackables/{trackable_id}
  • omlox/json/fence_events/providers/{provider_id}

The format is JSON and the data object is an omlox™ FenceEvent object.

collision_events​

This topic is used to retrieve real-time collision events. The DeepHub checks trackable movements for collisions and publishes collision events to omlox/json/collision_events/epsg4326/{trackable_id} when trackables start to collide, continue to collide, and end a collision.

The format is JSON and the data object is an omlox™ CollisionEvent object.

Topics for Object Change Events​

These topics inform subscribers about object changes based on the specified type (fence_changes, trackable_changes, provider_changes, zone_changes, anchor_changes). Object changes are published in the corresponding subtopic (create, update, delete).

These events contain a event_type field that specifies whether the change event is of type create, update, or delete. For create and update events, the object field specifies the new (updated) version of the object. Furthermore, they include a timestamp field that contains the timestamp the DeepHub associates with the event.

Example​

Here is an example for a fence update event. To receive data for a fence with id 5b67733b-194d-4dec-a644-411fc8cf0ecf, the application has to be subscribed to the fence_changes topic. For example: flowcate/json/fence_changes/update/5b67733b-194d-4dec-a644-411fc8cf0ecf.

An example JSON object of the fence update could look like this:

{
    "timestamp":"2024-11-04T12:15:45.523Z",
    "event_type":"update",
    "object":
    {
        "id":"5b67733b-194d-4dec-a644-411fc8cf0ecf",
        "radius":5,
        "region":
        {
            "type":"Point",
            "coordinates":[7.0,48.0]
        },
        "crs":"EPSG:4326",
        "elevation_ref":"floor"
    }
}

Unified Namespace​

A Unified Namespace brings data from different sources together to ensure a single source of truth. A typical format for the topics would be something like enterprise/site/area/line/machine. The root namespace, e.g. the enterprise/site/area part, can be configured via the configuration variable uns_root. The asset specific part of the namespace, e.g. line/machine, can be configured inside the trackable's properties field using the property com.flowcate.uns. The DeepHub publishes a JSON object containing WGS 84 coordinates (lon, lat) to the subtopic /sensor/wgs84 of the configured namespace.