Arduino Icon

Helium Arduino Guide


This guide covers getting up and running with the Helium Protoyping Atom Module and the Arduino platform. Specifically it covers:

Required Hardware and Software

Before we get started, make sure to have all of the following in your possesion:

Installing and Configuring Arduino

Once you have the required hardware components in hand, you'll need to get your Arduino development environment configured. You can do this using either the canonical Arduino IDE or via PlatformIO. Helium supports both.

Arduino IDE

First, download the Arduino IDE. Once you have this on your machine you can install the Helium package in one of two ways:

Install Helium Library via the IDE Menu

  1. From within the IDE, click Sketch, Include Library, and search for Helium.
  2. Once you find it, click the Install button.

Download the Helium.zip from GitHub

  1. Go to the releases section of the Helium Arduino repository on GitHub and download the latest Helium.zip file.
  2. Once downloaded, launch the Arduino IDE. Click Sketch then Include Library.
  3. Click Add .Zip Library and select the Helium.zip file.
  4. Lastly, restart the Arduino IDE and the Helium Library will now be available to you.

PlatformIO

Installing the Helium library for PlatformIO is a simple library install away. If you do not already have a PlatformIO project use the handy Quick Start guide to set one up.

Once you have a project, go into the project folder and add the Helium library using the standard PlatformIO command line interface.


$ pio lib install Helium

Register the Atom Prototyping Module in Helium Dashboard

Helium Dashboard is our hosted device management and visualization interface. This is where you'll configure and deploy all Atoms and Element Access Points that are part of your Helium Organization. You should have receieved an invite to Dashboard when you purchased your Helium hardware. If you still need an account, you can sign up here.

Before we start developing on the Arduino, it needs to be added to your Helium Dashboard organization and configured.

To add it to your Helium Dashboard organization, log in to Dashboard, click + Add Atom, give it a name, the last four digits of the MAC Address, and the 4 digit HVV Identifier. Here's how simple this is:

Building your Helium Arduino Development Board

Now onto the hardware. Here are several pictures of the assembled Helium Atom Prototyping Module connected to a Arduino UNO via the Helium Arduino Adapter. This unit is also equipped with the 2.4GHz and Sub-GHz antennas that are part of your shipment.

To assemble your complete Helium Arduino Development Board:

  1. Pin the Arduino Adapter into your Arduino board
  2. Pin the Helium Atom Prototyping Module into the Adapter
  3. Connect the provided antennas to the SMA connectors on board the Helium Arduino Adapter (optional)

Depending on the specific Arduino board, you will have to configure the RX and TX jumpers on the Adapter to get the board to talk to the Helium Atom using the right pins.

