Introduction

This quick guide discusses the MQTT functionality available on Irisys Vector devices, and how to configure it.

This section should be used in conjunction with the MQTT Programming Section which describes the output file format.

MQTT is just one of the many different methods of retrieving count data from a Vector device. It works by pushing out selected data ‘topics’ whenever new data is available. This means that as soon as there is a change, data is received within a few seconds. MQTT data is accessed via an MQTT ‘broker’ which is a kind of middleman for moving the MQTT JSON messages around.

Note that some features of the MQTT function are only available on Vector Analytics. See relevant topic below for more details.
Note: the use of MQTT, assumes, and requires, a working knowledge of the publish/subscribe model, topics, and the configuration of your own choice of MQTT broker.
Note: This section refers to Vector firmware 2.0.165 and above. See the Vector firmware section of any updates required.
In order to access these settings, you must first make an initial connection to the Vector unit; see separate guide: Irisys Vector 4D - Making a Setup Connection

 

MQTT Configuration

Once you are connected to the Vector, the MQTT settings are accessed via the ‘Settings’ tab, then ‘MQTT’. Click the ‘Add’ button to enter new MQTT Broker details:

If connected to a Vector via an Estate Manager connection, make sure you select the ‘Live View’ option to make changes

There can be multiple MQTT broker settings configured, each either pointing to different brokers and/or sending different data topics, as required. For example, you could send the ‘Counts’ data topic to a server at head office, and ‘Live Count’ data to an on-site Occupancy Reporting system.

The Field meanings are as follows (Note also the short help descriptions for each field displayed on the right of the MQTT tab):

  • Address: This is the IP address or hostname of the MQTT broker. If using a hostname, ensure that the Vector’s ‘IP Settings’ tab is configured with valid and accessible DNS server(s).
  • Port: MQTT is on port 1883 by default (with port 8883 being typically used for secure connections over TLS), but any valid port can be set here, as required.
  • Keep Alive (seconds): This configuration option dictates how regularly the device sends a keep alive message to the broker. This is part of the MQTT protocol.
  • Max History (hours): In the event that the device cannot communicate with the broker, it will retain any messages not yet sent. To limit storage requirements, any messages exceeding the max history will be discarded.
  • Max Size (bytes): This option limits the amount of the data that the device can send to the MQTT broker in a single transmission. Any data not sent in a transmission due to this limit will be retained in the history and will be the priority for sending in the next transmission. Irisys recommend that the limit is set to no more than 256Kb, with a much lower value preferred.
  • Credentials: Enable credentials if your broker requires a Username and password.
  • TLS: Transport Layer Security. Enable if required for your MQTT Broker, and choose the certificate to use from the dropdown. Additional TLS Certificates can be uploaded to the device on the ‘Security’ tab if required.

  • Register Filter: To minimise the amount of data being sent each time, it is recommended to select only the required register values. For example (from a device configured to be a SafeCount unit):

When configuring MQTT settings ensure that the Max History and Max size settings are balanced so that enough data is store temporarily in order to cope with any network outage, and also older stored data will be sent in a timely manner when the network is restored.
If the Max History setting is too large there will be lots of old data stored during a network outage which will take some time to catch up with when the network is fixed. If it is too small you will see small periods of missing data that is lost during network outages.
If the Max Size is too large it will attempt to send large amounts of data which will be more likely to fail. If it is too small, any temporarily stored data during network outages will take a long time to send and catch up to the live data sending.
If it is anticipated that there could be network outages greater than 24 hrs, then it could be argued that data from 'yesterday' does not need to be sent via MQTT - a real time data sending method. Instead, it is recommended that data from previous day(s) is pulled via the REST API from the logged count records on device rather than extending the MQTT Max History setting.

 

Topics

  • Counts: Sends all/selected current register values at a configurable interval period (in seconds).
  • Status: Sends connection and disconnection events.
  • Targets: Sends live target X & Y positional data over this topic - streamed at 15 frames per second. This is a Vector Analytic Only feature.
  • Live Counts: Sends all/selected current register values whenever there is any change.
Remember that any timing-based registers (e.g. ‘Wait Time’) will generate constant and consistent MQTT messages. Using the Register Filter is recommended to prevent in these cases.
  • Device Info: Sends various device settings and parameters sent on connection and change, e.g. IP address, MAC address, Product ID, Sitename, etc.
  • Events: A stream of information about each individual targets movements across lines and in and out of zones etc. Extremely useful for "Customer Journey" type applications where multiple Vectors are covering a large area containing different products/stands/demos etc. This is a Vector Analytic Only feature. The following options are available under the Events stream topic:

Each Event Type will result in an MQTT message containing the ID of the target, the height of the target and details of the event type itself. See descriptions below.

Event type descriptions are:

Target Birth - this is when a target first appears (initializes) within the whole field of view.

Target Death - this is when a target disappears (leaves the field of view).

Line Count - this is a line increment event. Note due to the configurable count mode associated with each line, this may not correspond to the actual line crossing. I.e. the Deferred count mode only increments when a target leaves the field of view.

Line Forward Crossing - a target crossing a line in the configured direction. This is an immediate output message and can therefore be different to the Line Count message above, dependent on register settings.

Line Reverse Crossing - a target crossing a line in the opposite direction to the configured direction.

Polygon Birth - a target appearing (initializing) within a configured zone.

Polygon Enter - a target entering a configured zone.

Polygon Exit - a target leaves a configured zone.

Polygon Death - a target disappears when inside a configured zone. 

In reality, when an installation comprises of only line registers, the required minimum Event filters are 'Target birth', 'Target death', and 'Line Count'. This will provide the standard target appearing and disappearing, and line count increments to be provided for each tracked target.
If a person is first seen (initialised) as a target within a Polygon (zone), you should expect both a Target Birth and Polygon Birth message. Similarly, with targets dying within a polygon. 

 

Retain State

To help prevent extra costs/processing of MQTT messages, the Retain State can be disabled if required:

Disabling of the Retain state is probably required when using AWS IoT Core as your MQTT broker.

 

QoS

Each topic has a Quality of Service (QoS) value that can be altered if required:

  • 0 – Best effort delivery with no guarantee. Often referred to as “fire and forget”. Effectively provides the same guarantee as the underlying TCP protocol. I.e. minimum quality.
  • 1 – Guarantees delivery at least one time to the receiver. Messages could be sent/delivered more than once.
  • 2 – Highest level of service. Guarantees that each receiver gets the message exactly once. Safest but slowest level.
It should be noted that if you are using AWS, this does not support QoS 2.
For details of how to use the data from the MQTT broker see here.