Subscribing to a Helium Atom With C

Helium is a complete wireless platform for the internet of things, supplying integrated hardware, software interfacing, and infrastructure to easily, efficiently and securely connect objects to the internet. Helium has several SDKs for connecting to its wireless transceiver, the Atom. In this tutorial I will show you how to subscribe to your Helium Atom using the C SDK, libhelium.

Other helpful Helium resources include:

Helium Blog

Helium Forum

Helium Docs

Two libraries are needed to receive data sent by your Atom: libhelium and msgpack.

libhelium is the Helium-C library, and can be found on github. If you have OS X there is a prepackaged installer available lower on that page that does all the heavy lifting for you. Instructions for manually building libhelium on OS X and Linux arealso included there. For Windows users a walkthrough is available here: Building libhelium on Windows.

libhelium provides all the tools needed to receive the packages sent over the Helium Netowork, but Msgpack is needed to unpack them into readable data.

For this exercise we are using a test device with MAC address 000000fffff00001 and base-64 token kdTl6U1w+sR61NBiQjm8sw==.

Include required libraries, including standard stdio.h and string.h, along with msgpack and both helium libraries.

<p>#include <stdio.h><br>#include <string.h></p><p>#include <msgpack.h></p><p>#include "helium.h"<br>#include "helium_logging.h"</p>

This next chunk of code helps prevent errors which could occur from using certain PCs.

<p>#ifdef _MSC_VER<br>#include "msvc_inttypes.h"
#else
#include <inttypes.h>
#endif</p>

Make callback function that is triggered when your Atom sends a message.

<p>void test_callback(const helium_connection_t *conn, uint64_t sender_mac, char * const message, size_t count)<br>{</p>

Inside this function, make some memory to decode the data into.

<p>msgpack_zone mempool;<br>msgpack_zone_init(&mempool, 128);</p>

Deserialize the message and unpack it.

<p>msgpack_object deserialized;
msgpack_unpack(message, count, NULL, &mempool, &deserialized);</p>

Print the data to the terminal.

<p>printf("payload was ");<br>msgpack_object_print(stdout, deserialized);
printf("\n");</p>

Delete the memory space and end the function.

<p>msgpack_zone_destroy(&mempool);<br>}</p>

Next we need a main function. Create the function and declare some variables we will need, including a helium token, a character token and space for the message.

<p>int main(int argc, char *argv[])<br>{
  helium_token_t token;
  unsigned char *token1;
  char message[1024];</p>

Declare a helium connection and allocate a helium connection struct.

<p>helium_connection_t *conn;</p><p>conn = helium_alloc();</p>

Open the connection and call our previous function with it. Since Helium works on IPv6 and most networks at the moment are IPv4 we will have to use the r01.sjc.helium.io proxy for sending data.

<p>helium_open(conn, "r01.sjc.helium.io", test_callback);</p>

Store the base 64 encoded access token unique to your device's MAC address in a character array, then convert it into binary. Your device's token can be found my entering it's MAC address into the Helium Dashboard.

<p>token1 = (unsigned char*)"kdTl6U1w+sR61NBiQjm8sw==";</p><p>helium_base64_token_decode(token1, strlen((char*)token1), token);</p>

Subscribe to the device using its MAC address.

<p>helium_subscribe(conn, 0x000000ffff00001, token);</p>

Create an endless while loop so that the program stays subscribed to the atom until ended. Then end the function.

<p>  while(1) {<br>  }
  return 0;
}</p>

The complete code above can be found here.

I prefer to compile and run my in the terminal, using gcc as my compiler. Compiling you code takes the following format:

gcc filename.c -o outputfile -lhelium -lmsgpack

Then you use the designated output file to run your program:

./outputfile

You should see your device's messages coming up in the terminal. Strike ctrl+c to end the program.

If you need additional help, be sure to check out the Helium Forum.