MV Camera Intelligence - MQTT Protocol and Configuration

Learn about MQTT Protocol, Architecture, MQTT Broker, and configuring MQTT in Meraki Dashboard.

What is MQTT?

MQTT is a Client-Server publish/subscribe messaging transport protocol. It is lightweight, open, simple, and designed to be easy to implement. These characteristics make it ideal for use in constrained environments, such as for communication in machine-to-machine (M2M) and the internet of things (IoT) contexts where a small code footprint is required or network bandwidth is at a premium. The MQTT protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless, bi-directional connections.

Components of MQTT

An MQTT Client is a program or device that establishes a network connection to the Server/Broker to publish application messages that other clients might be interested in or subscribe to request messages that it is interested in receiving. A Server/Broker acts as an intermediary between clients which publish or subscribe as well as process the published.

Topics are labels that you publish messages to and subscribe to. They are arranged as a hierarchy, so you could have sensors/outside/temp and sensors/outside/humidity.

Sample Architecture

Mosquitto – MQTT Broker

Mosquitto is an open source message broker that implements the MQTT protocol. To install a simple Mosquitto Broker on a Raspberry Pi, follow this guide.

Configuring MQTT in the Dashboard

1. Start by navigating to Cameras > Monitor > Cameras and selecting the camera you would like to enable MV Sense on.
2. Once the camera is selected, go to Settings > Sense.
3. Click Enabled.*
4. To enable MQTT on your camera and create a new MQTT broker configuration click Add or edit MQTT Brokers.

• If this is your organization’s first time using MV Sense, you will have 10 free perpetual licenses available to use. If you have exceeded this 10 free licence count, you must activate more licenses by navigating to Organization > Configure >License info and claiming more licenses.

Enter the following information for your broker:

1. Broker Name – Name for the broker.
2. Host – This could be an IP address or hostname.
3. Port – TCP port number for MQTT. Most commonly used ports are 1883 for TCP and 8883 for TLS.
4. Security – Enable or disable TLS. When enabling TLS, upload a CA signed cert for the broker and choose hostname verification.
5. Optionally, test the connection between the camera and the broker to ensure communication.

MQTT Messages

Once your MQTT broker is set up and enabled on your camera, you can start subscribing to the following topics. These topics and their messages are published by your camera to the broker when configured (XXXX-XXXX-XXXX is the S/N of the camera):

Current live count of people or vehicles within the cameras view

topic: /merakimv/XXXX-XXXX-XXXX/0

{
     "ts":1714632612326, 
     "counts":
     {
          "vehicle":0, 
          "person":0
     }
}

Response Parameters

Raw Detections, a list containing object identifiers (oids) and their x, y coordinates

topic: /merakimv/XXXX-XXXX-XXXX/raw_detections

{
    "objects" : 
    [
        {
            "confidence" : 71,
            "frame" : 1752377,
            "oid" : 1018,
            "subtype" : "",
            "type" : "person",
            "x0" : 0.872,
            "x1" : 0.738,
            "y0" : 1.0,
            "y1" : 0.629
        }
    ],
    "ts" : 1714632793422
}

Response Parameters

Here's a visualization of the data from these raw detections.

With this information, you can assess the directionality of objects detected in your space.

Areas and Lines

Line Crossing Events

topic: /merakimv/XXXX-XXXX-XXXX/crossing/BOUNDARY-ID

{
    "_v" : 1,
    "event" : "crossing_out",
    "label" : "Entering ParkLabs",
    "object_id" : 41324,
    "ts" : 1714621457000,
    "type" : "person"
}

This topic will be published to every time a crossing event happens.

Response Parameters

To get your line ID, send a GET request using MV CI RESTful API.
GET Camera Line Boundaries by Device

NOTE: The edge of an area is also classed as a line crossing boundary.

Area Occupancy Events

topic: /merakimv/XXXX-XXXX-XXXX/occupancy/BOUNDARY-ID

