The easy way to make your Rails application interact with IoT devices.
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, optionally, Scripts. Drivers and Scripts have interfaces. An example worker might be a Thermostat. The Thermostat has a Control Script with two interfaces: temperature and target temperature. If you set the target temperature to 72 and the temperature is 65, the Thermostat will turn the heat on. We'll use this example again and flesh it out below.
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.
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/Scripts: Thermometer, Furnace and Control.
Each of the Drivers/Scripts has Interfaces (all of this would be viewable on the portal.apiotics.com portal). The Control script might have two interfaces: Temperature and Target Temperature.
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, we will create a model in our Rails application with attributes that correspond to the interfaces we want to interact with. We will then create records in our Rails database that correspond to our devices. Once we've done that, we can interact with a database record using ActiveRecord as usual, but the attribute values from our database records will be automatically synced to the corresponding device.
This generator actually creates models inside a module. The module is in app/models/thermostat.rb and the models in app/models/thermostat/thermostat.rb, app/models/thermostat/furnace.rb and app/models/thermostat/thermometer.rb. Each model that you generate for one of your Thermostat Worker's Drivers/Scripts is placed in the app/models/thermostat directory.
Now you should migrate your database in order to create the database tables that correspond to your model.
Now that you have your models and database tables created, you can use them to communicate with the devices that are out in the field.
The first 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.
Note that you can only communicate with devices if the local communications server is running.
Now that the preliminaries are out of the way, let's communicate with devices.
Now that you are synced with the device, you can read and set the device's Interfaces easily right from Rails.
First, let's read the temperature.
All of the communications to the device are taken care of for you. If the value of these Interfaces changes (if the ambient temperature rises or falls for example) then your database will be kept up to date via the communications server without needing to sync the device instance going forward so long as your comms server remains up and connected.
Now that you can communicate with your devices from the rails console, let's create a web scaffold so that you can communicate with them via your web browser.
Run the Apiotics scaffold controller generator to generate a scaffold and views for your device.
This command installs a default controller and views for your Thermostat. Once they are installed, you can see them in your browser by starting up your development web server.
Then in your web browser of choice, navigate to http://localhost:3000/thermostats. This page will show you a list of your Thermostat instances, as well as the current values of the different interfaces for your device. You can use the edit links for each device instance to change these values.
Since we want to be able to see changes to our devices without refreshing our webpage manually, we can leverage Rails 5's ActionCable to push device updates to our page.
In order for the ActionCable messages to actually transmit to the browser, we need to install Redis. Redis is an open source in-memory data store that ActionCable uses to implement its PubSub messaging.
Then, restart your Rails server and your comms server. Once you have done that, the values on the Thermostats page will update via push notifications.