HomeArduinoWiFi Location Fun with Cisco Meraki CMX & Nod ...

WiFi Location Fun with Cisco Meraki CMX & Node-RED

Posted by: ,

WiFi Location Fun with Cisco Meraki CMX & Node-RED

CMX map website

The IoL City would like to use their metropolitan free WiFi to better understand how the citizens move about the city. With this information, they can build smarter public areas, provide analytics for local services and trigger other forms of IoT automation.

How does Cisco Meraki CMX work?

All WiFi clients discover a wireless network (SSID) by sending a “probe request“. This is effectively a broadcast message emitted by the device (i.e. phone or laptop), which basically says “Hello! I want to join a network, my name is AA:BB:CC:DD:EE:FF”. In reality, the wireless access points in the area hear a broadcast message with a MAC address. At that point, the Meraki APs will log the time of day, MAC, signal strength and deduce some other bits of info like the manufacturer and operating system. The Meraki cloud will then combine this data with what other APs heard, to help triangulate the client with the help of GPS or X/Y coordinates on a map.

The Cisco Meraki Dashboard will retain this information in an anonymized way to generate helpful trend analysis for marketing research or event space optimization. Alternatively, Meraki can export the raw data feed to your own web service that will use that data however it’s needed.

For a complete explanation on this technology, check out this article.

 

Security & Privacy

As with all things IoT, security and privacy should be an important part of your final solution. If you are collecting this information in an unambiguous way, there should be disclaimers placed where the clients can be informed. This might be on a captive portal, or posted near the access points. Apple and likely Google will anonymize their MAC addresses during the probe request to prevent tracking of unaware clients. Only after the client has associated to a wireless SSID, will their MAC address remain consistent for accurate tracking. More information on security and privacy best practices can be found in a previous IoL article.

Network Diagram

Meraki CMX Diagram

Meraki CMX Diagram

JSON Data

  1. {
  2. “apMac”: <string>,
  3. “apTags”: [<string, …],
  4. “apFloors”: [<string>, …],
  5. “observations”: [
  6. {
  7. “clientMac”: <string>,
  8. “ipv4”: <string>,
  9. “ipv6”: <string>,
  10. “seenTime”: <string>,
  11. “seenEpoch”: <integer>,
  12. “ssid”: <string>,
  13. “rssi”: <integer>,
  14. “manufacturer”: <string>,
  15. “os”: <string>,
  16. “location”: {
  17. “lat”: <decimal>,
  18. “lng”: <decimal>,
  19. “unc”: <decimal>,
  20. “x”: [<decimal>, …],
  21. “y”: [<decimal>, …]
  22. },
  23. },…
  24. ]
  25. }

The Meraki Dashboard must be configured to point to your Node-RED service.

CMX Meraki Dashboard API config

In addition, the Meraki APs should be placed on the map within the Meraki Dashboard.

Hardware

Cisco Meraki MR access points

A minimum of three access points are required for triangulation, but one will at least give you some proximity.

Motion Sensor Towermr42-mantle

Cisco Meraki MX security appliance

This device acts as the Internet firewall. Although it’s not a mandatory component, it makes it easy to provide secure access to the Raspberry Pi with a simple NAT rule and by using the built-in Dynamic DNS feature.

mx65-mantle (1)

Raspberry Pi

The CMX web services will be hosted on this small computer, running Node-RED.

Pi2ModB1GB_-comp

Node-RED

To make this information easy to work with, I personally built my own Node-RED “node” to accept the JSON feed provided directly from a Meraki wireless network. I’ll go into the details of building that in a future post.

CMX node

Installation

(Note: I’m running this flow on a Raspberry Pi, so NodeJS and Node-RED are installed by default)

  • Install NodeJS
    • https://nodejs.org/en/download/
  • Install Node-RED
    • Run the following command in your computer terminal
  1. sudo npm install -g –unsafe-perm node-red
  • Install the Meraki CMX node
    • Run the following command in your Node-RED user directory – typically ~/.node-red
  1. npm i node-red-contrib-meraki-cmx
  • Restart Node-RED

 

Flow

I’ve created a few example flows to demonstrate the power of this new IoT data stream.

