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

response

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

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.

alt_text

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

Start by navigating to Cameras > Monitor > Cameras and selecting the camera you would like to enable MV Sense on.
Once the camera is selected, go to Settings > Sense.
Click Enabled.*
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:

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

alt_text

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

Response Parameters

Parameter	Description
ts	Current time in milleseconds since epoch.
counts	Returned JSON indicating the number of people or vehicles counted in the entire field of view. Response will say either "person" or "vehicle" and will be separate messages for each type.

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

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

Response Parameters

Parameter	Description
ts	Current time in epoch milliseconds since epoch
frame	Unique identifier for the frame.
oid	Unique identifier for the person detected.
confidence	The confidence of the model that it's detection is what it thinks it is.
x0, y0	The x, y coordinates corresponding to the top-left corner of the object detection box. They are proportional distances from the upper-left of the image.
x1, y1	The x, y coordinates corresponding to the bottom-right corner of the person detection box. They are proportional distances from the upper-left of the image.
type	Object type.
subtype	Object subtype. E.g. Car within the Vehicle Type

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

alt_text

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

alt_text

Areas and Lines

Line Crossing Events

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

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

Response Parameters

Parameter	Description
ts	Current time in milleseconds since epoch.
_v	MQTT Version
event	What type of crossing it was. Possible values: crossing_in, crossing_out
label	Dashboard friendly name of the line
object_id	The ID of the object detected on this camera which crossed the line
type	The type of detected object which crossed the line. Possible values: vehicle, person

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

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

Parameter	Description
ts	Current time in milleseconds since epoch.
_v	MQTT Version
label	Dashboard friendly name of the area
object_id	The ID of the object detected on this camera which crossed the line
type	The type of detected object which crossed the line. Possible values: vehicle, person
ts_entered	The time which the detected object with the mentioned object_id most recently crossed the threshold of the edge of the area boundary into the area.
ts_exited	The time which the detected object with the mentioned object_id most recently crossed the threshold of the edge of the area boundary exiting/out of the area.
ts_appeared	The time the detected object most recently appeared within the area, if the object was not tracked as crossing into the area over the boundary line.
ts_expired	The time the detected object most recently disappeared from within the area, if the object was not tracked as crossing out of the area over the boundary line.

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

Response Parameters

Parameter	Description
lux	A numerical value with units lux, which measures luminous flux per unit area in the camera’s field of view.

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

Response Parameters

Parameter	Description
timestamp	Current time in milleseconds since epoch.
class	The class of the detected object based on the running model.
id	The ID of the object detected on this camera which crossed the line
location	The co-ordinates of the bounding box based on the width and height of the frame following the x0, y0, x1, y1 structure
score	The confidence score that the detected object is the identified class.

[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}

Response Parameters

Parameter	Description
ts	Current time in milleseconds since epoch.
counts	Returned JSON indicating the number of people or vehicles counted in the specified zone. Response will say either "person" or "vehicle" and will be separate messages for each type.

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.

Coordinates of occupying heads and desks detected - V2

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

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

Parameter	Description
_v	Configured MQTT API version for camera
time	Current time expressed as YYYY-MM-DD hh:mm:ss and in UTC
coords	Describes all detected persons' heads. Each element expresses one detection and the format is: [x, y, a]
desks	Describes all detected desks. Each element expresses one detection and the format of each detection is: [lx, ly, cx, cy, rx, ry, o]

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

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

Parameter	Description
_v	Configured MQTT API version for camera
ts	Current time in milleseconds since epoch
heads	Describes all detected persons' heads. Each element expresses one detection and the format is: [x, y, a]
desks	Describes all detected desks. Each element expresses one detection and the format of each detection is: [lx, ly, cx, cy, rx, ry, o]

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

Response Parameters

Parameter	Description
_v	Configured MQTT API version for camera
status	Current status of device. Can be either "online" or "offline"
timestamp	Current time expressed as YYYY-MM-DD hh:mm:ss and in UTC

Presence message - V2

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

Response Parameters

Parameter	Description
_v	Configured MQTT API version for camera
status	Current status of device. Can be either "online" or "offline"
timestamp	Current time in milleseconds since epoch