Helium Command Line Interface (CLI) Guide


This guide covers getting up and running with the Helium Atom and the USB Adaptor. 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 CLI Development Board

The first thing we need to do is contruct our complete development board. This will be the combination of the Helium Atom Prototyping Module and the Helium USB Adapter. To build this, pin the Helium Atom Prototyping Module onto the USB Adapter. It should look like this when you're done:

cli2

Building the Helium CLI

Here are the steps to download and build the Helium CLI.

  1. Clone the helium-cli repo (and don't forget --recursive).
$ git clone --recursive https://github.com/helium/helium-cli.git
  1. Navigate into this directory and run make.
$ cd path/to/helium-cli
$ make 
  1. Once this is complete, and your Atom is connected to your workstation via the USB Adapter, you can the test then connection by using the info command and specifying the port you're connected. For example:
$ ./helium -p /dev/tty.usbserial-DN01IQCC info

cli3

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 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 Atom Prototying Module, 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 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're connected to the Internet. After that, the Element will connect to the Helium Network.

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).

Here's a short video about the Element and how to connect it:

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.

CLI Examples

Now that your Atom Prototyping Module and Element Access Point are both registered in the Helium Dashboard, we can try out a few of the CLI's commands.

What follows is series of commands and responses for standard CLI interface use. This example will connect, check connection, create channel, and send a string.

Connect your Helium Atom to the Network via the "tty.usbserial-DN01IQCC" port

$ ./helium -p /dev/tty.usbserial-DN01IQCC connect

Check if you Helium Atom is connected to the Network while plugged into port "tty.usbserial-DN01IQCC"

$ ./helium -p /dev/tty.usbserial-DN01IQCC connected

Create a channel named "Helium MQTT"

$ ./helium -p /dev/tty.usbserial-DN01IQCC channel create "Helium MQTT"
$ Channel created: 1

Send the string "hello world" to the Helium MQTT Channel (which was given the ID "1" in the previous command).

$ ./helium -p /dev/tty.usbserial-DN01IQCC channel send 1 "Hello Helium"

cli0

Once you send the string you will see the packet in your created channel's Realtime Packets section

cli1


Further Reading and Support