AWS Icon

Helium AWS IoT Channel Guide


AWS IoT is AWS's dedicated IoT offering, used by developers and enterprises in IoT deployments as the entry point into AWS's Cloud Products. One can store, filter, transform, and act upon device and sensor data in the AWS Cloud.

The Helium AWS IoT Channel enables you to quickly send Helium device data to AWS IoT with little effort, while adhering to their schema and security best practices.


Prerequisites

To get started, you'll need accounts for both Helium Dashboard and AWS IoT as well as an activated Helium Atom.

Configuring and Deploying the AWS IoT Channel

Setting up the Channel in Dashboard requires three pieces of information from AWS.

Finding your AWS IoT Access Key ID

  1. Log in to your AWS IoT account
  2. In the nav bar, hover over your name and click My Security Credentials in the dropdown
  3. In the My Security Credentials page, click Users in the menu
  4. Click Add Users
  5. In Set User Details > User Name, type - helium
  6. Under Select AWS Access Type, make sure Programmatic Access is selected
  7. Click Next: Permissions
  8. We'll add a user to a group next. Click Add user to group > Create Group
  9. Name the new group helium and select AWSIoTConfigAccess policy
  10. Click Create Group
  11. Once this new group has been created, check the box to give the helium user group permissions. Click Next: Review.
  12. Confirm the new group, user, and policy and select Create user to finish.

You should then see a confirmation with your Access Key ID and the Secret Access Key. We'll be using these to finish setting up the Channel in Dashboard.

Deploying the Channel in Helium Dashboard

  1. In Dashboard, go to Channels and create a new AWS IoT channel
  2. Enter the Access Key ID and the Secret Access Key from AWS
  3. The AWS Region is available from the browser address bar in AWS IoT. The example below's region is us-west-2
  4. Name your Channel and click Create.

AWS IoT MQTT Settings

Once deployed, the Helium AWS IoT Channel auto-generates the correct configuration information needed to use the MQTT client provided by AWS IoT. Specifically, this enables you to automatically configure AWS IoT's MQTT client to subscribe to and publish messages to your Atoms.

DocImg

AWS IoT MQTT Settings Usage
Atom MQTT Subscription Topic Use this to subscribe to messages from a given Atom on the AWS IoT MQTT broker.
Atom MQTT Publish Topic Use this topic to send message to a given Atom on the AWS IoT MQTT broker.

Data Collection with AWS IoT MQTT

AWS IoT's MQTT broker allows you to collect samples of transmitted data and export it in multiple formats. Grab the MQTT Subscription Topic string from your Helium Channel under MQTT Settings, replace the “< atom-mac >” field with your Atom’s MAC address, and enter it into the Subscription Topic field on AWS. The default number of samples is set to 100 and can be modified to your liking.

DocImg

With the Atom running and transmitting data to AWS IoT, click Subscribe to Topic to begin collecting samples. Each transmission will show up individually and can be exported alone, or the entire sampling group can be exported as a whole.

DocImg

AWS IoT Channel Configuration Variables

Helium enables developers to interact with sensor settings and parameters over the air (OTA) using Configuration Variables. There are two types of Configuration Variables: Channel and Global. For the AWS IoT Channel, developers can use Channel Configuration Variables to orchestrate logic between Helium Devices and AWS IoT's Thing Shadow feature. Thing Shadows make it easy to model and alter sensor state programatically or via AWS IoT's Console. And with Channel Configuration Variables, you can ensure those state changes are both sent over the air to devices as needed; and reported back to your AWS IoT Thing Shadow.

Thing Shadows and Your Sensor Code

To use a Channel Configuration Variable with an AWS IoT Channel, you'll need two things:

Here's an example of an AWS IoT Thing Shadow for the Helium Device with the MAC Address 6081f9fffe000c19 (as seen through the AWS IoT Console):

DocImg

To interact with this Thing Shadow programtically, you simply reference the relevant fields in your sensor's code using the Configuration Variable schema.

Here's an example function from an Arduino Sketch that uses Configuration Variables to talk to the example Thing Shadow above. Here, our sensor will get the latest interval_ms setting based on the corresponding "desired" value in the Thing Shadow and then report it back to the Thing Shadow where it will be displayed as the "reported" interval_ms value.

void
update_config(bool stale)
{
    if (stale)
    {
        DBG_PRINT(F("Fetching Config - "));
        int status = config.get("channel.interval_ms", &send_interval, 5000);
        report_status(status);
if (status == helium_status_OK)
        {
            DBG_PRINT(F("Updating Config - "));
            status = config.set("channel.interval_ms", send_interval);
            report_status(status);
        }
    }
}


And if you wanted to interact with this same Thing Shadow as part of a control pipeline using the Helium Python Client on the Raspberry Pi platform, the equivalent code would look like this:


from helium_client import Helium

helium = Helium("/dev/serial0")
helium.connect()

channel = helium.create_channel("aws-iot") # Be sure to use your channel name here

# Access an instance of Configuration
config = channel.config()
# Get the channel setting for interval_ms
interval = config.get("channel.interval_ms")
# Report the device having set interval_ms
config.set("channel.interval_ms", interval)