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.
> rails generate apiotics:install
to install configuration files for the Apiotics gem.
Now, go to https://portal.apiotics.com 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)
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.
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.
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.
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.
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.
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
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.
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.
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:
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.save else self.alert.grove_pi_color_led.light = false self.alert.grove_pi_color_led.save end end
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.
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.