[ { "title":"Meraki", "url":"/meraki/" }, { "title":"Explore", "url":"/meraki/explore/" }, { "title":"Building IoT Apps with Node-RED" } ] Code Exchange https://developer.cisco.com/codeexchange/platforms/meraki _blank

Building IoT Apps with Node-RED

Explore all of the Meraki APIs and interact with Cisco WebEx Teams easily with Node-RED. This is a great environment for learning and experimenting with APIs as well as Internet of Things technology.

Labs

Scanning API
Captive Portal API
Dashboard API
Cisco WebEx Teams API

Getting Started

This guide will walk through the configuration of several Node-RED flows to interact with the Meraki and WebEx Teams APIs. It will demonstrate how to think about connecting APIs and the Internet of Things by using flow-based programming. This concept is great for Network Engineers where you can think of routing packets through your application. You will be using your own Meraki Network and Cisco WebEx Teams accounts to interact with the APIs.

The labs should go quickly once the prerequisites and sample flows are installed. The following tools and sample applications will be helpful to you beyond this lab.

Prerequisites

Node-RED: Flow based programming tool
- Install
- 5 minute video
Ngrok: Reverse proxy to expose your local application to the public Internet.
- Install
- Make ngrok available in path

Resources

Start Node-RED and Create a Tunnel

Before we begin working with the lab applications, we must first ensure Node-RED has been successfully installed and running. The link to install Node-RED is in the prerequisites. To run the application, open a command terminal and type “node-red”.

$ node-red

You can then access the Node-RED editor at http://localhost:1880.

Ngrok

To make your local Node-RED instance available to the public Internet, run ngrok in a new terminal window. This will create a dynamic tunnel which routes http (80/443) to Node-RED (1880).

$ ngrok http 1880

You now have an encrypted and unencrypted URL that you can use for your labs. In addition, ngrok will display all of the connection requests as they happen, which can be helpful when troubleshooting.

In this example, I would use https://535f455c.ngrok.io for my server location.You can easily test this by navigating to your URL in a browser. It will open Node-RED if working properly.

Install Lab Flows

Open the Flow’s library page and copy the flow JSON text at the bottom of the page into your clipboard.

Source Code on Node-RED library

Import the flow in Node-RED by pasting it into the Clipboard.

Deploy your changes.

You are now ready to begin the labs!

Scanning API

Meraki wireless networks have the ability to track WiFi and Bluetooth devices and relay this telemetry data via an API.

Scanning API

Receive Telemetry Data

This flow demonstrates the native functions of the Scanning API.

It then sends the observation data to a “link”nodethat can be used for various workflows.

Setup

Meraki

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

Network-wide → 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 “/scanning” as configured in the flow’s API endpoints (this can be easily changed).
  - http://server/scanning
    - Note: “server” will be your public IP and port for the Node-RED server. If using a proxy like ngrok, you will use that provided tunnel address.
  - Secret
    - Define your secret here

Node-RED

Configure the function labeled “validate-validator – UPDATE” by double clicking on the orange function node.

Paste your validator key here.

Configure the function labeled “validate-secret – UPDATE” and press Done.
- Type your secret here.

Test

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.
Make sure to Save your dashboard configurations to begin receiving posts.

Verify

View the location data in the Node-RED debugger (will take about a minute for first data to arrive). You will need to expand out the object data to discover the observations.

The JSON data will arrive periodically and be visible in the debug tab. Each of the green “debug” nodes will output their msg object in this window. Look for the payload details by expanding each of the objects or arrays to discover the information. It is this data that will be parsed in future flows to make use of the data.

Manual Testing

You can optionally test the flow using a Postman collection of API calls.

Postman Collection

At this point, you are ready to use the incoming location data!

World Map

To make use of the location data, let’s try building a map by adding an additional flow.

Add a world map to visualize the data in real-time!

Install the WorldMap Node from the palette

Import the Flow

Sample Flow

Ensure the Input Link node is attached to “WiFi Location API” by double clicking on the node.

Verify

Open your browser to http://yourserver/worldmap

You will see the map automatically update the markers when Meraki sends location data. Clicking on a marker will display several attributes of the device.

You now have a real-time device tracking system! The worldmap is highly configurable so there are a lot of cool possibilities with this application.

Captive Portal API

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. Although most splash pages like this would be written in a more traditional web environment, this Node-RED method allows you to easily integrate the WiFi authentication process into other workflows. For example, a WebEx Teams message could be sent to notify that a user has logged in or a database could record the event.

Captive Portal API

Click-through

The click-through flow creates a simple splash page which displays a form. The splash page will be available at http://yourserver/excapClick. Once the user clicks submit, the form action will post the data to the [post] /excapClickLogin endpoint. The flow will redirect the client to a base_grant_url, provided by Meraki, that will effectively log the client in. The form data is routed to a gray link node where a workflow or database can make use of the session data.

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 and CSS Style nodes can be tailored to your splash design requirements.

Configure the Splash Page in Dashboard for your SSID

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.

Walled Garden: Enabled
Walled Garden 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

Test in your local browser

Open your site by navigating to http://yourserver/excapClick
You can fake the AP data by appending these parameters 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

Example

http://yourserver/excapClick?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

Verify

If you have access to the wireless SSID you are configuring, complete the following steps to verify everything works.

Connect your mobile device to the wireless SSID you’ve configured (if available). It should automatically redirect you to the splash page. Once authenticated, you should be free to use the wireless network.

Open the client details in the Meraki Dashboard
- Monitor → Clients: Select the client

Not Authorized

Authorized

You can press the “Revoke” link to end the client’s session. This is commonly used when testing your splash page.

Revoke Splash Authorization

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. Then Save your changes on the Dashboard.

Update the Custom Splash URL to http://yourServerIP:1880/excapSignOn

Test

Test in browser by navigating to your splash URL.

At this point, you will likely want to modify the splash pages to be branded as well as update your ToC.

Double click on the template node “HTML Terms and Conditions” to edit the HTML.

Dashboard API

Admin Form

This flow demonstrates a simple use case to create admin users for 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

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 by double clicking on the orange function node and replacing the strings in the single quotes..

API_KEY
- Copy from Dashboard
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. (see below screenshot URL)

OrgID (not required)

This step can be ignored, since this form allows you to select which Org you would like to use when you create an admin account. Alternatively, you could set the orgId using a provided utility flow to discover the ID. This might be necessary if you are modifying the form to be more controlled (i.e “Force new admins to be created in Sandbox1”).

Click on the blue inject node button “List Organizations” (at the bottom of the flow canvas). This will print all of the organizations your account has access to within the JSON results. Navigate to the Debug window in the right menu and scroll through the logs. Look for your desired organization by expanding the Objects and paste the corresponding ID into the Env Variables node previously modified.

Test

Deploy your changes

Navigate to the following URL to use your form:

https://yourServer/meraki/admins

Verify

Open your Meraki Dashboard and verify the user was created.

Organizations → Administrators

Cisco WebEx Teams API

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.

Cisco WebEx Teams API

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. Note: Use the console in full screen mode to have access to all functions.
- 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

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