Helium Raspberry Pi Guide

This guide covers getting up and running with the Helium Atom Prototyping Module and the Rasberry Pi platform. Specifically it will walk you through:

Required Hardware and Software

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

Building your Helium Raspberry Pi Development Board

The first thing we need to do is construct our complete development board. This will be the combination of the Helium Atom Prototyping Module, the Helium Rasberry Pi adapter, and the Raspberry Pi board you're using. To build this, drop the Helium Adapter onto the Raspberry Pi and then pin Helium Atom Prototyping Module onto the Rasberry Pi adapter. PIN 1 of the Raspberry Pi adapter should allign with PIN 1. That's it. It should look like this when you're done:

The Raspberry Pi adapter is only an extension of the Raspberry Pi pins. As such, all of the pin assignments for the Raspberry Pi are identical to the Raspberry Pi adapter. The Atom Module makes use of the software serial port on the Raspberry Pi, PIN 8 and PIN 10, and will be unavaliable for use by other devices while the Atom Module is using this port.

Configuring your Raspberry Pi Development Environment

After building the board we'll need to set up your Raspberry Pi with an operating system. Step by step hardware instructions and software instructions are available to set up your Raspberry Pi.

In the following we're going to assume that this installation completed and you're logged in as user pi, and have an open terminal.

Installing the python-dev package

Install the python-dev package so that the native extensions that are part of the Helium Python client library can be built during installation:

sudo apt-get install python-dev

Installing the Helium Python Client Library

If your Helium Atom is connected through an adapter, you will need to disable the login shell on the serial port of the Raspberry Pi. Start by running this in your terminal:

sudo raspi-config

Then select Interface Options > Serial and disable the login shell over serial, while enabling access to the Serial ports. Save the configuration and reboot the Raspberry Pi.

You can then install the Helium Python Client library in one of two ways:

Method 1: From PyPi

On a command line, install the library using pip:

sudo pip install helium-client

Method 2: From Source

On a command line, check out the helium-client-python repository:

git clone --recursive https://github.com/helium/helium-client-python

Install the package locally

cd helium-client-python
sudo pip install .

Registering the Atom Prototyping Module in Helium Dashboard

Now it's time to register your device in the 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 received 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 Rasberry Pi, 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:

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 in 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 Raspberry Pi

Now onto actually writing some code. The main reference for Helium's Python documentation can be found here.

The easiest way to get started is to look at the basic example included with the Helium Python library. (The example can be found in the GitHub repository.)

Here it is in its entirety:

    from helium_client import Helium

    helium = Helium("/dev/serial0")

    channel = helium.create_channel("Helium MQTT")
    channel.send("hello from Python")

Let’s walk through what this example does. The first thing you’ll see, below the import line, is:

helium = Helium("/dev/serial0")

This creates an instance of the Helium class, in this case called helium. The parameter is the serial port that is used to communicate with the Helium Atom.

Next we have this:


This tells the Helium Atom to the network. You should see red and blue blinking lights on the Helium Atom as it tries to securely connect to the Helium Network.

Creating a Channel

This code then creates what's known as a channel. 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. Channels are managed and deployed from the Helium Dashboard but your client code on the device also needs to know what Channels it's sending data to. This Python script will tell your device to start sending data to the Helium MQTT Channel. Every Dashboard account has this Channel created and enabled, so no additional setup is required to test the Helium MQTT Channel.

So, here's the part of the example that creates the MQTT channel and starts sending the string hello from Python to it:

    channel = helium.create_channel("Helium MQTT")
    channel.send("hello from Python")

That's all there is to it. The call either returns successfully or will raise an error if a failure occurs.

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.

Special Configuration for Raspberry Pi 3

If you are running a Raspberry Pi 3, the Bluetooth module will be blocking the serial port which the Atom Module uses to interface with your Raspberry Pi. To fix this problem, we will need to disable Bluetooth on the main serial port and undo a firmware update from the Raspberry Pi team.

First, SSH into your Raspberry Pi or log in through the Raspbian desktop environment with your login credentials. If this is your first time logging in, the username and password will be pi:raspberry.

    ssh pi@<your-pi-ip-address>

Next, we need to update and upgrade the OS, and update the firmware with these commands:

    sudo apt-get update
    sudo apt-get upgrade
    sudo rpi-update

After this process has finished, we need to edit the config.txt and cmdline.txt files in your /boot directory. The config.txt file controls all of the startup configurations for your Raspberry Pi, some of which can be set in the raspi-config menu.

    sudo nano /boot/config.txt

Navigate to the bottom of the file with the arrow keys and add dtoverlay=pi3-disable-bt and enable_uart=1 to the config.txt file. Ctrl+x to exit the Nano text editor, saving the file.

In the cmdline.txt file, we need to remove a reference to the serial port we are using on startup.

    sudo nano /boot/cmdline.txt

Remove the line console=serial0,115200 from this file, save, and exit the Nano editor

Finally, diable the systemctl processes for hciuart by typing the commands:

    sudo systemctl stop hciuart.service
    sudo systemctl disable hciuart.service

And sudo reboot your Raspberry Pi.

Questions and Next Steps

Congratulations. You're now up and running with Helium and Rasberry Pi. Your future is undoubtedly brighter than when you started this guide. 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: