Most of the home automation Arduino projects I’ve been working on lately use wireless communications (WiFi, Bluetooth, or XBee). Or at least these projects are interfaced with a computer via the Arduino serial interface. And one problem I had is that I felt I was reinventing the wheel at every new project, because I didn’t have a standardised way to make these projects communicate with an interface running on my computer.

Wouldn’t it be nice to have a generic sketch that you could upload to your Arduino board, that can then receive standardised commands coming from your computer ? That’s exactly what I will show you in this article. And as a demo, I will show you how to have an hybrid system with WiFi, Bluetooth and XBee Arduino projects communicating with a central interface, all using the same communication scheme. Let’s dive in!

The first step was a recent project where I worked on an Arduino sketch that implements a REST API for Arduino & the CC3000 WiFi chip. In a nutshell, I wanted an API where I could simply go to a web browser, and type in commands like /digital/8/1 to turn pin number 8 to a logical high state. In that sense, this kind of REST API is very close to what is used for SaaS (Software as a Service) applications. It makes much easier to create web applications that communicate with your Arduino projects, as you have a standardised way to access your Arduino system via WiFi.

But I wanted to go further: why not encapsulate everything inside an Arduino library ? And why not generalise this idea of having a REST API for Arduino to other ways of communication than WiFi? That’s exactly what I’ve been working on for this project. And the result is a library called aREST, that implements a REST API for Arduino Serial & WiFi communications. Because the library can also handle serial communications, it means it can work with the USB connection to an Arduino board, but also with Bluetooth and XBee.

The library basically comes with two examples: one for WiFi-based communications, and one for Serial communications. And to show you what the library can do, I will go through the detail of these two examples, and make a simple demo where we are going to control one WiFi, one Bluetooth, and one XBee module from a central web app running on your computer.

Hardware & Software requirements

The hardware that you need for this project really depends on what you want to do. To illustrate what you can do with the library, I used a simple setup: an Arduino Uno board, along with a simple red LED in series with a 220 Ohm resistor (to illustrate how the module can receive commands) and a DHT11 sensor (to illustrate how we can read data from a module). For the DHT11 module, you will also need a 4.7K Ohm resistor.

Then, I attached some wireless module to each of these projects. For this article, I had three projects in total: one with the Adafruit CC3000 WiFi breakout board, one Adafruit EZ-Link Bluetooth module, and one XBee Serie 1 module & SparkFun XBee Arduino Shield. For the Xbee communication, I also used one XBee Serie 1 module with an XBee explorer board. But of course, you can also test the aREST library with simply an Arduino Uno board connected via USB to your computer.

On the software side, you will need the usual Arduino IDE, and several Arduino libraries. The first one is of course the aREST library that you can find on the GitHub repository of the project. This repository is also a good point to learn about the API by reading the README file. You will also need the Adafruit CC3000 library and the Adafruit mDNS library. Finally, you will need the DHT sensor library to make the examples work. To install a library, simply insert the folder into your /library folder of your Arduino folder.

Hardware Configuration



The hardware configuration really depends on which wireless module you are using. But the common part is the same: you have to connect the LED and the DHT11 sensor to your Arduino board. The LED is connected in series with a 220 Ohm resistor to pin number 8 of the Arduino board. The signal pin of the DHT11 sensor is connected to pin 7 of the Arduino board. Don’t forget to put a 4.7K Ohm resistor between the signal & VCC pin of the DHT sensor.

For the wireless modules, it depends. The CC3000 breakout board is the most complicated one to connect, you can refer to this article for the detailed instructions on how to connect this module. For the Bluetooth module, you’ll have to connect the TX & RX pins to your Arduino board RX & TX pins. And for the XBee shield, you simply have to put the XBee module on the XBee Arduino shield, and plug the shield on your Arduino board. Warning, keep in mind that to upload a sketch to the Arduino board, the switch next to the XBee module on the shield has be set to “DLINE”. Also, don’t forget to plug the XBee explorer board to your computer so you can actually send & receive XBee data. I included pictures of my different projects so you can have an idea about how it looks like. This is the WiFi project:





The Bluetooth project:





And finally the one with XBee:





Your first RESTful Arduino project

To illustrate how the aREST library works, I’ll use the Serial version as an example along with the XBee shield. It is inspired from the Serial example that can be found inside the library. It starts by including the different libraries in the sketch, including the aREST library and the library for the DHT sensor:

#include #include "DHT.h"

Using the aREST library is actually really simple. You have to create instance of the library:

aREST rest = aREST();

