Build An IoT Rails Application in 5 Minutes

How To Build An IoT Rails Application With Apiotics in 5 Minutes

Click here for a video version of this tutorial

First, create a new rails app

> rails new HeyBlinkin --skip-spring

Then, add the Apiotics gem to your new application's Gemfile and run bundle.

gem 'apiotics'
> bundle

Next, run

> rails generate apiotics:install

to install configuration files for the Apiotics gem.

Now, go to and log in to the site. (Since you're probably reading this on the Apiotics portal, the login button is on the top right hand side of the page)

A New Hive

Once you are logged in to the portal, click on the "Hives" tab on the left side of the page, and then on the New Hive button to create a new Hive.

Hive API Keys

In Apiotics, a Hive is what organizes the set of IoT devices associated with your IoT application, and also allows your Rails application to authenticate and securely communicate with those devices.

Name your new hive HeyBlinkin, since we're going to be creating an application using a connected device that has a button and an led. We're going to use the button to blink the led.

The Hive automatically generates API keys, which we will use in our Rails application to authenticate to the Hive.

Hive API Keys

Configuring your Rails application

The API keys are inserted in config/initializers/apiotics.rb. In order to protect your API keys in a production environment, you should use environment variables to store the API keys, and reference them in your apiotics.rb file. In the example below, we've just copied and pasted them into the file.

Hive API Keys

Creating a Worker

In Apiotics, a worker defines a kind of IoT device that we use with our IoT application. Each worker has a name, a base hardware platform, and a set of drivers associated with it. For the HeyBlinkin application, we are going to use a RaspberryPi 3 Model B+ as our hardware platform, for our drivers we will use a button driver and led driver.

First, on your HeyBlinkin hive page in the Apiotics portal, click on the New Worker button.

Let's call the worker an "Alert" and select the RaspberryPi 3 B+ as the hardware platform.

Hive API Keys

After creating the worker, click on the Manage Drivers button, and select the GrovePiButton and GrovePiLed drivers.

Next we'll configure the ports for our peripherals. Click the Set Interface Defaults button on the worker page, and set the GrovePiButton port to GrovePI::D2, so that we don't have the same port assignment for both of our peripheral drivers.

Hive API Keys

Generating A Scaffold

Instead of using the default Rails scaffold generator, we will use the scaffold generator included in the Apiotics gem to build scaffolding in our Rails application to control our new Alert worker. The Apiotics scaffold generator, just like the default generator, creates database migrations, models, controllers and views. Unlike the default Rails scaffold generator, we only need to give the Apiotics scaffold generator the name of our worker for it to generate the appropriate code and then run rake db:migrate to run the generated database migrations.

> rails generate apiotics:scaffold Alert
> rake db:migrate

Provisioning Our Device

Because our Alert device is going to connect to the Internet using WiFi, we use the following command to set the WiFi network parameters:

> rake firmware:wifi[<ssid>,<password>,<security_mode>]

For example, if we wanted to connect to an unsecured network called "OpenWifi", we would run the following command:

> rake firmware:wifi[OpenWifi,NONE,NONE]

And if we wanted to connect to a secured network called "SecureWifi" with a password of "password" using WPA2 security, we would run the following:

> rake firmware:wifi[SecureWifi,password,WPA2]

Then, you can install an image on your RaspberryPi that includes drivers for the Button and Led that we selected before.

> rake firmware:install[Alert,TestUnit]

The first argument is the name of your worker, in this case Alert, and the second (optional) argument is a name that you want to give to the particular worker instance you are creating on this particular RaspberryPi. As this command runs, you will need to give it your password, and select the drive that contains the SD card that you are installing the image on to. Be careful not to install the image on to the boot drive of your development machine!

Insert the SD card into the Raspberry Pi, seat the GrovePi hat on top of it, and plug the led and button into ports D3 and D2, respectively. See here to get the hardware you need, and more

Then, boot up the RaspberryPi. Once it has finished booting up, you will see that a new worker instance appears on the worker page on the portal. It will show the name of your worker instance, if you gave it one above.

Hive API Keys

Starting Our Rails App

Now, start up the communications server that comes bundled into the Apiotics Gem.

> rake dev_comms:start

And then start the rails web server and navigate to localhost:3000/alerts in your browser.

> rails server

From within the generated web application, we can easily turn the Led on, and off.

Hive API Keys

Custom Logic

Now, let's add some custom logic to our Rails application to turn the led on and off when we press the button.

Each driver in our device has a model in our generated Alert module.

These models are associated with one another using Rails standard has_one, belongs_to logic. And each instance in these models are associated with a particular device.

So we can easily add this functionality in our app/models/alert/grove_pi_button.rb model.

First we define a callback in the model:

after_commit :blink

And then define the blink function

def blink
  if self.button_toggle == true
    self.alert.grove_pi_color_led.light = true
    self.alert.grove_pi_color_led.light = false

If we restart our communications server so that it picks up our changes to this model as follows:

> rake dev_comms:restart

Then the light will turn on and off as we press the button.

Learn more

That's it for our IoT Rails App in 5 minutes tutorial. But there's lots more to check out here on the Apiotics Portal.

Read our documentation
Checkout pre-configured workers

Mac Dougherty