{
    "_v" : 1,
    "label" : "Tables New",
    "objects" : 
    [
        {
            "object_id" : 3241,
            "ts_appeared" : 0,
            "ts_entered" : 1714663917457,
            "ts_exited" : 1714663917324,
            "ts_expired" : 0,
            "type" : "person"
        }
    ],
    "ts" : 1714663920000
}

This topic will be published to every 60 seconds with a summary of the previous 60 seconds, if activity is observed within that time period.

Response Parameters

To get your Boundary ID, send a GET request using MV CI RESTful API.
GET Camera Area Boundaries ID by Device

NOTE: If an object has never been tracked appearing/disappearing/entering/exiting the opposite values will be 0. In the data example attached, the object was only tracked going into and out of the zone, therefore the expired and appeared values are 0, as they have never been observed.

Lux light levels

topic: /merakimv/XXXX-XXXX-XXXX/light

{
     "lux": 44.198
}

Response Parameters

Custom CV

Custom Analytics

NOTE: If Custom CV is enabled on a camera, ONLY the below topic will be published. All other topics will be disabled

topic: /merakimv/XXXX-XXXX-XXXX/custom_analytics

{
    "outputs": [
        {
            "class": 46,
            "id": 8227,
            "location": [
                0.132,
                0.48,
                0.391,
                0.823
            ],
            "score": 0.699
        }
    ],
    "timestamp": 1714667995929
}

Response Parameters

[DEPRECATED] Zones

NOTE: Zones are now deprecated and replaced by the area and line topics above.

Number of object entrances in a specific zone*

topic: /merakimv/XXXX-XXXX-XXXX/{zoneId}

{
     "ts":1541699602570,
     "counts":{
          "person":1
     }
}

Response Parameters

To get your zone’s ID, send a GET request using MV Sense’s RESTful API.

Get Device Camera Analytics Zones

[DEPRECATED] MQTT Messages - Desk Occupancy

Note - This is now deprecated.

Once your MQTT broker is set up and enabled on your camera, you can start subscribing to the following topics. These topics and their messages are published by your camera to the broker when configured (XXXX-XXXX-XXXX is the S/N of the camera):

Coordinates of occupying heads and desks detected - V2

topic: /merakimv/XXXX-XXXX-XXXX/net.meraki.detector

{
     "_v": 2,
     "time": "2021-03-29 20:41:00",
     "coords": [[122, 563, 1.0], [322, 411, 1.0]],
     "desks": [[12, 200, 34, 201, 181, 203, 1.0], ...]
}

For v2 the coordinates expressed in the output are pixel coordinates based from the top left part of the view and in fisheye space.

Response Parameters

lx, ly is the pixel position of the left desk edge; rx, ry is the right position of the desk edge. cx, cy is the center position of the desk edge. The last element, o, is an integer depicting occupancy; 0→free, 1→ occupied.

Coordinates of occupying heads and desks detected - V3

topic: /merakimv/XXXX-XXXX-XXXX/net.meraki.detector

{
     "_v": 3,
     "ts": 1286748610000,
     "heads": [[0.664, 0.443, 1.0], [0.251, 0.337, 1.0]],
     "desks": [[0.017, 0.278, 0.047, 0.279, 0.251, 0.281, 1.0], ...]
}

For v3 the coordinates expressed relative to the top left corner of the image, scaled in the range of 0.000 to 0.999 in fisheye space.

Response Parameters

lx, ly is the pixel position of the left desk edge; rx, ry is the right position of the desk edge. cx, cy is the center position of the desk edge. The last element, o, is an integer depicting occupancy; 0→free, 1→ occupied.

Note - The current format for presence is entering deprecation and is subject to change in an upcoming update, for the time being make sure to support both the current v1 and upcoming v2 versions!

Presence message - V1

topic: /merakimv/XXXX-XXXX-XXXX/net.meraki.presence

{
     "_v": 1,
     "status": "offline",
     "timestamp": "2021-03-29 20:41:00"
}

Response Parameters

Presence message - V2

topic: /merakimv/XXXX-XXXX-XXXX/net.meraki.presence

{
     "_v": 2,
     "status": "offline",
     "timestamp": 1286748610000
}

Response Parameters