We also declare the variables that will contain the measurements from the DHT sensor:

int temperature; int humidity;

Because the XBee modules use Serial communications, we need to start the Serial module in the Arduino sketch:

Serial.begin(9600);

Note that the speed of the Serial has to match the speed of your XBee modules, and by default it’s 9600 Bauds. To actually access these variables from the REST API, we need to declare them as such by giving them a name. This is done with the variable function of the library:

rest.variable("temperature",&temperature); rest.variable("humidity",&humidity);

You can also give an ID and a name to your module, that will be returned when making a call to the API:

rest.set_id("008"); rest.set_name("xbee");

In the loop() function of the sketch, we first measure the temperature & humidity from the sensor and convert them to integers:

float h = dht.readHumidity(); float t = dht.readTemperature(); temperature = (int)t; humidity = (int)h;

The handle of the incoming requests by the aREST library is done by passing the Serial object to the aREST instance:

rest.handle(Serial);

As you can see the Arduino code is really simple, because most of the work is handled by the aREST library. You can now upload the code to your Arduino board. Note that the code is also available on the GitHub repository of the project. We can now actually test the project without using XBee yet. Just open the Serial monitor (make sure the speed is set to 9600) and type:

/mode/8/o

Which will set the pin 8 as an output, as you can see on the confirmation message. Now type:

/digital/8/1

This should turn the LED on. Finally, type:

/temperature

This last command should return:

{“temperature”: 22, “id”: “008”, “name”: “xbee”, “connected”: true}

Simple, right ? Note that this data is returned using the JSON format, which will be quite easy to access later using programming languages like PHP or JavaScript. You can now put the switch on the board to “UART” so it uses XBee to communicate with the Serial port. Note that the repository of the project also contains the code for the Bluetooth & WiFi examples of the aREST library.

Controlling All Devices From a Central Dashboard

Let’s go further, and make a demo where several Arduino projects are controlled via a central interface. The code that you will find inside the GitHub repository is actually a demo for WiFi, Bluetooth and XBee, for in this article we’ll only see the WiFi and XBee parts as an example.

The demo interface is quite simple: for each module you want to interface using the aREST library, it will display two buttons to turn the LED on or off, a display of the current temperature, and a status field to check if the module is online or offline. This is how this interface looks like:





Note that the code is also available on the GitHub repository of the project. Let’s see how this interface works. There are three main parts: the app itself which uses Node.js, the interface coded in Jade (a simplified way to code HTML), and some JavaScript to make the link between both.

Let’s see the Node.js part first, located inside a file called app.js. We will not see all the details, as most of the communication between the app and our devices is handled by the node-aREST module. Inside this file you only need to change some lines to add the correct devices to the interface. This line is for WiFi (of course, you will need to change that for the IP address of your WiFi board):

rest.addDevice('http','192.168.1.103');

And this one is for the XBee project (you need to change it with the address of your XBee USB adapter):

rest.addDevice('serial', '/dev/tty.usbmodem1411', 9600);

It’s now time to test the interface. Note that the code is also available on the GitHub repository of the project. Make sure that all the files are located in a folder on your computer, go to a terminal, and type:

sudo npm install express jade arest

Then, type:

node app.js

Finally, go to this address with your favorite browser:

http://localhost:3000

Wait a moment, and you should see the status of the board being updated. You can also check the small LEDs on the XBee modules, they should blink regularly because the modules are sending/receiving data. You can also try out the buttons on the interface: you should be able to switch the LED on & off.

Note that at the time this article was written, there might still be some minor bugs with the interface, especially on the online/offline status indicator. I am working on improving this graphical interface, and you should see it as a canvas to build your own projects based on the aREST library.

How to Go further & Apply it to Your Own Projects

The goal of this project was really to standardise communications for your Arduino projects, so the field of applications is really large and not limited to home automation. With this project, you can control relays, measure data and retrieve it to you computer, and mix different wireless technologies in the same project.

To build your own applications & projects based on the aREST library, the first step is to head over to the GitHub repository of the project and read the documentation of the API. Then, you can start with the web app example that we saw in this project to build your own application, by modifying the code that you can find on the GitHub repository of the project. Using this code, you can really build a complete home automation systems using different wireless modules & Arduino!

Did you enjoy this project? You built some exciting applications using the aREST library? Found a bug in the API? Please share below! Note that you can also find Open Home Automation on Facebook and Twitter.

Update 25/11/14: The tutorial has been updated to make use of the node-aREST module. It greatly simplified the code to control the different boards from the web page. For example, it completely removed the need of another language (PHP).