Introduction: Subscribing to a Helium Atom in Ruby

By

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 APIs for connecting to its wireless transceiver, the Atom. In this tutorial I will show you how to subscribe to your Helium Atom using the Ruby API, rbhelium.

Other helpful Helium resources include:

Helium Blog

Helium Forum

Helium Docs

Step 1: Install Rbhelium, Libhelium and Msgpack-ruby

rbhelium is the API to speak with the Atom via Ruby, but is itself a binding on libhelium, Helium's C API. Therefore, before rbhelium and be leveraged libhelium must be downloaded and built.

libhelium

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

rbhelium

Once libhelium is built rbhelium can be installed. Several common tools for Ruby programmers are needed for this installation: pthreads, Bundler, and ruby-devel. If you do not already have these running, install them before rbhelium.


Ruby MessagePack

The final piece needed is msgpack-ruby. This is used to unpack the messages sent by your Atom.

Step 2: Ruby Code

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

Include your required libraries. libhelium is bound by rbhelium, so it does not need to be explicitly included.

require 'rbhelium'
require 'base64' 
require 'msgpack'

Set thread.abort_at_exception to true

Thread.abort_on_exception = true

Set and decode the token corresponding to your specific device. Your token can be found by registering your Atom's MAC address in the Helium Dashboard: LINK TO COME. The token is used to decrypt the secure data coming from the device.

token = Base64.decode64("kdTl6U1w+sR61NBiQjm8sw==:")

Create a new Helium connection and print the information received via this connection.

conn = Helium::Connection.new("r01.sjc.helium.io") do |mac, datums|
  puts "Got data #{MessagePack.unpack(datums)} from mac #{mac}"
end

Lastly, subscribe to your device using its MAC address and corresponding decoded token.

status = conn.subscribe(0x000000fffff00001, token)

In my program I added a sleep function to end the program in a hour's time

sleep 3600

Complete code can be found in attached file or here: RubySubscribe.rb on Github

Attachments

Step 3: Run Your Code

Now it's time to run your file!

I prefer to run mine in the terminal. To do that open the terminal and cd yourself into the folder containing your program. When in the proper location enter:

ruby yourfilename.rb

Your program should run and you should see your device's messages in the terminal. Strike ctrl+c to end the program.

More rbhelium resources: Forum Announcement, Blog Announcement

Tutorial for sending data from an Atom

Thank you, and have fun making!