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.
Watch a 5 minute video
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.
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.
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.
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
Let’s build a flow to get the time from a free test service.
We expect the endpoint http://date.jsontest.com/ to return a structure like this:
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.
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.
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.
Basic Client Site Flow
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.
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.
Meraki Demo Flows
Several demo flows have been created to demonstrate the Cisco Meraki APIs and Cisco Spark API.
- Scanning API
- Captive Portal API
- Dashboard API – Admin Form
- Cisco Spark API
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.
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.
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.
(Note: if you are using this guide with a Cisco DevNet sandbox, MongoDB is already installed and running)
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).
- 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.
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.
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
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
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.
- 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.
- Test with WiFi client.
- Connect your mobile device to the wireless SSID. It should automatically redirect you to the splash page.
The sign on splash page is configured in a similar way as the Click-through with a few exceptions.
- 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
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.
- Enable the Dashboard API
- Organization → Settings: Dashboard API = Enabled
- Generate an API key
- Profile → API key: Generate API Key.
- 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
- Navigate to the following URL to use your form:
- Navigate to the following URL to use your form:
This flow is used to collect data from the previous sample flows and send messages to a Spark room. This is handy for monitoring Location logs, wifi access logins and Admin Form user creation.
- Get your Cisco Spark Access Token. You may need to sign-up for a developer account.
- 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.
- Enable “Test Mode”
- Note the “id” value. This will be the roomId used in the flow.
- Update the “Spark 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 Spark room
You should see messages generated in the Spark room for each of the previous sample flows.