In this example, I have attached a “switch” node, which I named “Search Clients. This will look for either a MAC address or machine name to determine the next flow path. If an “Apple” device was found, I simply send a message “Apple device found!” to my debug screen. If my personal phone’s MAC address was found, it will trigger a message “Welcome Back”. If the device has not been seen for 5 minutes, it then sends a message “We Miss You!”. Although I am just sending these messages to the debug console, I have also played with sending myself a Tweet, logging the data and triggering lights in my LEGO city to start flashing. In theory I could create a digital media board to customize a welcome message, or combine it with my hotspot captive portal flow to build up profile information.

CMX sample flow


 

CMX Workflow

Download Flow:

In this example, I’ve pulled in the Meraki CMX node into my flow area. I then double clicked on it to bring up the local configuration.

CMX node

The URL is going to be the end point where Meraki will send the JSON stream of location data. This will look like http://yourserver:1880/cmx2

CMX config node

The Credentials section will hold the configurations specific to your Meraki network. It will consist of a validator and a secret. The validator is used by Meraki to ensure they are delivering content to the correct system. They do this by first sending a [GET] request to your path. The CMX node will automatically respond with this validator key. If successful, the JSON stream will be sent as a [POST] message to the CMX node. The secret will then be used by the CMX node to verify the data is coming from the correct Meraki network.

CMX config credentials

The CMX node is then connected to a switch node. which has two filters created, each representing a different output path.

CMX search function

The first criteria looks to see if the msg.payload contains the word “Apple”, if so the message function node will be triggered to rewrite the msg.payload object with the string “Apple device found!”.

CMX apple device found

