1.8. Dev Kit: Sending Nordic Thingy data to Amazon Web Services

1.8.1. Overview

The Vesta Gateway runs a Node-RED application (“flow”) that connects to available Nordic Thingy:52 devices and sends that data to Amazon Web Services (AWS). This document will show you how to connect to and configure the Dev Kit, and how to modify it for your own purposes.

1.8.2. Getting Started

The Gateway will start Node-RED when it boots. There are two ways to begin interacting with the Node-RED application:

  1. Connect the Gateway to Ethernet. Then, using a computer connected to the same network, open a web browser page to the Gateway’s unit serial number with the suffix .local (e.g. http://b014012917-00065.local).
  2. Run through the process to connect the Gateway to your local Wi-Fi network (see Setup Wi-Fi with the Wi-Fi configuration app). At the end of this process will be a page with a link to the Node-RED application. Click the link once the Gateway has finished rebooting.

The Node-RED application will start the Dev Kit “flow” automatically. This flow will connect to any nearby Nordic Thingy devices (with the default name “Thingy”), and read sensor data from them. To power on a Thingy, remove the rubber enclosure from around the device and flip its power switch. The power should be on when the switch is closer to the corner of the device. If the battery is dead, plug the Thingy in via USB. When it is on, LEDs will blink slowly.

../_images/devkit-thingy.jpg

Figure 1.2 A Nordic Thingy, showing the power switch in the On position (on the side of the Thingy, front left corner), and the LEDs lit up blue-green.

1.8.3. Renaming the Thingy (optional, Beryllium 4.0+)

If the Gateway is running Rigado Board Support Package Beryllium 4.0 or later and you wish to change the Thingy’s name from the default (“Thingy”) you can follow these instructions:

1.8.3.1. Rename the Thingy

The Thingy’s name can be changed with the Thingy App from a supported Android or iOS device

To change the name via the Thingy App:

  1. Install the Thingy App

  2. Power off all nearby Gateways to prevent them from connecting to the Thingy

  3. Open the Thingy App on the mobile device, grant any Bluetooth or Location permissions requested by the App

  4. If the Thingy you wish to rename is not saved in the Thingy App, you must add it

    • If the Thingy App has no Thingy’s saved, an “Add Thingy” wizard will help you add the Thingy and at the end of the wizard you can set a new name.

    • If you have Thingys saved in the App and need to add a new Thingy

      1. Tap the hamburger button on the top left corner of the app
      2. Tap the arrow next to the name of the current Thingy (first item in the Menu),
      3. Tap “Add Thingy” and follow the wizard
    ../_images/devkit-thingy-app-wizard.png

    Figure 1.3 Thingy App “Add Thingy” wizard allows you to rename the Thingy after adding a new Thingy.

  5. If the Thingy is already added to the Thingy App:

    1. Tap the hamburger button
    2. Tap the arrow next to the name of the currently selected Thingy (first item in the Menu)
    3. Select the Thingy you wish to rename
    4. Tap “Connect” on the top right corner of the App and wait for the Thingy to connect
    5. Tap the hamburger button
    6. Tap “Configuration”
    7. Tap “Thingy name” and set the new name
    ../_images/devkit-thingy-app-config.png

    Figure 1.4 Thingy App “Configuration” page allows you to rename the Thingy.

For more details on using the Thingy App, see Nordic’s documentation

1.8.3.2. Updating the Node-Red Flow

Once you have renamed the Thingy, the Node-Red flow on the Gateway must be updated to look for a Thingy with the new name.

  1. Assuming the default Rigado Dev Kit flow is loaded, open a web browser and point it at the Gateway (e.g. http://b014012917-00065.local).

  2. Double click the noble-connect node in the flow, this will bring up the “Edit noble-connect node” pane

  3. Update the “Restrict by Name” field with the name of your new Thingy

  4. Click “Done” to save the changes to noble-connect

  5. Click “Deploy” to deploy the flow

    ../_images/node-red-change-thingy-name.png

    Figure 1.5 Updating the Thingy Name filter in Node-Red

1.8.4. How the flow works

The flow starts with a noble-connect node. This scans for Bluetooth Low Energy (BLE) devices, attempts to connect to them, and scans them for specific characteristic UUIDs.

From there it splits into two different processes. The top one formats the data and sends it to AWS if the switch on the dashboard is turned on. The bottom one formats the data and sends it to the graphs on the dashboard.

More detail about these processes can be found in the comment nodes in the flow itself. Highlight one of the comment nodes and open the Info tab in the sidebar to see its contents.

../_images/devkit-comment.png

Figure 1.6 A comment node, highlighted to show its contents.

Note

If you are running multiple Gateways with this Node-RED flow on them you may experience difficulty connecting to each Thingy. To ensure that the correct Gateway is connecting to the correct Thingy, you can try configuring the noble-connect node with the UUID of the Thingy (this should be a 32-character hexadecimal value). You could also disable the Dev Kit flow on other Gateways by deleting the nodes in the flow and clicking Deploy.

1.8.5. Modifying the flow

Any changes you make to the flow will need to be Deployed before they take effect. When you’re ready to test your changes, click the Deploy button in the top right corner.

Since this application deals with active connections over Bluetooth, it is recommended to restart Node-RED after Deploying.

Note

If Node-Red is restarted (via Gateway reboot for example), any changes made to the flow will be deleted if they were not “Deployed” first in Node-Red.

One easy way to restart Node-RED is to restart the Gateway itself. There are multiple ways to achieve this:

  1. Disconnect and reconnect the power
  2. Log in to the Gateway and run the command /etc/init.d/node-red restart
  3. Log in to the Gateway and run the command reboot

By default, the flow file on the Gateway is saved to /usr/share/node-red/dev-kit.json.

1.8.5.1. Debugging the flow

If you run into errors or see unexpected messages, it may become useful to check the Node-RED log file. Connect to the Gateway and check the contents of /var/log/node-red/node-red.log. You can list the entire file with the command cat /var/log/node-red/node-red.log, or “follow” the log with the command tail -f /var/log/node-red/node-red.log.

1.8.5.2. Reverting back to the original Dev Kit flow

If you need to reset the flow to its original state, you can do so by importing it from the Examples menu.

../_images/devkit-example.png

Figure 1.7 The location of the Dev Kit flow in the Examples menu.

1.8.6. AWS Architecture Overview

There are four main compontents to this the DevKit cloud infrastructure: AWS API Gateway, Lambda, DynamoDB and a freeboard.io based dashboard hosted in S3.

API Gateway gives us two HTTP endpoints (POST /datapoint & GET /datapoints). Those endpoints point at two Lambda functions (getFunction & postFunction) that read and write device data from a simple DynamoDB table with a partition key of deviceId.

Node-RED makes an HTTP POST call to the API Gateway once per second for devices it is connected to, which updates the DynamoDB table with the time that device was last seen and the value of the X coordinate of the device’s accelerometer.

The populateBucket Lambda function is triggered every 5 minutes by a CloudWatch event. It looks for new devices in the DynamoDB table and updates a JSON file in S3 to include a time-series chart for every device in the DynamoDB table.

The freeboard site hits the GET /datapoints endpoint once every 5 seconds and builds a table of all known devices and a time-series chart of accelerometer data. The configuration of this dashboard comes from the JSON file that populateBucket updates.

../_images/aws-arch.png

Figure 1.8 Diagram of AWS infrastructure used to ingest and display sensor data

1.8.7. Using your own AWS Account

If you would like to stand up your own copy of the Devkit Dashboard, you can follow the links below to stand up an AWS CloudFormation stack capable of processing the data from your Rigado Gateway.

Region Name Region Code CloudFormation
US West (N. California) us-west-1 USWest1Link
US West (Oregon) us-west-2 USWest2Link
US East (N. Virginia) us-east-1 USEast1Link

Follow any of the links above depending on your preferred AWS region and then follow the on-screen prompts to create a replica of our AWS infrastructure in your account. You should be able to use the defaults for everything.

Note

Standard AWS charges will be applied to your AWS account.

CloudFormation will take ~5-10 minutes to create the stack.

Once the stack is available, you can view the “Outputs” section of the stack in the AWS console and get the two pieces of information you will need:

  • ApiURL – Needed to point your Rigado Devkit at your new AWS infrastructure.

  • DasboardUrl – Needed to view your own version of the DevKit Dashboard.

    ../_images/stack-outputs.png

    Figure 1.9 Outputs from the stack creation.

In Node-RED, Double-click on the “Rigado Demo Kit Lambda” Node and change the URL to the value of “ApiURL” from your stack.

../_images/node-red-change-url.png

Figure 1.10 URL to change in Node-Red.

It will take a few minutes for the data to propagate to the dashboard.