1. MV Sense Camera APIs
  2. What is MQTT?
  3. Components of MQTT
  4. Mosquitto – Open Source MQTT Broker
  5. Dashboard Configuration for Sense
  6. Sample MQTT Message from MVs
  7. 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).

MQTT

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

rexAdpY9ENuHevohqfBZWkndZCSW8 XCUOtCbfW Ob 01mAlyHzf90OdTxUtNeibJQPywfYjG4zqDpyH38zVq7g8SVbMAQg21Rk9m57unfuFg6ZNbAJdKZwboZJ754IVXmuC6DmB

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:

xTtZfoIPir viwYTNvEG1zwEL7UQVu6ec6FmL4SWKZSQaRyx4ol 3H65gCA36oqvsItJ8EhUeE9X7ZMUwilWUtWPUObOzJof2j8WPVSXuO9hO45v5T4cAYzIQdxsfRud hW JxM

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:

h6wrIF6ddcg2qOADeDjvIe pI8rxo2W8KFDaH0oiwbg7DATz0RmV5whOh8XavJyJMRw1qHf3UMrYfhYqYlijcogo3Tfj78AZQhbuAQbtS3GxMgWEodjMSI343M6WE4wlbun0Gfpt

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 can choose to hostname verification.
  5. Optionally, test the connection between a camera and the broker to ensure communication

1fTZ svTiG0NbsSlq5EUHmPbeMlwlg84WQnY IcrkI8ECfvtHHNXDxe2UPVBu8DtJ4p1 ZFNQO7t4jLGGe637BBk8CNflxWpFY8IC1gNLqrvj5p3NTMxf4S77DJe7zORL7qcRKvV

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 ) :

  1. Number of entrances in the complete field of view:

/merakimv/XXXX-XXXX-XXXX/0

{“ts”:1541699540806, “counts”:{“person”:1}}

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

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