Technical Documentation
Version 2022.3

Raw event data with Custom MQTT server

Getting started with your custom MQTT connection
As soon as you have configured your use case in the Swarm Control Center, the SWARM software generates events. These events are transferred as standard JSON.
In case you don't want to use Data Analytics and retrieve data via SWARM API, we provide you the option to configure a custom MQTT broker.

Custom MQTT broker

The Swarm Perception Box will send events in the form of a JSON to an MQTT broker you configure. The QoS level 1 is used to deliver events. In case events cannot be delivered, e.g. no connectivity, we cache events up to 24k messages.
For higher security, you can use MQTT over SSL. Simply add ssl:// prefix to the broker configuration.

Message compression

In case that message compression is configured the events are compressed with zlib / inflate .

Swarm Event Scheme

There are several ways how to validate a JSON against a schema, a good overview is provided by As a starting point, we recommend, an online tool to manually validate a JSON against our schema.
The header of the JSON is defined by a version of the format being used (property version). The format is major.minor, a major version change denotes a breaking change whereas a minor version change indicates backward compatibility. For unique identifiers, we rely on UUID. Timestamps are defined with ISO8601.

Counting Line Event

A counting line event is triggered if an object crosses a virtual line (identified by the property lineId). The line has a user-defined name (property lineName). A timestamp (property timestamp) is set when the event occurred. The object can cross the line in two directions (property direction) and is either moving in or out. Additionally, the object which crosses the line is classified (property class & sublcass). The classes are dependent on the use case.
In case ANPR feature is enabled, the license plate (property plateNumber) and the license plate country (property numberPlateOrigin) will be added to the event.
With ANPR there are captures of the license plate at entries and exits taken. The License plate capture can be attached in jpg format to the MQTT message encoded with BASE64.
Please contact our support to enable the addition of license plate captures via MQTT.
If speed estimation is enabled and configured the speed estimate (property speedestimate) will gove the speed estimate output in km/h.

Region of Interest Event

The Region of Interest Event depends on the type of the Region of Interest. Region of Interest with RoI type Parking will generate a ParkingEvent and the RoI type Generic will generate a RegionOfInterestEvent

Parking Event

A parking event is triggered by a time interval every 10 seconds. The information of all the configured Parking RoI will be aggregated in one single event. In parkingSummary all the RoI will be listed with the configured capacity and the current count of vehicles in the RoI.
As a total summary, you will have the totalCapacity and the totalVehicles which are giving a complete overview of all configured Parking RoI in this camera stream.
As an Early Availability feature, you can enable ANPR for Parking RoI. This will provide the license plate (property plateNumber) and the license plate country (property numberPlateOrigin) in a string format.

Region of Interest Event

A region of interest event is triggered either by a state change or by a time interval (property triggerType). The state (property state) can change from occupied to vacant or vice-versa. It is occupied in case the number of objects in the RoI is at least as high as the configured capacity.
Every event contains a user-defined name (property roiName) and a timestamp (property timestamp) when the event occurred. Detected objects and their associated class and dwell times are listed (property objects). The classes are dependent on the use case.

Rule Event

In case a rule is created on an event trigger, a rule event is sent. The rule event is triggered based on the chosen event trigger logic in combination with the defined conditions. A timestamp (property timestamp) is set when the event occurred. The rule event includes the generic information around the rule name, device and stream UUID. On top of the event information, the chosen standard event information is part of the message in the same format as for the standard messages of the chosen event triggers.

Raw track Event (Heatmap)

Raw track mode traces objects as they move through the field of view. A complete trace, of the route that the object took, is generated as soon as the object exits the field of view.
This trace includes the classification of the object (property class) and the path of the object throughout the field of view. The class is dependent on the particular use case.
The track is described as a series of path elements, which include a timestamp and the top-left coordinates along with width and height of the tracked object. There are a maximum of 10 path elements in every event.
Breakdown of Object related attributes:

Classes in the Swarm Event Scheme

Every event does contain a class of the detected object. We arranged those objects in classes and subclasses for a better overview. You can see the classes and Subclasses as well as examples in the section "Object Classes detected by SWARM".
Example Counting Line detecting a Van. Note that the class is "car" and the subclass is "van".

Last modified 1mo ago