The second criteria looks for a specific MAC address, then tells a trigger node to send a string “Welcome Back!”. After waiting for 5 minutes without seeing a new message, the trigger node will then send a string “We miss you :(”

CMX welcome message

That’s it! I can now easily consume WiFi location information to trigger a workflow.

CMX Map

Download Flow:

Since the JSON data contains GPS coordinates, among other things, I thought it would be fun to place this information on a map. To be fair, this front-end was largely ported from a CMX API demo project written with Ruby provided by Meraki. My primary task was re-writing the Ruby code with Node-RED. This involved storing the data into a MongoDB in the structure expected by the front-end code. The front-end will then present a Google Map that allows the ability to track all clients or a specific device. I then enhanced the data provided in the client info window and also allowed for a JSON export from the web page. I thought of many other ideas along the way… but I’m going to keep things simple for now.

Receive CMX Data

This flow section will accept the JSON data either from the CMX node or by injecting sample data.

 

CMX map - receive flow

The “Format Client” function node iterates through the supplied JSON and maps it to a client object to be stored in the database.

  1. // This function extracts the raw CMX data to create a consistent DB entry
  2. map = msg.payload;
  3. client = {}; //reset payload object for clarity
  4. if (map[‘version’] != ‘2.0’){
  5. msg.log = “got post with unexpected version: #{map[‘version’]}”;
  6. return msg;
  7. }else{
  8. msg.log = “working with correct version”;
  9. }
  10. if (map[‘type’] != ‘DevicesSeen’){
  11. msg.log = “got post for event that we’re not interested in: #{map[‘type’]}”;
  12. return msg;
  13. }
  14. var o = map[‘data’][‘observations’];
  15. console.log(‘map.data.apMac = ‘+map.data[‘apMac’]);
  16. for (var c in o){
  17. if (o.hasOwnProperty(c)) {
  18. //console.log(“Key is ” + c + “, value is ” + o[c].location.lat);
  19. if (!o[c][‘location’]){continue}
  20. client.name = o[c][‘clientMac’];
  21. client.mac = o[c][‘clientMac’];
  22. client.lat = o[c][‘location’][‘lat’];
  23. client.lng = o[c][‘location’][‘lng’];
  24. client.unc = o[c][‘location’][‘unc’];
  25. client.seenString = o[c][‘seenTime’];
  26. client.seenEpoch = o[c][‘seenEpoch’];
  27. client.floors = map[‘data’][‘apFloors’] === null ? “” : map[‘data’][‘apFloors’].join;
  28. client.manufacturer = o[c][‘manufacturer’];
  29. client.os = o[c][‘os’];
  30. client.ssid = o[c][‘ssid’];
  31. client.ap = map[‘data’][‘apMac’];
  32. msg.log = “AP #{map[‘data’][‘apMac’]} on #{map[‘data’][‘apFloors’]}: #{c}”;
  33. if (client.seenEpoch===null || client.seenEpoch === 0){continue}// # This probe is useless, so ignore it
  34. }
  35. msg.payload = client;
  36. node.send(msg);
  37. }
  38. return msg;

I then use a function node, “build operation parameters: filter, update”, to prepare the MongoDB insert operation.

  1. // This function updates/creates the client in the database
  2. var filter = msg.payload;
  3. if (“string” == typeof filter) {
  4. filter = JSON.parse(filter);
  5. }
  6. msg.payload = [
  7. {‘name’:msg.payload.name},
  8. msg.payload,
  9. {upsert:true}
  10. ];
  11. return msg;

The MongoDB2 node was something I had to install additionally into Node-RED. It provides tons of options for working with a Mongo database.

You can install it just like the CMX node, by going to the ~/.node-red directory and typing the following.

 

  1. npm install node-red-contrib-mongodb2

 A MongoDB database should be already installed and running for this flow to work. Installation instructions can be found here.

Client Front-end API

This flow section handles the requests made by the front-end page.

The [get] /clients route will perform a lookup in the database with a simple search query, msg.payload = {}, which is equivalent to find({}) in MongoDB. This will return all available documents within the database, which will be sent back to the client.

The [get] /clients/:mac route will accept a MAC address appended to the /clients/path, which is then parsed out of the params and then formatted in the following two function objects. Then a search for the specific client is performed on the database and returned to the client.

 

CMX map API

Client Front-end Site

This flow section will deliver the webpage that a user will see in their browser. Creating this specific flow was a process in itself, starting with the basic chaining of “mustache” nodes, which I describe in detail here.


CMX map siteThe core set of code is within that JavaScript mustache node. This is what I kindly borrowed from a clever Merakian. It basically utilizes the Google Maps API to place the supplied coordinates on the map and add information from the JSON data.

  1. (function ($) {
  2. var map, // This is the Google map
  3. clientMarker, // The current marker when we are following a single client
  4. clientUncertaintyCircle, // The circle describing that client’s location uncertainty
  5. lastEvent, // The last scheduled polling task
  6. lastInfoWindowMac, // The last Mac displayed in a marker tooltip
  7. allMarkers = [], // The markers when we are in “View All” mode
  8. lastMac = “”, // The last requested MAC to follow
  9. infoWindow = new google.maps.InfoWindow(); // The marker tooltip
  10. /*
  11. ,
  12. markerImage = new google.maps.MarkerImage(‘blue_circle.png’,
  13. new google.maps.Size(15, 15),
  14. new google.maps.Point(0, 0),
  15. new google.maps.Point(4.5, 4.5)
  16. );
  17. */
  18. var latlngbounds = new google.maps.LatLngBounds();
  19. // Removes all markers
  20. function clearAll() {
  21. clientMarker.setMap(null);
  22. clientUncertaintyCircle.setMap(null);
  23. lastInfoWindowMac = “”;
  24. var m;
  25. while (allMarkers.length !== 0) {
  26. m = allMarkers.pop();
  27. if (infoWindow.anchor === m) {
  28. lastInfoWindowMac = m.mac;
  29. }
  30. m.setMap(null);
  31. }
  32. }
  33. // Plots the location and uncertainty for a single MAC address
  34. function track(client) {
  35. clearAll();
  36. if (client !== undefined && client.lat !== undefined && !(typeof client.lat === ‘undefined’)) {
  37. var pos = new google.maps.LatLng(client.lat, client.lng);
  38. console.log(‘track client pos ‘+pos);
  39. if (client.manufacturer !== undefined) {
  40. mfrStr = client.manufacturer + ” “;
  41. } else {
  42. mfrStr = “”;
  43. }
  44. if (client.os !== undefined) {
  45. osStr = ” running “ + client.os;
  46. } else {
  47. osStr = “”;
  48. }
  49. if (client.ssid !== undefined) {
  50. ssidStr = ” with SSID ‘” + client.ssid + “‘”;
  51. } else {
  52. ssidStr = “”;
  53. }
  54. if (client.floors !== undefined && client.floors !== “”) {
  55. floorStr = ” at ‘” + client.floors + “‘”
  56. } else {
  57. floorStr = “”;
  58. }
  59. $(‘#last-mac’).text(mfrStr + “‘” + lastMac + “‘” + osStr + ssidStr +
  60. ” last seen on “ + client.seenString + floorStr +
  61. ” with uncertainty “ + client.unc.toFixed(1) + ” meters (reloading every 20 seconds)”);
  62. map.setCenter(pos);
  63. clientMarker.setMap(map);
  64. clientMarker.setPosition(pos);
  65. clientUncertaintyCircle = new google.maps.Circle({
  66. map: map,
  67. center: pos,
  68. radius: client.unc,
  69. fillColor: ‘RoyalBlue’,
  70. fillOpacity: 0.25,
  71. strokeColor: ‘RoyalBlue’,
  72. strokeWeight: 1
  73. });
  74. } else {
  75. $(‘#last-mac’).text(“Client ‘” + lastMac + “‘ could not be found”);
  76. }
  77. }
  78. // Looks up a single MAC address
  79. function lookup(mac) {
  80. $.getJSON(‘/clients/’ + mac, function (response) {
  81. track(response);
  82. });
  83. }
  84. // Adds a marker for a single client within the “view all” perspective
  85. function addMarker(client) {
  86. var pos = new google.maps.LatLng(client.lat, client.lng);
  87. console.log(‘addMarker pos ‘+pos);
  88. var m = new google.maps.Marker({
  89. position: pos,
  90. map: map,
  91. mac: client.mac,
  92. //icon: markerImage
  93. });
  94. if(client.lat){
  95. latlngbounds.extend(pos);
  96. map.fitBounds(latlngbounds);
  97. }
  98. google.maps.event.addListener(m, ‘click’, function () {
  99. //build info
  100. var htmlString = ‘<h2>Client: ‘+client.name +‘</h2>’;
  101. for (var key in client) {
  102. if (client.hasOwnProperty(key)) {
  103. if(client[key] !== undefined){
  104. if(key == ‘_id’ || key == ‘name’){continue}
  105. htmlString += ‘<p>’+key+‘ : ‘+client[key]+‘</p>’;
  106. }
  107. }
  108. }
  109. infoWindow.setContent(“<div>” + htmlString + “</div>” + “(<a class=’client-filter’ href=’#’ data-mac='” +
  110. client.mac + “‘>Follow this client)</a>”);
  111. //
  112. //infoWindow.setContent(“<div>” + client.mac + “</div> (<a class=’client-filter’ href=’#’ data-mac='” +
  113. //client.mac + “‘>Follow this client)</a>”);
  114. infoWindow.open(map, m);
  115. });
  116. if (client.mac === lastInfoWindowMac) {
  117. infoWindow.open(map, m);
  118. }
  119. allMarkers.push(m);
  120. }
  121. // Displays markers for all clients
  122. function trackAll(clients) {
  123. clearAll();
  124. if (clients.length === 0) {
  125. $(‘#last-mac’).text(“Found no clients (if you just started the web server, you may need to wait a few minutes to receive pushes from Meraki)”);
  126. } else { $(‘#last-mac’).text(“Found “ + clients.length + ” clients (reloading every 20 seconds)”); }
  127. clientUncertaintyCircle.setMap(null);
  128. clients.forEach(addMarker);
  129. }
  130. // Looks up all MAC addresses
  131. function lookupAll() {
  132. $(‘#last-mac’).text(“Looking up all clients…”);
  133. $.getJSON(‘/clients/’, function (response) {
  134. trackAll(response);
  135. });
  136. }
  137. // Begins a task timer to reload a single MAC every 20 seconds
  138. function startLookup() {
  139. lastMac = $(‘#mac-field’).val().trim();
  140. if (lastEvent !== null) { window.clearInterval(lastEvent); }
  141. lookup(lastMac);
  142. lastEvent = window.setInterval(lookup, 20000, lastMac);
  143. }
  144. // Begins a task timer to reload all MACs every 20 seconds
  145. function startLookupAll() {
  146. if (lastEvent !== null) { window.clearInterval(lastEvent); }
  147. lastEvent = window.setInterval(lookupAll, 20000);
  148. lookupAll();
  149. }
  150. // This is called after the DOM is loaded, so we can safely bind all the
  151. // listeners here.
  152. function initialize() {
  153. var center = new google.maps.LatLng(37.7705, –122.3870);
  154. var mapOptions = {
  155. zoom: 20,
  156. center: center
  157. };
  158. map = new google.maps.Map(document.getElementById(‘map-canvas’), mapOptions);
  159. clientMarker = new google.maps.Marker({
  160. position: center,
  161. map: null,
  162. //icon: markerImage
  163. });
  164. clientUncertaintyCircle = new google.maps.Circle({
  165. position: center,
  166. map: null
  167. });
  168. $(‘#track’).click(startLookup).bind(“enterKey”, startLookup);
  169. $(‘#all’).click(startLookupAll);
  170. $(document).on(“click”, “.client-filter”, function (e) {
  171. e.preventDefault();
  172. var mac = $(this).data(‘mac’);
  173. $(‘#mac-field’).val(mac);
  174. startLookup();
  175. });
  176. startLookupAll();
  177. }
  178. // Call the initialize function when the window loads
  179. $(window).load(initialize);
  180. }(jQuery));

The CSS mustache node does the styling. (I’ve left that code out to stay on topic)

The HTML mustache node will then import the JavaScript and CSS information since they were set as properties of the msg.payload object.

  1. <html>
  2. <head>
  3. <title>CMX push API demo app with Node-RED</title>
  4. <meta name=“viewport” content=“initial-scale=1.0, user-scalable=no”>
  5. <meta charset=“utf-8”>
  6. <script>TypekitConfig={kitId:“hum1oye”,scriptTimeout:1.5e3},function(){var a=document.getElementsByTagName(“html”)[0];a.className+=” wf-loading”;var b=setTimeout(function(){a.className=a.className.replace(/(\s|^)wf-loading(\s|$)/g,“”),a.className+=” wf-inactive”},TypekitConfig.scriptTimeout),c=document.createElement(“script”);c.src=“//use.typekit.com/”+TypekitConfig.kitId+”.js”,c.type=”text/javascript”,c.async=”true”,c.onload=c.onreadystatechange=function(){var a=this.readyState;if(!a||a==”complete”||a==”loaded”){clearTimeout(b);try{Typekit.load(TypekitConfig)}catch(c){}}};var d=document.getElementsByTagName(“script”)[0];d.parentNode.insertBefore(c,d)}()</script>
  7. <script src=“https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=false”></script>
  8. <script src=“http://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.0/jquery.min.js”></script>
  9. <script>{{{payload.script}}}</script>
  10. <style>{{{payload.style}}}</style>
  11. </head>
  12. <body>
  13. <div id=“masthead”>
  14. <div id=“masthead-content”>
  15. <img src=“https://meraki.cisco.com/img/cisco-meraki.png”/>
  16. </div>
  17. </div>
  18. <div id=“content”>
  19. <h1>CMX API Demo with Node-RED</h1>
  20. <div id=“mac-address”>
  21. <input id=“mac-field” type=“text” placeholder=“Enter MAC address” />
  22. <button id=“track”>Follow</button>
  23. <button id=“all”>View All</button>
  24. <button><a href=/clients target=“_blank” style=“text-decoration:none; color: inherit”>View All – JSON</a></button>
  25. </div>
  26. <div id=“last-mac”></div>
  27. <div class=“small”><span class=“bold”>Clients in the wrong place?</span> Make sure your APs are placed properly in Dashboard.</div>
  28. <div id=“map-wrapper”>
  29. <div id=“map-canvas”></div>
  30. </div>
  31. </div>
  32. </body>
  33. </html>

Note:

I had to create a Google API key to append to the import script for this to not generate errors. The real HTML line will look something like this

  1. src=”https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&key=XXXXXXXXXXXfLzjGaepofBse9sHFF-S-mtqVjzLA

 

The Website

In the browser, navigate to the path for your new website to see the results.

http://localhost:1880/cmxapimap
CMX map website

CMX map client details

 

Client JSON

By using Postman or simply clicking on the JSON button, all of the data within the MongoDB can be exported.

CMX map Postman

Conclusion

When thinking about IoT, sensors are one of the most important parts. By leveraging the Cisco Meraki CMX API, a huge amount of sensor data can be obtained that will enable location based workflows and analysis with ease.

the original post is from http://www.internetoflego.com/wifi-location-based-analytics-workflows-cisco-meraki-cmx/

Leave a Reply

You must be logged in to post a comment.

Category