Using Meraki APIs with Node-RED

Node-RED is “a tool for wiring the Internet of Things”. It provides a graphical flow based editor built on NodeJS. This tool provides an easy way to interact with RESTful APIs and IoT messaging data like MQTT, then add your own logic to make things happen.

Docs

Node-RED Docs

Installation

Install

Watch a 5 minute video

Flow Library

Discover community supported Node-RED flows and nodes to learn or begin your next project. There are several Meraki flows that you can quickly import into your editor as well.

Flow Library

Flows

Flows are the individual programs that you will be building with Node-RED. They consist of several nodes which perform a single task on a msg object that is passed down the flow. They are easy to create and there are tons of free ones available.

In this example flow, a timestamp will be simply converted to a formatted date string. By double clicking on a node, you can pull up the node editor to set any values or code sections.

The blue “inject” node simply writes a timestamp in milliseconds to the msg.payload object.

It is then passed to an orange “function” node, which converts the raw milliseconds into a Date object, using JavaScript.

Finally, the msg object is passed to green “debug” nodes which will display the contents of the msg.payload property.

By pressing the blue button on the inject node, you can trigger the event and view the results in the Debug screen, which is available in the right-side toolbar.

Building a REST API Endpoint

Node-RED makes it easy to quickly build an API for your next application or service worker.

A RESTful API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data.

Flow

To extend our previous example, let’s make this timestamp available via a REST API request. This will return a timestamp message when you navigate to http://yourserver:1880/time.

