A simple library that implements a REST API for Arduino. It is designed to be universal and currently supports REST calls via HTTP (using the CC3000 WiFi chip, the Ethernet shield or the Arduino Yun), via the Serial port (using the USB serial connection, Bluetooth, and XBee) and also via Bluetooth Low Energy.
- aREST.h: the library file.
- examples: several examples using the aREST library
- test: Python-based unit tests of the library
The library is at the moment compatible with the following Arduino boards: Uno, Mega, Due, Yun and Teensy 3.x
For the HTTP part, the library is compatible with most CC3000 breakout boards, and was tested with the Adafruit CC3000 breakout board and the CC3000 WiFi shield. It was also tested with the Tiny Circuit WiFi shield (but in that case, you will have to change the pins configuration inside the example WiFi sketch. See the Tiny Circuit WiFi shield documentation for more details). The library is also compatible with the official Arduino Ethernet shield, and with the Arduino Yun via the embedded WiFi connection.
For the WiFi part, the library is compatible with most CC3000 breakout boards, and was tested with the Adafruit CC3000 breakout board and the CC3000 WiFi shield. It was also tested with the Tiny Circuit WiFi shield (but in that case, you will have to change the pins configuration inside the example WiFi sketch. See the Tiny Circuit WiFi shield documentation for more details). The library was successfully tested with firmware versions 1.11 and 1.12 of the CC3000 chip.
For the Ethernet part, the library is compatible with the official Arduino Ethernet shield.
For the Serial part, it has been tested with the direct USB serial connection on an Arduino Uno board, with the Adafruit BlueFruit EZ-Link Bluetooth module, and with XBee Series 1 devices.
For the Bluetooth Low Energy part, the library has been tested with the Adafruit BLE nRF8001 breakout board.
The project has been tested with Chrome 33, Safari 7 and Firefox 27.
- Adafruit CC3000 Library
- Adafruit MDNS Library
- MDNS support in your operating system:
To install the library, simply clone this repository in the /libraries folder of your Arduino folder.
- Connect a LED & resistor to pin number 8 of your Arduino board
- Open the WiFi_CC3000 example sketch and modify the WiFi SSID, password & security
- Upload the sketch
- Go to a web browser and type arduino.local/mode/8/o to set the pin as an output
- Now type arduino.local/digital/8/1 and the LED should turn on
- Connect a LED & resistor to pin number 8 of your Arduino board
- Make sure your computer is connected via Ethernet to the board and has the IP address 192.168.2.x
- Upload the sketch
- Go to a web browser and type 192.168.2.2/mode/8/o to set the pin as an output
- Now type 192.168.2.2/digital/8/1 and the LED should turn on
- Connect a LED & resistor to pin number 8 of your Arduino board
- Open the Serial example sketch
- Upload the sketch
- Go to a the Serial monitor and set the options to "Carriage return" and "115200 bauds"
- Type /mode/8/o to set the pin as an output
- Now type /digital/8/1 and the LED should turn on
- Connect a LED & resistor to pin number 8 of your Arduino board
- Open the BLE example sketch
- Upload the sketch
- Use the BlueFruit LE Connect app to connect to the BLE chip
- Type /mode/8/o / to set the pin as an output
- Now type /digital/8/1 / and the LED should turn on
The API currently supports five type of commands: digital, analog, and mode, variables, and user-defined functions.
Digital is to write or read on digital pins on the Arduino. For example:
- /digital/8/0 sets pin number 8 to a low state
- /digital/8/1 sets pin number 8 to a high state
- /digital/8 reads value from pin number 8 in JSON format (note that for compatibility reasons, /digital/8/r produces the same result)
Analog is to write or read on analog pins on the Arduino. Note that you can only write on PWM pins for the Arduino Uno, and only read analog values from analog pins 0 to 5. For example:
- /analog/6/123 sets pin number 6 to 123 using PWM
- /analog/0 returns analog value from pin number A0 in JSON format (note that for compatibility reasons, /analog/0/r produces the same result)
Mode is to change the mode on a pin. For example:
- /mode/8/o sets pin number 8 as an output
- /mode/8/i sets pin number 8 as an input
You can also directly call variables that are defined in your sketch. At the moment only integer variables are supported by the library. To access a variable in your sketch, you have to declare it first, and then call it from with a REST call. For example, if your aREST instance is called "rest" and the variable "temperature":
- rest.variable("temperature",&temperature); declares the temperature in the Arduino sketch
- /temperature returns the value of the variable in JSON format
You can also define your own functions in your sketch that can be called using the REST API. To access a function defined in your sketch, you have to declare it first, and then call it from with a REST call. Note that all functions needs to take a String as the unique argument (for parameters to be passed to the function) and return an integer. For example, if your aREST instance is called "rest" and the function "ledControl":
- rest.function("led",ledControl); declares the function in the Arduino sketch
- /led?params=0 executes the function
You can define an API key to add more security to your projects, so only someone with the key can access to the devices using aREST. The authentification works only with HTTP requests (WiFi and Ethernet). You simply need to define a key in the Arduino sketch with:
- rest.set_api_key("K9gs1wbodW");
Then, you need to send this key in the HTTP header of the request:
- "X-ApiKey: K9gs1wbodW"
In case you cannot access your Arduino board via the mDNS service (by typing arduino.local in your browser), you need to get the IP address of the board. Upload the sketch to the Arduino board, and then open the Serial monitor. The IP address of the board should be printed out. Simply copy it on a web browser, and you can make REST call like:
192.168.1.104/digital/8/1