Prototyping with Node-RED

Node-RED is a programming tool for wiring together hardware devices, APIs and online services in new and interesting ways. It’s a really good tool to explore the Managed IoT Cloud (MIC) APIs, to prototype solutions and even build small custom adaptations.

Node-RED provides a browser-based editor that makes it easy to wire together flows using the wide range of nodes in the palette that can be deployed to its runtime in a single-click.

Install and run Node-RED

You can install and run Node-RED using docker or by following our manual guide.

Docker setup

docker run -p 1880:1880 --name mynodered nodered/node-red-docker
docker exec -it mynodered /bin/bash
cd /data
npm install node-red-contrib-managed-iot-cloud
exit
docker restart mynodered
# Open http://localhost:1880 in your web browser

Skip to section MIC API Node

Manual setup

To run Node-RED, you need to have Node.js installed. When you have Node.js installed, you can install Node-RED using:

npm install -g node-red

Now you can start a Node-RED server by running:

node-red

The Node-RED interface can now be found at http://localhost:1880 in your browser.

To make it easier to connect Node-RED to a MIC instance, we’ve created custom nodes to call the Cloud API and to connect to MQTT using normal user credentials.

To add the MIC nodes to your Node-RED server,

  • Navigate to the Node-RED user directory (default is $HOME/.node-red)
  • Run npm install node-red-contrib-managed-iot-cloud
  • Restart the Node-RED server

MIC API Node

The MIC API function node can be used to connect to the now deprecated Cloud API. It supports input and output for the APIs. Please contact MIC Support if you need to integrate API functionality in your Node-RED flows. We recommend using an HTTP client like Postman to use our REST API or our GraphQL client.

MIC Event In/Out Nodes

The MIC Event In/Out nodes are used for subscribing and publishing to MQTT topics in a MIC instance. You could say that we are simulating some sort of device that is publishing or subscribing to the MIC platform. Like when using the Cloud REST API, you must give user credentials to be able to use the nodes. The event in/out nodes can only connect to topics that the user has privilege to. Otherwise you will be disconnected.

The in node is for subscribing to a topic and the out node is for publishing.

Usage example

Creating an output node

Now we are going to create an output node. This will simulate some sort of device publishing data to a topic on the MIC platform.

  1. Connect output node
    • Drag the MIC Event node onto the Node-RED flow canvas. There are two different MIC Event nodes. Select the one with an arrow to the right(output).
    • Connect an inject input node to the left of the MIC Event output node.
  2. Double click the MIC Event node
    • Configure a Managed IoT Cloud account by clicking the edit icon.
    • Provide the correct information. This is the same information you previously used.
    • The static Manifest URL: https://1u31fuekv5.execute-api.eu-west-1.amazonaws.com
      • Note that the Manifest URL must start with https:// and can not end with a trailing /.
    • Your Cloud URL e.g demo.mic.telenorconnexion.com
      • Note that the Cloud URL can not start with https:// and can not end with a trailing /.
    • Your username and password.
    • Add a topic, the topic is created by using the domain topic path saved in the previous step. The topic follows a format like this thing-update/sub1/sub2/sub3/sub4/sub5/sub6/myTestThing .
    • If your domain topic was /TCXN/demo/ then your topic should be thing-update/TCXN/demo/00004268 . So sub1 equals TCXN, sub2 equals demo and myTestThing equals 00004268 .
    • The root domain is always implied. So if you have a thing in the root domain, your domain topic will just be /. In that case your topic should be thing-update/00004268 .
    • The number representing your thing can be found in the app board on your things detail page or in the url while on that page.
    • Optionally add a name for your node.
  3. Double click the inject node
    • Make sure to pick the JSON payload type.
    • Provide a correct input json object (see below) to the inject node.
  4. Test it!
    • Click Deploy in the upper right corner.
    • Wait for the MIC Event connection indicator to turn green.
    • Trigger the inject node by clicking the box to the left of the node.
    • Go into your App Board and update your things detail page. You should be able to see the new data!

Example payload for publishing

{
    "state": {
        "reported": {
            "engine": "OFF",
            "color": "#FF0000"
        }
    }
}

Creating an input node

Now we are going to create an input node. This will simulate some sort of device subscribing to a topic on the MIC platform.

  1. Connect input node

    • Drag the MIC Event node onto the Node-RED flow canvas. There are two different MIC Event nodes. Select the one with an arrow to the left (input).
    • Connect a debug node to the right of the MIC Event input node.

  2. Double click the MIC Event node

    • Configure a Managed IoT Cloud account by clicking the edit icon.
    • Provide the correct information. This is the same information you previously used.
    • The static Manifest URL: https://1u31fuekv5.execute-api.eu-west-1.amazonaws.com
      • Note that the Manifest URL must start with https:// and can not end with a trailing /.
    • Your Cloud URL e.g demo.mic.telenorconnexion.com .
      • Note that the Cloud URL can not start with https:// and can not end with a trailing / .
    • Your username and password.
    • Add a topic, the topic is created by using the domain path, read about it here. The topic follows a format like this thing-update/sub1/sub2/sub3/sub4/sub5/sub6/myTestThing .
    • If your domain topic was /TCXN/demo/ then your topic should be thing-update/TCXN/demo/00004268 . So sub1 equals TCXN , sub2 equals demo and myTestThing equals 00004268 .
    • The root domain is always implied. So if you have a thing in the root domain, your domain topic will just be /. In that case your topic should be thing-update/00004268 .
    • Make sure to use the same thing as you used for the output node.
    • The number representing your thing can be found in the app board on your things detail page or in the url when on that page.
    • Optionally add a name for your node.

  3. Test it!

    • Click Deploy in the upper right corner.
    • Wait for the MIC Event connection indicator to turn green.
    • Then open the debug window. The messages received by the subscribing input node will later show up here.
    • Now you can use the output node created before to publish data to the MIC platform.
    • Do this by triggering the inject node to the left of the output node.
    • If everything is set up correctly, you should now see the data you published with the output node show up in the debug window because we subscribed to that thing topic with the input node.