Apiotics Gem Quickstart

Apiotics Gem

The easy way to make your Rails application interact with IoT devices.


Add this line to your application's Gemfile:

gem "apiotics"

Or install it yourself as:

$ gem install apiotics

And then execute:

$ bundle
$ rails generate apiotics:install

On the Apiotics portal located at portal.apiotics.com, you can create a Hive for your project. Hives have Workers (each type of IoT device in your project will have a corresponding worker in the Hive). Workers have Drivers and Drivers have interfaces. An example worker might be a Thermostat.

Once you have created a Hive, it will give you a public and a private API key. Best practice is to set environment variables in your development, test and production environments to equal these API keys. Then, set config.public_key and config.private_key in config/initializers/apiotics.rb to those environment variables. You can enter the API keys directly into the configuration file, but you should only do this if you never plan to put your Rails application and Hive into production, as it is a significant security risk.

Apiotics.configure do |config|
    config.public_key = ENV['APIOTICS_PUBLIC_API_KEY']
    config.private_key = ENV['APIOTICS_PRIVATE_API_KEY']
    config.local_port = 8001
    config.server_port = 8000
    config.tls = true
    config.local_logging = true


After you have installed the API keys, log in to the Apiotics portal (portal.apiotics.com) to see that your Hive has Workers and that those Workers have Drivers and, if applicable, Scripts defined. Each Worker, Driver or Script will have one or more Interfaces. For example, if you are making a connected Thermostat, your Hive might have a Worker named 'Thermostat' and it might have the following Drivers: Thermometer and Furnace.

Each of the Drivers has Interfaces (all of this would be viewable on portal.apiotics.com).

We want to be able to interact with these interfaces easily through our Rails application for all of the Thermostats that we have out there in the field.

To do this, run the Apiotics Scaffold Generator.

$ rails generate apiotics:scaffold Thermostat

And then run

$ rake db:migrate

To install firmware onto your IoT device, plug it in via USB to your computer or insert the SD card for the device.

Next set your networking configuration:

If you are using WiFi, use the following command to set the wifi parameters.

$ rake firmware:wifi[SSID,Password,SecurityType]

Allowed security modes are NONE and WPA2

If your device uses cellular connectivity:

$ rake firmware:cellular[on]

If you want to give a name to the device you are installing, use the following command (for a thermostat to be installed in a kitchen for example):

$ rake firmware:install[Thermostat,Kitchen]

NOTE: The command may ask you for your password.

If you do not wish to give a name to the device you are installing run:

$ rake firmware:install[Thermostat]

The next thing we need to do is establish a communications channel we can use to communicate between our Rails application and the devices in the field. To do this, we use a local server that handles sending communications to the remote devices and handles communications that we will receive from them.

$ rake dev_comms:start

This starts our communications server. If you want to stop the communications server for any reason simply:

$ rake dev_comms:stop

Note that you can only communicate with devices if the local communications server is running.

Now, start your web browser.

> rails server

Then in your web browser of choice, navigate to http://localhost:3000/thermostats.

Mac Dougherty