Meraki ICU

IFM supplies network engineering services for $NZ200+GST per hour. If you require assistance with designing or engineering a Cisco network - hire us!

Introduction

Second generation Cisco Meraki MV cameras (those ending with a "2" in their model number) have built in people detection.  The Cisco Meraki MV72 (and only the MV72) can also detect vehicles.  These cameras can deliver the detections (called a notification) via a system known as MQTT (Message Queue Telemetry Transport) to an MQTT broker.  Clients can connect to the MQTT broker and subscribe to those notifications and process them further in some way.

meraki-icu is a node.js application that subscribes or consumes the MQTT notifications from second generation Cisco Meraki MV cameras via an MQTT broker.  In the case of people detections it can optionally save a still snapshot and optionally pass the image to Amazon AWS Rekognition to profile the person and determine their gender, age range and emotional state.  In the case of vehicle detections (from an MV72 camera) meraki-icu can use a cloud based image to licence plate server - either platerecognizer.com or openalpr.com.  They call these services ALPR or ANPR depending where in the world you come from.  If platerecognizer.com is used and you are based in New Zealand meraki-icu can optionally look up the number in the New Zealand Police stolen vehicles database to see if the vehicle is stolen.

Limitations and Restrictions

  • To be able to deploy this you should have a medium skill level in using the Cisco Meraki system and scripting.  If you plan to use Amazon AWS Rekognition then you'll need to have a basic knowledge of using Amazon AWS.  If you have never done either or are new to doing this consider getting someone to help with sufficient experience.
  • The MQTT broker and meraki-icu should be installed on a machine located on the same site as the cameras. They don't need to be in the same VLAN, but the Cisco Meraki cameras need to be able to send messages via IP to the machine hosting the MQTT broker.  The program uses very little resources, so a low end workstation is fine.
  • The Cisco Meraki dashboard API limits calls to the dashboard to 5 per second for the entire organisation.  meraki-icu uses the dashboard API to request a snapshot of whatever triggered the person or vehicle event.  Consequently meraki-icu wont work well in an environment where more than 5 requests are made per second for snapshots.  Note that if you have any other dashboard API integrations running they will also be counting against the limit of 5 per second. You can have brief periods where it bursts higher than this, but it can not operate at a sustained level higher than this.
  • The MQTT framework uses the Cisco Meraki MV Sense API.  Each organisation gets 10 free licences.  If you need to use more than 10 cameras with this system you'll need to buy additional MV Sense licences.
  • meraki-icu has been written to expect all of the cameras being monitored to be in the same Cisco Meraki Dashboard organisation and network.  If you have cameras spread across more networks you'll need to either modify the code or run additional instances of meraki-icu.

Preparing to get started

You need to decide on a machine to install the meraki-icu onto.  meraki-icu uses very little CPU or RAM, so it can go onto a low end workstation.  This machine needs to have a static IP address.

meraki-icu is a node.js program.  If you don't have node.js then you'll need to download and install it.  It's free.  I like free.  Download and install node.js.  The default configuration is fine.

You need an MQTT broker.  I like the free MQTT broker called Mosquito.  Download and install Mosquito.  The default configuration is fine.

You need to configure the cameras that you want to use with meraki-icu to send MQTT messages to Mosquitto.  Follow the "Configuring MQTT in the Dashboard" guide.  Mosquitto defaults to using port 1883.

You need to enable the Meraki API.  I would recommend creating a dedicated Meraki dashboard administrator account for the API access.  meraki-icu requires read-only access.  The account needs to be able to access and view the cameras that will be used.  Follow the "The Cisco Meraki Dashboard API" guide to enable the API and to generate an API key.  The API key is essentially a password and you should treat it in the same way you would treat a user password.

If you want to do licence plate recognition you now need to decide on a ALPR cloud provider to use.  meraki-icu supports platerecognizer.com and openalpr.com.  In both cases the cloud API of each relevant service is used.

openalpr.com seems to be the most famous and very popular.

platerecognizer.com is cheaper, comes with a generous allowance of free plate recognitions (so you can have a really good play at no cost), and from my use of it - substantially better at converting images of number plates to readable text.

openalpr.com lists New Zealand as a supported country but it recognises so few number plates I found it useless.  It may be better for your country.  platerecognizer.com does not list New Zealand as a supported country but it pretty much recognises every single number plate image I gave it - even really bad images or barely readable images.  I found when using openalpr.com the images need to be really good.  An image a little less than good could not be recognised.

Whichever cloud based ALPR provider you choose, go open an account with them.  For platerecognizer.com you need to generate an API token.  For openalpr.com you need to generate an API key.  Remember you will be using their cloud based product.

To use Amazon AWS Rekognition you'll need an Amazon AWS account.  You'll need to create an IAM user with AmazonRekognitionFullAccess permission.  You'll need to generate an access and secret key.  I would also suggest installing the Amazon AWS CLI.  Once installed run "aws configure" to setup your environment to access Amazon AWS correctly. 

Deployment

Start by download meraki-icu.zip and extract it into a new directory.  Change into that directory and run "npm install" to install all the libraries used.

Next you need to create a ".meraki.env" file in your home directory (special note for Windows users - the filename is dot meraki dot env).  This is used to store your sensitive information.  If you are a Windows user and you go Windows+R  and type in "cmd" and hit return you'll have a command prompt with the current directory equal to your home directory.  From here you can go "notepad .meraki.env" to create the file.  A sample might look like:

x_cisco_meraki_api_key=****************************************

Now you need to create a .env file (note dot env) file in the meraki-icu directory.  This contains all of the configuration.  There is a sample .env.example file.  Start by copying .env.example to .env.  Then edit the .env file and fill out the required configuration.  Most of the options involve setting a "true" or "false" flag.  Make sure you fill out the list of cameras you are going to be using.

Ready, set, go!

You are now ready to run the system. Change into the directory and execute "node index.js". You should shortly get a message saying the system is ready to start processing camera messages.  If you get an error go back then check your work and try and work through the error message.

If you have it enabled, each time meraki-icu gets a person or vehicle detection message the image will be saved to the "people" or "vehicle" folder (as appropriate).  Note these folders could grow very big so create a scheduled task to delete its contents every now and then.

If you have either of platerecognizer.com or openalpr.com enabled (and a vehicle detection event occurs) a request is made for the licence plate to be read.  If the licence plate is readable it will be written to the console.  If you have configured lookups against the NZ Police stolen vehicle database and are using platerecognizer.com then that will also be checked and a special warning written to the console if the vehicle is listed as stolen.

If you have Amazon AWS Rekoginition enabled a request is made for details when a person detection event happens.  If a person can be identified, then the persons gender, age range and emotional state will be written to the console.

Summary

meraki-icu provides you with a working framework to use Meraki MV cameras to process people detection events and in the case of the MV72, vehicle detection events.  The vehicle detection events use an ALPR cloud based service to convert it to a licence plate in plain text which can then be passed onto other systems for further processing.  You can extend the code to provide further processing, as demonstrated by being able to consult the NZ Police stolen vehicle database.  People detection events can be processed by Amazon AWS Rekognition to determine information about the people the camera has seen.