How do I create events and gather them?

As soon as you configured a solution (What are Solutions and how do I use them? & How do I build my own Solution?) the Perception Box will generate events. Those events are formated as standard JSON and will be sent to a MQTT broker. The content of the event depends on the solution you definded.

Swarm Event Scheme

There are several ways how to validate a JSON against a schema, a good overview is provided by json-schema.org. As a starting point, we recommend jsonschemalint.com, 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.

Crossing Line Event

A crossing 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 by two directions (property direction) and is either moving in or out. Additionally, the object which crosses the line is classified (property class). The classes are dependent on the use case.

{
"crossingLineEvent":{
"class":"person",
"direction":"in",
"lineId":"test_id",
"lineName":"office",
"timestamp":"2019-12-29T10:31:14.373202Z"
},
"node":{
"id":"test",
"name":"test"
},
"version":"1.5",
"eventSchema": "https://swarm-analytics.com/schema/event/1.6",
}

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. A time interval can be set by the user to an arbitrary amount of seconds, e.g. if a timer is set to 60 seconds, every minute an event will be fired which contains the current state of the region of interest.

Every event contains a user-defined name (property roiName) and a timestamp (property timestamp) when the event occurred. Detected objects and their associated class are listed (property objects). The classes are dependent on the use case.

{
"node": {
"id": "test",
"name": "test"
},
"regionOfInterestEvent": {
"objects": [
{
"class": "person"
}
],
"roiId": "69031920-6239-471e-a3d7-f241b7753fd0",
"roiName": "R1",
"state": "occupied",
"timestamp": "2020-01-02T14:59:27.85136Z",
"triggerType": "time"
},
"version":"1.6",
"eventSchema": "https://swarm-analytics.com/schema/event/1.6",
}

Heatmap Event

Heatmap 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 a timestamp and the top-left coordinates along with width and height of the tracked object.

Breakdown of Object related attributes:

​ {
"heatmapEvent":{
"class":"car",
"trackId": 23,
"path":[
{
"h":554.192138671875,
"timestamp":"2019-12-29T10:31:14.373202Z",
"w":766.527587890625,
"x":0.0,
"y":525.807861328125
},
{
"h":757.237060546875,
"timestamp":"2019-12-29T10:31:14.373202Z",
"w":1013.7042236328125,
"x":137.61514282226563,
"y":161.38143920898438
},
{
"h":757.2371215820313,
"timestamp":"2019-12-29T10:31:14.373202Z",
"w":789.4736938476563,
"x":249.7304229736328,
"y":108.07360076904297
},
{
"h":757.2371215820313,
"timestamp":"2019-12-29T10:31:14.373202Z",
"w":1013.704345703125,
"x":149.989990234375,
"y":157.8472137451172
},
{
"h":757.237060546875,
"timestamp":"2019-12-29T10:31:14.373202Z",
"w":789.4736938476563,
"x":184.40171813964844,
"y":161.38143920898438
},
{
"h":757.2371215820313,
"timestamp":"2019-12-29T10:31:14.373202Z",
"w":1013.7042236328125,
"x":131.88348388671875,
"y":157.8472137451172
},
{
"h":757.2371215820313,
"timestamp":"2019-12-29T10:31:14.373202Z",
"w":1013.7042236328125,
"x":131.88348388671875,
"y":157.8472137451172
}
]
},
"node":{
"id":"test",
"name":"test"
},
"version":"1.6",
"eventSchema": "https://swarm-analytics.com/schema/event/1.6",
}

Send data to a MQTT broker

To gather the data, formated as JSON, the Swarm Perception Box will send it to a MQTT broker you configured: How does the configuration work?

For higher security you can use MQTT over SSL. Simply add ssl:// prefix to the broker configuration.

You can use http://www.mqtt-dashboard.com/ for a simple test output. Note that this broker is a public broker and your events could be seen by others as well. Also this service is independed from Swarm Analytics.