I was recently playing with the Arduino Yun for a whole set of new projects, and I discovered a sketch that implements a REST API for the Arduino Yun. We’ll see in more details what a REST API is, but for now let’s say it allows to standardise the communication between your Arduino and the external world via WiFi or Ethernet, and develop complex applications without having to modify your Arduino sketch every time.

So I told myself: why not create one REST API for the CC3000 WiFi chip ? That’s exactly what I did as a weekend project, and I wanted to share it with you. If you want to directly jump to the project files, go over to the GitHub repository of the project.

So what’s a REST API ?

You may wonder: what’s a REST API ? It’s actually a concept that is widely used by many web applications like SaaS. REST stands for REpresentational State Transfer, and is a communication architecture that was created back in 2000. It defines many constraints that the architecture has to follow, the most important features being:

  • A client/server communication: a client sends a request to a server, and the server answers accordingly
  • A stateless communication: every request has to contain all the information so the server can understand it, without having to rely on some information stored on the server
  • A uniform interface to easily identify resources on the server

This allowed to standardise communication between web applications, and made them more scalable, faster, and simplified the development of more complex applications. Many applications now propose a REST API, for example the eCommerce plugin I am using on this website.

Why do we need it for Arduino & the CC3000 WiFi chip ?

The problem that I encountered while developing web applications using the CC3000 is that I had to create a new Arduino sketch for every application, that needs to be coordinated with the rest of the application, for example an interface running on my computer.

And then, I discovered the REST API of the Arduino Yun. It is a simple sketch for the Arduino Yun that allows to make REST calls directly from your browser. For example:

http://arduinoyun.local/arduino/digital/8/1

will put the pin number 8 to a high state on my Arduino Yun. With this REST interface, it’s easy to load a sketch once for all on your Arduino, and then only work on the interface on your computer that makes REST calls on your Arduino board. And for now, this kind of interface was only available on the official Arduino boards, like the WiFi & Ethernet shields, and the Yun.

But I wanted to have the same on my CC3000 WiFi chip: make a sketch that will create a web server on the Arduino board, and then accept REST commands from an external client, like from an interface running on my computer. With this, I just have to build complex web applications on my computer, and then made them interact with the REST API of my Arduino board. And that’s what I built in this project.

The Arduino sketch

Let’s see the Arduino sketch first. If it’s not done yet, get the files by going to the GitHub repository of the project. You will also need the following libraries for this project:

You might also need additional software components to make the mDNS service work for your operating system. Please have a look at the GitHub repository of the project for more information. The Arduino sketch is actually close to the one from this project:

Wireless Relay Control with Arduino & the CC3000 WiFi chip

The sketch basically consists in connecting the WiFi chip to your network, creating a web server on the Arduino board, and listening for incoming connections. The main difference is that when a command is received from a client, it is processed by the aREST library to see which mode we are in, which pin we want to access, and check if we want to read from this pin of write.

I won’t detail all the code here, but as an example, I will take the case where we have a digital command coming in, for example digital/8/r. When we detect a client that connects to the Arduino board, inside the aREST library we read the request and store it in a String variable with:

char c = client.read();
answer = answer + c;

We then check if we get a command (like “digital”), a pin (like “8”) and a value (like “1”). To detect all these values, we check when we encounter the “/” symbol:

if ((c == '/' || c == '\r') && state_selected == false) {

We then need to detect that’s it is a digital command. This is done with:

if (answer.startsWith("digital")) {
  // Serial.println("Digital command received");
  command = "digital";
  command_selected = true;
}

At the next “/” that will be detected, we then check the pin number:

if (command_selected == true && pin_selected == false) {
  pin = answer.toInt();
  // Serial.println("Pin " + String(pin) + " selected");
  pin_selected = true;
}

Finally, when we know which pin we want to access, we need to know if it’s a read command (for example digital/8/r) or if we want to write a given value. For example, reading is done by:

if (state == 'r'){
  
  // Read from pin
  value = digitalRead(pin);

   // Send answer
   serial.print(F("{\"return_value\": "));
   serial.print(value);
   serial.print(F(", "));

The same is done with other commands, like “analog” or “mode”. For the complete documentation about the REST API, you can check the GitHub repository of the aREST library.

A simple example for home automation

I want to finish this article by giving you a simple example you can use directly in home automation: controlling a relay and switching a LED on using a REST call. You will need the following hardware components to test this project:

The hardware configuration is the same as in this article:

Wireless Relay Control with Arduino & the CC3000 WiFi chip

Of course, you don’t even need to have anything connected to your Arduino (except the CC3000 chip) to test the project, as you will always have a confirmation message coming back from the Arduino inside your web browser. Once you assembled the hardware, we can test the sketch.

You first need to go into the sketch and modify your sketch by setting your SSID, password and security type of your WiFi network. You can then upload the sketch to your Arduino board, and wait a bit some it can connect to your local WiFi network. Now, you can simply go over to your favorite web browser, and type the following command to set the pin 8 to an output:

http://arduino.local/mode/8/o

You should instantly get the confirmation message right in your browser:

Setting pin D8 to output

We then need to set the value of pin number 8 to a high state, to turn the relay on:

arduino.local/digital/8/1

You should also have the confirmation message in your browser:

Pin D8 set to 1

In the same time, the relay should turn on, and power up the LED. If that works correctly, it means you successfully used the REST API on your project, and can start building more complex web applications for your Arduino.

If it doesn’t work at that point, it is probably because the mDNS service (that gives the arduino.local name to the board) is not working properly. One solution is to use the IP address of the board directly. To find it, simply open the serial monitor and reset the project: the IP address will be displayed once the CC3000 chip is connected to the WiFi network. You can then make calls like:

http://192.168.1.104/digital/8/1

Update 06/06/14: The project was updated and is now using the aREST library. It greatly simplified the code and made the project works more reliably. It also now works with other kind of hardware, like the Arduino Ethernet shield. The video is still using the old code, but the commands for the REST API and all the principles are exactly the same. Let me know if you encounter any issues with the new code!

I recorded a video to show you how the API works to control two LEDs connected to the Arduino board:

Future work

Of course, many things can still be done to improve the API. In the future I want to extend the API to get data from various sensor, like from the DHT sensor family. I also want to extend the API to communicate with I2C devices that are connected to the Arduino board. I will also rewrite some of the tutorials using the CC3000 chip to use this REST API. So please try it out, all the files you need can be found at the GitHub repository of the project and you can find the complete documentation of the API in the GitHub repository of the aREST library. If you do so and build exciting projects based on the API, please share here or on GitHub your experience with using this project!