To do this, all we had to do was add an “http” input node and modify its URL to be “/time”. This provides the endpoint which will extend your Node-RED server’s FQDN (i.e. http://localhost:1880/time)

In our previous example, the timestamp was generated by the blue “inject” node. We will instead write a simple function node to do this every time somebody visits the /time endpoint.

The msg.payload is then sent to the same Format Date node, which formats the time and includes the additional text.

Finally, the msg is sent to an “http” output node. This node is responsible for sending the information back to the API client.

The results will simply be our date string in the browser.

Consuming REST APIs

There are tons of APIs for web applications and IoT services. This data is typically passed around in a message format called JSON (JavaScript Object Notation). The structure simply consists of name/value pairs and organized using curly braces {“name”: “Billy Bob”}.

Let’s build a flow to get the time from a free test service.

http://www.jsontest.com/

We expect the endpoint http://date.jsontest.com/ to return a structure like this:

Flow

Our flow will consist of a blue “inject” node that passes an empty string to start the program.

A yellow “http” request node is where the magic happens. We simply need to add the API endpoint into the URL and choose our Method, which is GET by default.

Finally, the messages is formatted by extracting just the “time” property of the JSON results and appending it to our message string.

By clicking on the blue “inject” node button, the flow calls the API and displays messages in the debug console.

Building a Web Form

For a more advanced use, build a web page that provides a form to interact with the server.

Since a typical front-end web page consists of several different files for JavaScripts, CSS style sheets and the HTML page, I wanted a way to keep these parts modular. By using “mustache” nodes, you can add HTML syntax to your msg object. This opens the door for a more interactive experience.

Flow

I have created a sample Node-RED Flow to demonstrate how this can be accomplished, complete with an AJAX form post to get the results back to the client as well as send the information onto additional flows.

First, download the flow by clicking on the link and copying all of the JSON text inside of the red window.

http://flows.nodered.org/flow/1bffe6808d37bd96cce283939983e758

Then, paste that into your Node-RED editor and hit Deploy.

The sample flow should now be ready to test.

The important technique is how the mustache templates are used. Each template will set the “property” relative to the content.

The CSS node sets the “msg.payload.style” property. The JavaScript node sets the “msg.payload.script” property. The HTML node then includes these properties.

<script>{{{payload.script}}}</script>
<style>{{{payload.style}}}</style>

 

Basic Client Site Flow

The JavaScript mustache node will contain your script code. Set the “property” to “msg.payload.script” (or similar convention).

The CSS mustache node will contain your style code. Set the “property” to “msg.payload.style” (or similar convention).

The HTML mustache node will contain your HTML code but will now include the scripts and styles, along with other imports in a familiar way.

Demo

To use the the website, just open a browser to your server and add /mysite to the address: http://localhost:1880/mysite

The GET request will return a web page, built using the mustache templates. It first attaches a msg.url which will be used by the submit button to POST the data.

When you submit data, the information is passed into the flow as the msg.payload. The information is simply returned to the client, which is displayed in the footer of the page.

There was some fancy AJAX JavaScript code that manages how the page submits and displays the data. How this works is beyond this guide 😉

Meraki Demo Flows

Several demo flows have been created to demonstrate the Cisco Meraki APIs and Cisco WebEx Teams API.

• Scanning API
• Captive Portal API
• Dashboard API – Admin Form
• Cisco WebEx Teams API

Flows

A collection of flows have been created for use with this lab guide. Import the contents of the provided JSON file into your Node-RED editor.

Lab Flows

Scanning API

The Scanning API can be used to track the location of WiFi and Bluetooth clients.

Scanning API mechanics

This flow demonstrates the native functions of the Scanning API.

It then sends the observation data to a “link” node that can be used for various workflows as well as a MongoDB database.

Setup

MongoDB

A database is required for the location data storage. This flow uses MongoDB for that purpose. For the flow to run properly, please install and run MongoDB. The installation instructions are outside the scope of this document. Please refer to these instructions for your operating system.

MongoDB Installation

(Note: if you are using this guide with a Cisco DevNet sandbox, MongoDB is already installed and running)

Meraki

Before configuring the flow, a Meraki Network must first be configured to send the location data to your server.

More info on the Meraki Scanning API: https://documentation.meraki.com/MR/Monitoring_and_Reporting/Scanning_API

Login to the Meraki Dashboard and select your desired wireless network.

Navigate to the Scanning API section.

• Network-wide → Configure → General: Scanning API

Configure the Meraki wireless network Post URL

• Add a Post URL and set the address to the path for your server. The url will include the HTTP(s) path to your server with the endpoint being “/cmxNative” as configured in the flow’s API endpoints (this can be easily changed).
  • http://server/cmxNative

Node-RED

• Configure the function labeled “validate-validator – UPDATE”.
  • Paste your validator key here.

• Configure the function labeled “validate-secret – UPDATE”.
  • Type your secret here.

• Deploy your changes to Node-RED.
  • Click the red Deploy button in the Node-RED editor to save and run your application.

• Test your configuration by pushing the Validate button. If everything works, you will see a “Validated http….” message. Location should begin to appear within 2 minutes.

• View the location data in the Node-RED debugger.

At this point, you are ready to use the incoming location data. To demonstrate how you can work with the JSON data stream, a few extra flows were created.

Frontend Web Page

A simple frontend web page is demonstrated with this flow. It offers two web urls, http://server/showcmxNative and http://server/showcmxhtml , which pull the location history from a database and display the JSON data or a simple HTML table.

Database Utilities

This flow simply allows you to delete all of the data from the database, as well as an automatic function that cleans out older clients. This is primarily for demo purposes, so it keeps the database size small.

Captive Portal

The following two flows demonstrate a captive portal authentication process. This is typically used to handle WiFi authentication for a guest hotspot. Meraki offers a “Click-through” and “Sign on” method for gaining access to the network.

More info on the Meraki Captive Portal: https://meraki.cisco.com/lib/pdf/meraki_whitepaper_captive_portal.pdf

Click-through

The click-through flow creates a simple splash page which displays a form. Once the user clicks submit, the form data is sent to a “link” node for additional workflows and the client is redirected to the “base_grant_url” which Meraki uses to authenticate the client. The form data is then available via the gray link node. Attach a database or any workflow to this endpoint (via another link node).

Splash Page URL: HTTP://yourserver/excapClick

Setup

The flow does not need any configuration to get started. Simply configure your Meraki wireless network to redirect wireless users to your captive portal, a.k.a “Splash Page”. Once configured, the HTML splash page node can be tailored to your splash page design requirements.

• Wireless → Access Control: Splash page = “Click-through”

• Configure the Walled Garden

The walled garden allows access to your server and any dependency locations before authentication.

• Enable
• Ranges: yourServerIP or domain* (Note: domain name support is enabled via a support case to Meraki).

• Configure the Splash Page
  • Wireless → Splash Page: Custom splash URL

• Test in local browser
  • Open your site by navigating to http://yourserverIp:1880/excapClick
  • You can fake the AP data by appending these paramters to your URL.
    • ?base_grant_url=https%3A%2F%2Fn143.network-auth.com%2Fsplash%2Fgrant&user_continue_url=http%3A%2F%2Fask.com%2F&node_id=149624921787028&node_mac=88:15:44:50:0a:94&gateway_id=149624921787028&client_ip=10.110.154.195&client_mac=60:e3:ac:f7:48:08:22

• Test with WiFi client.
  • Connect your mobile device to the wireless SSID. It should automatically redirect you to the splash page.

Sign on

The sign on splash page is configured in a similar way as the Click-through with a few exceptions. 

Setup

• Set the Splash page method to “Sign on w/ Meraki Authentication”

• Create a WiFi user and authorize the admin for WiFi access.
  • Network-wide → Users
  • Select your “Zone” which will be the SSID name.
  • Push the “Add User” button, create the account and be sure to select “Yes” for Authorized.

• Update the Custom Splash URL to http://yourServerIP:1880/excapSignOn
• Test in browser by navigating your splash URL.

Finally, test with a mobile client.

Dashboard API – Admin Form

This flow demonstrates a simple use case to create admin users for the the Meraki Dashboard. This could be helpful for self registration into a Meraki sandbox lab. The concepts used here can also be easily extended to other Dashboard API calls such as updating a WiFi SSID or building a new network.

More info on Meraki Dashboard API

https://documentation.meraki.com/zGeneral_Administration/Other_Topics/The_Cisco_Meraki_Dashboard_API

Setup

In order to interact with your Meraki organization, the Dashboard must first be configured to use the API and an API key must be generated for your account. We will then use that API key in the Node-RED flow.

Meraki

• Enable the Dashboard API
  • Organization → Settings: Dashboard API = Enabled

• 

• Generate an API key
  • Profile → API key: Generate API Key.

Node-RED

• Configure the Env Variables: UPDATE THIS node.

• API_KEY: paste your API key between the single quotes.
• Shard: By default, dashboard is the intended API endpoint but posting data involves a redirect that breaks some functions. It is best to use your “shard” number, which is the subdomain available when you login to the Meraki Dashboard.

• orgId: Before we can use the form, we must know the Organization we will be working with. We will get this info in the next section.
• Deploy your changes

• Get the orgId

• Click on the blue inject node “List Organizations”. This will print all of the organizations your account has access to. Look for your desired organization and paste it into the Env Variables node previously modified.

• Deploy your changes
• Test
  • Navigate to the following URL to use your form:
    • http://yourServer:1880/meraki/admins

Cisco Spark

This flow is used to collect data from the previous sample flows and send messages to a WebEx Teams room. This is handy for monitoring Location logs, wifi access logins and Admin Form user creation.

Setup

Spark

• Get your Cisco WebEx Teams Access Token. You may need to sign-up for a developer account.
  • https://developer.webex.com/#

• Get your roomId. Use the built-in developer console to test an API call using your token. We will test the “List Rooms” endpoint and copy the room ID we intend to use for our test.
  • https://developer.webex.com/endpoint-rooms-get.html
  • Enable “Test Mode”
  • Run
  • Note the “id” value. This will be the roomId used in the flow.

Node-RED

• Update the “WebEx Teams Send Message (API) – UPDATE” node with your accessToken and roomId.

• Test the flow by pushing the blue inject “timestamp” node. This will generate the time in milliseconds and send the message to the WebEx Teams room

Success!

You should see messages generated in the WebEx Teams room for each of the previous sample flows.

Additional Resources

Source Code

Example Flows

More Info

Internet of LEGO

Node-RED Guide

Communities

Node-RED forum

Developer.webex.com

DevNet Cisco