MV Sense – Camera Intelligence APIs
- MV Sense Camera APIs
- What is MQTT?
- Components of MQTT
- Mosquitto – Open Source MQTT Broker
- Dashboard Configuration for Sense
- Sample MQTT Message from MVs
- REST API
MV Sense Camera APIs
MV Sense is designed to allow our customers to truly integrate the edge-computing capabilities of Meraki Smart Cameras into business solutions while keeping in-line with Meraki simplicity. Through the API endpoints of MV Sense, the ML/CV data from the cameras can provide organizations with high-value data and insights without additional infrastructure requirements. It offers both historical data and real-time information with MQTT and REST API endpoints.
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 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 to subscribe to request messages that the client is interested in receiving.
- An MQTT Server/Broker acts as an intermediary between clients that publish or subscribe. It also processes the published application messages.
- Topics are labels that you publish messages to and subscribe to. Topics are arranged in a hierarchy path, so if you wanted to specify different outdoor sensor types, you might have the two topics: sensors/outside/temp and sensors/outside/humidity. Clients that publish messages to the sensors/outside/temp topic (such as a client that is measuring temperature), will send their messages to a broker (usually a server). The broker will send those messages to clients that subscribe to the sensors/outside/temp topic (such as a client that activates a process when a certain temperature threshold is reported).
Mosquitto – Open Source MQTT Broker
Mosquitto is an open source message broker that implements the MQTT protocol. Installed on a server, it can serve as your MQTT broker. To install Mosquitto, log in with your non-root user and install Mosquitto with apt-get.
sudo apt-get install mosquitto mosquitto-clients
Testing Mosquitto
Log in to your server a second time, so you have two terminals side-by-side. In the new terminal, use mosquitto_sub to subscribe to the test topic:
mosquitto_sub -h localhost -t test
-h is used to specify the hostname of the MQTT server
-t is the topic name
You’ll see no output after hitting ENTER because mosquitto_sub is waiting for messages to arrive. Switch back to your other terminal and publish a message:
mosquitto_pub -h localhost -t test -m “hello world”
-m option to specify our message
Hit ENTER, and you should see hello world pop up in the other terminal. You’ve sent your first MQTT message! Optionally, the MQTT broker can be configured to use TLS by using either a CA-signed or self-signed certificate.
Dashboard Configuration for Sense
MV Sense is enabled with an additional software license that is applied on an individual camera as needed.
1. Claim your MV Sense license by going to Organization > Configure > License
2. Once the licenses are claimed, go to Cameras > Monitor > Cameras, select a camera and then go to Settings > Sense, and click Enabled
Configure MQTT and Zones on a Camera
Zones can be configured to create specific areas of interest. To create a zone, you must go to Cameras > Monitor > Cameras, select a camera and then go to Setting > Zones. Once a zone is created, you can make specific calls for any person detection events captured within the zone. Below is a screenshot showing this functionality:
To setup MQTT on your camera, go Cameras > Monitor > Cameras, select a camera from the list page and then go to Settings > Sense. Click Add or edit MQTT Brokers to create a new MQTT broker configuration:
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 can choose to hostname verification.
- Optionally, test the connection between a camera and the broker to ensure communication
Sample MQTT Message from MVs
The following topics and messages are published by a camera to the broker when configured (XXXX-XXXX-XXXX is the S/N of the camera ) :
- Number of entrances in the complete field of view:
/merakimv/XXXX-XXXX-XXXX/0
{“ts”:1541699540806, “counts”:{“person”:1}}
- Number of entrances in a particular zone. (Use the REST API to get zone ID as shown)
/merakimv/XXXX-XXXX-XXXX/566327653141839878
{“ts”:1541699602570, “counts”:{“person”:1}}
- When a person is detected, a list containing person identifier(oid) and X,Y coordinates are published
/merakimv/XXXX-XXXX-XXXX/raw_detections
{“ts”:1539055297728,”objects”:[{“frame”:5961,”oid”:5,”x0″:0.67,”x1″:0.458,”y0″:0.738,”y1″:0.111}]}
ts – timestamp in epoch time
oid – unique identifier for the person detected
REST API
Use The Cisco Meraki Dashboard API KB article to obtain your dashboard API key
REST API Endpoints
Analytics Overview Returns an overview of aggregate analytics data for a time span
GET https://api.meraki.com/api/v0/devices/[serial]/camera/analytics/overview
Successful HTTP Status: 200
{
"startTs": "2018-11-16T17:25:18.822Z",
"endTs": "2018-11-16T18:25:18.822Z",
"zoneId": 0,
"entrances": 2,
"averageCount": 0.0005263157894736842
}
Zones – Returns all configured analytic zones for this camera
GET https://api.meraki.com/api/v0/devices/[serial]/camera/analytics/zones
Successful HTTP Status: 200
{
"id": "0",
"type": "occupancy",
"label": "Full Frame"
}
History – Return historical records for analytic zones aggregated per minute
GET https://api.meraki.com/api/v0/devices/[serial]/camera/analytics/zones/[zoneId]/history
Parameters
perPage – The number of entries per page returned
startingAfter – A token used by the server to indicate the start of the page. Often this is a timestamp or an ID but it is not limited to those. This parameter should not be defined by client applications. The link for the first, last, next or prev page in the HTTP Link header should define it.
endingBefore – A token used by the server to indicate the end of the page. Often this is a timestamp or an ID but it is not limited to those. This parameter should not be defined by client applications. The link for the first, last, next or prev page in the HTTP Link header should define it.
Successful HTTP Status: 200
{
"startTs": "2018-11-16T17:28:58.367Z",
"endTs": "2018-11-16T17:29:58.367Z",
"averageCount": 0,
"entrances": 0
}
entrances: How many people entered the frame during that minute
average_count: How many people were in view of the camera on average over that minute (sampled at 5fps). For example, if one person stood there for 30 seconds, the result would be 0.5.
Recent – Returns most recent record for analytics zone
GET https://api.meraki.com/api/v0/devices/[serial]/camera/analytics/recent/[zoneId]
Successful HTTP Status: 200
{
"zoneId": 0,
"startTs": "2018-11-16T18:27:05.002Z",
"endTs": "2018-11-16T18:28:05.002Z",
"entrances": 0,
"averageCount": 0
}
Live – Returns near real-time record for analytics zone
GET https://api.meraki.com/api/v0/devices/[serial]/camera/analytics/live/[zoneId]
Successful HTTP Status: 200
{
"ts": 1542393082849,
"state": {
"0": 0,
"566327653141839878": 0
}
}