The following boards RX and TX pins are known. (Other configurations will also work but we've tested and confirmed the following.)

Board RX TX Notes
Arduino Uno 9 8
Arduino M0 Pro 0 1
Arduino Zero 0 1
Arduino Due 9 8 Wire up RX3 (15) to pin 8 on board, TX3 to pin9

Deploying the Helium Element

Before going any further, we need to power up and connect the Helium Element. The Element is what creates the local network coverage for your Helium Atom Prototyping Module. To deploy your Element, you will need to plug it into power (and Ethernet if applicable) and register the Element the Helium Dashboard.

Power up your Element

If you purchased your Helium Element as part of the Helium Starter Kit, it can use both Cellular and Ethernet for data backhaul. The easiest way to connect it is to plug it into power using the supplied power cable. If you wish for redundancy in the backhaul, you can also plug it into a live Ethernet port using the supplied cable. (Note that the Ethernet port must serve DCHP.)

For the Ethernet-only variant of the Element, connect the supplied Ethernet cable to the back of the Element and the other end into an internet-connected port that serves DHCP.

Your Element will be connected when the front-facing LED turns green (signalling Ethernet connectivity) or teal (for Cellular connectivity).

Note You can watch a short video about the Element and how to connect it here.

Activate the Element in Helium Dashboard

Once your Element is plugged into power and connected to either cellular or ethernet, it's time to register it in the Helium Dashboard. This process is similar to how you registered the Atom Prototyping Module. Log in to Helium Dashboard, select +Add Element, and enter the Element details.

Programming the Arduino

Now it's time to start programming the Arduino and sending data to Helium wirelessly.

To do that, let's take a look at the Basic example included with the Helium Arduino library. The example sketches can be found in the Arduino IDE under File > Examples > Helium. (You can also view it on GitHub.) Here's the Basic example in its entirety:


    /*
     * Copyright 2017, Helium Systems, Inc.
     * All Rights Reserved. See LICENCE.txt for license information
     */

    #include "Arduino.h"
    #include "Board.h"
    #include "Helium.h"

    Helium  helium(&atom_serial);
    Channel channel(&helium);

    void report_status(int status)
    {
        if (helium_status_OK == status)
        {
            Serial.println("Succeeded");
        }
        else
        {
            Serial.println("Failed");
        }
    }

    void report_status_result(int status, int result)
    {
        if (helium_status_OK == status)
        {
            if (result == 0)
            {
                Serial.println("Succeeded");
            }
            else {
                Serial.print("Failed - ");
                Serial.println(result);
            }
        }
        else
        {
            Serial.println("Failed");
        }
    }

    void
    setup()
    {
        Serial.begin(9600);
        Serial.println("Starting");

        // Begin communication with the Helium Atom
        // The baud rate differs per supported board
        // and is configured in Board.h
        helium.begin(HELIUM_BAUD_RATE);

        // Connect the Atom to the Helium Network
        Serial.print("Connecting - ");
        int status = helium.connect();
        // Print status
        report_status(status);

        // Begin communicating with the channel. This should only need to
        // be done once.
        //
        // NOTE: Please ensure you've created a channel called "Helium
        // Cloud MQTT" called in the Helium Dashboard.
        int8_t result;
        Serial.print("Creating Channel - ");
        status = channel.begin("Helium MQTT", &result);
        // Print status and result
        report_status_result(status, result);
    }

    void
    loop()
    {
        const char * data = "Hello Helium!";

        // Send some data to the configured channel
        int8_t result;
        Serial.print("Sending - ");
        int    status = channel.send(data, strlen(data), &result);
        // Print status and result
        report_status_result(status, result);

        // Wait a while till the next time
        delay(5000);
    }

Sketch Walkthrough

Let’s walk through what this sketch does.

The first thing you’ll see below the set of #include lines is:

Helium helium(&atom_serial);

This creates an instance of the Helium class, in this case called helium. You’ll use this to perform Atom-related functions like turning on the serial interface and connecting to the Helium network. For example, here's how we would create Channel instance called channel that we'll use to send data to the Helium MQTT service later on.

Channel channel(&helium);

Next, on line 45, we move into the setup() block. This should be familiar if you’ve worked on any Arduino sketches before. In the first few lines of this we setup the Serial port for output to the Arduino Serial Monitor tool.


    Serial.begin(9600);
    Serial.println("Starting");

Then, on line 57, we call helium.connect() to ask the Atom to connect to the Helium network.


    int status = helium.connect();

Assuming there is an Element within range, the Atom will connect seamlessly and you’ll be online right away. You can open the Arduino Serial Monitor from within the Arduino IDE to see log output of what is happening.

Creating a Helium MQTT Channel

The end game of this sketch is to send data from your Arduino to the Helium MQTT Channel over the Helium network. Channels are the optimized routing layers Helium has built to send your device data directly to the Cloud Service(s) and endpoints of your chosing.

On line 66 of this sketch we establish a cloud MQTT Channel and start sending data to it. The name is important and is what you’ll use in the following lines to create the channel and start sending data to it.

        // Begin communicating with the channel. This should only need to
        // be done once.
        //
        // NOTE: Please ensure you've created a channel called "Helium
        // Cloud MQTT" called in the Helium Dashboard.
        int8_t result;
        Serial.print("Creating Channel - ");
        status = channel.begin("Helium MQTT", &result);
        // Print status and result
        report_status_result(status, result);

Assuming the call to mqtt.begin(“Helium MQTT”) is successful, we can move on to the main loop of the sketch. If the Helium Router can’t find a channel with that name associated with your Team, this command will fail.

Sending Data to the Helium Network

With a successfully connected Helium Atom and the MQTT Channel created, we can now start sending data to the Channel. As you can see in the main loop() that starts on line 74, we create a string literal called data with the contents “Hello Helium!”. We’ll use this in a moment as the data to send to the channel. You could of course change this to say whatever you’d like.

Directly following the main loop() is where the sending of data happens. Here we attempt to send the data over the Helium network. status returns the result of the communication between the Arduino and the Helium Atom. This should be 0 for success. Anything other than 0 means some kind of failure. result is the response from the Helium network as to whether the packet was delivered successfully or not. Again, 0 means success, and anything other than 0 indicates failure. We then wait 5 seconds with delay(5000) before attempting to send again.


    loop()
    {
        const char * data = "Hello Helium!";
        // Send some data to the configured channel
        int8_t result;
        Serial.print("Sending - ");
        int    status = channel.send(data, strlen(data), &result);``        
        // Print status and result
        report_status_result(status, result);
        // Wait a while till the next time
        delay(5000);
    }

Making it All Happen

Now it's time to bring it all home. With the Basic example opened, the Element powered on and connected, and the configured board connected to a USB port, click the Run button in the Arduino IDE. The IDE should upload the example sketch to the board and you should see the Atom Prototyping Module power on, connect, and perform the task coded into the loaded example sketch.

To verify data is flowing over the air to the Helium infrastrcuture, head to either the Atom or Channel section of Dashboard to see an Event Log of the last 100 messages sent by the Atom or to the Channel. From here, you can use an MQTT client such as Mosquitto to subscribe to the Helium MQTT server and see the messages as they flow in. The MQTT server settings can be found within the Helium MQTT Channel page within Dashboard.

Questions and Next Steps

Congratulations. You're now up and running with Helium and Arduino. Naturally this is just the beginning of great things for you. If you have any questions or comments on this tutorial, or want to get in touch with Helium or the community for whatever reason, here's are some options: