mbed Icon

Helium ARM mbed Guide


This guide covers getting up and running with the Helium Atom Prototyping Module and the ARM® mbed™ platform. Specifically it covers:

Required Hardware and Software

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

Installing and Configuring mbed

Once you have the required hardware components, you'll need to get your mbed development environment configured. You can do this using either the mbed web IDE or the mbed command line interface (CLI). Helium supports both.

mbed IDE

First, go to the mbed IDE and add the FRDM-K64F board in the platform selector.

Then import the helium_basic program in the IDE:

Hit the Compile button and you'll get a .bin file download that you can copy into the MBED folder that appeared when the board is plugged into your computer. You may need to reset the board to have the new application start after the application finish copying on to the board.

mbed CLI

Once you've installed the mbed CLI you can import the program using the CLI using:


$ mbed import http://mbed.org/teams/Helium/code/helium_basic/

then go into the helium_basic folder and set the target and toolchain just once for your target and toolchain:

$ mbed target K64F
$ mbed toolchain GCC_ARM

Then compile the application using:

$ mbed compile

Near the end of the output you will see where the resulting .bin file was created:

...
Total Flash memory (text + data + misc): 64673 bytes

Image: ./BUILD/K64F/GCC_ARM/helium_basic.bin

Copy that file into the folder that was created when you connected the board to your computer. You may need to reset the board to have the new application start after the application finish copying on to the board.

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 for the mbed device, 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 an example of how simple this is:

Building your Helium mbed Development Board

Ok. Now onto the hardware. Here is a picture of the assembled Helium Atom Prototyping Module connected into the K64F via the Helium Arduino Adapter.

To assemble your unit:

  1. Pin the Arduino Adapter into your mbed device
  2. Pin the Helium Atom Prototyping Module into the Adapter

Depending on the mbed device you will have to configure the RX and TX jumpers on the Adapter to get the mbed device to talk to the Helium Atom using the right pins.

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

Board RX TX Notes
FRDM K64F 9 7
WIZwiki-W7500 0 1

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.

Powering on the Element with Ethernet backhaul

To turn on the Helium Element with Ethernet connectivity, connect the supplied Ethernet cable to the back of the unit and into an internet-connected port that serves DCHP. The Element supports power over ethernet or you can connect the supplied power cable into an outlet. The Ethernet-only Element is in a white and purple case.

The orange LED light reports internet connectivity. When the LED is solid orange, you've got internet connection.

Behavior Explanation
Blue LED blinks once per second Normal operation, the Element is transmitting data to Atoms in range
Red LED blinks Normal operation. The Element is receiving data from Atoms in range
Red LED blinks rapidly for 10s to 1 min The Element is receiving a firmware update. Afterwards, the Element will reboot. No action is required on your part.
All 3 LEDs blink simultaneously once per second Fault code. The Element will reset on its own. No action is required on your part.

Powering on the Element with Cellular and Ethernet backhaul

To turn on the Helium Element with Cellular and Ethernet connectivity, connected the supplied power cable into an outlet. 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).

Your Element will be connected when the front-facing LED turns green (signaling 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 mbed device

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

To do that, let's take a look at the Basic example you imported previously.

The full source for the example is located on the mbed developer site and is also available on Github.


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

    #include "mbed.h"
    #include "Helium.h"
    #define __STDC_FORMAT_MACROS
    #include <inttypes.h>

    void report_status(int status)
    {
        if (helium_status_OK == status) {
            printf("Succeeded\n");
        } else {
            printf("Failed (status %d)\n", status);
        }
    }

    void report_status_result(int status, int result)
    {
        if (helium_status_OK == status) {
            if (result == 0) {
                printf("Succeeded\n");
            } else {
                printf("Failed - %d", result);
            }
        } else {
            printf("Failed (status %d)\n", status);
        }
    }


    #if defined(TARGET_K64F)
    Helium helium(D9, D7);
    #elif defined(TARGET_WIZwiki_W7500)
    Helium helium(D1, D0);
    #else
    #error Please define helium with serial tx/rx
    #endif

    Channel channel(&helium);

    int main()
    {
        printf("Starting\n");

        printf("Info - ");
        struct helium_info info;
        int status = helium.info(&info);
        if (helium_status_OK == status) {
            printf("%" PRIx64 " - ", info.mac);
        }
        report_status(status);

        printf("Connecting - ");
        status = helium.connect();
        report_status(status);

        printf("Creating Channel - ");
        int8_t result;
        status = channel.begin("Helium MQTT", &result);
        report_status(status);

        printf("Sending - ");
        const char *data = "Hello Helium";
        status = channel.send(data, strlen(data), &result);
        report_status_result(status, result);
    }

Code Walkthrough

Let’s walk through what this sample does.

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

Helium helium(D9, D7);

This creates an instance of the Helium class, in this case called helium using a serial port on pins D9 and D7. Notice how we used the C compiler's pre-processor to define different instances of helium based on what board is configured as the target.

You’ll use the helium object to perform Atom-related functions like 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 44, we move into the main() function. In the first few lines we print out some informational messages to the serial port and then get information and print the mac address of the atom.

You can open a serial port monitor like screen or minicom configured to point a the port the board is connected to to see log output.


    struct helium_info info;
    int status = helium.info(&info);
    if (helium_status_OK == status) {
        printf("%" PRIx64 " - ", info.mac);
    }
    report_status(status);

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


    status = helium.connect();

Assuming there is an Element within range, the Atom will connect seamlessly and you’ll be online right away.

Creating a Helium MQTT Channel

The end game of this sample is to send data from your mbed device 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 choosing.

On line 62 of this application 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.
    printf("Creating Channel - ");
    int8_t result;
    status = channel.begin("Helium MQTT", &result);
    report_status(status);

Assuming the call to channel.begin(“Helium MQTT”) is successful, we can move on to sending data to the channel. 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() function starting on line 66, we create a string literal called data with the contents “Hello Helium”.


    printf("Sending - ");
    const char *data = "Hello Helium";
    status = channel.send(data, strlen(data), &result);
    report_status_result(status, result);

We then attempt to send the data over the Helium network. status returns the result of the communication between the mbed device 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.

Making it All Happen

Now it's time to bring it all home. With the Basic example binary you previously built, the Element powered on and connected, and the configured board connected to a USB port, copy the .bin file to the folder for the connected board and wait for it to complete copying (the quickly flashing light will stop on completion). You may need to reset the board to start the newly loaded program.

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 Cloud 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 mbed. 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: