A simple library that implements a REST API for Arduino & the ESP8266 WiFi chip.
It is designed to be universal and currently supports REST calls via HTTP (using the CC3000 WiFi chip, the Arduino WiFi library or the Ethernet shield), via the Serial port (using the USB serial connection, Bluetooth, and XBee) and also via Bluetooth Low Energy. The library is also compatible with the Arduino MKR1000 board.
It also works with the ESP8266 WiFi chip using the ESP8266 processor, therefore working as an independent unit. It also works on the ESP32 WiFi chip.
Boards running aREST can also be accessed from anywhere in the world via an API available at cloud.arest.io
. Check the rest of this file and the examples ending with _cloud for more details. This currently only works with the Ethernet library for Arduino & the ESP8266 WiFi chip.
If you want to know more about aREST, go over to http://arest.io/.
The library is at the moment compatible with the following Arduino boards: Uno, Mega, Due, Yun and Teensy 3.x. It is also compatible with the Arduino/Genuino MKR1000 board.
The library is compatible with most of the ESP8266 modules & ESP8266 development boards, as well as most boards based on the ESP32 WiFi chip.
For HTTP communications, 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, with the official Arduino WiFi shield, and with the Arduino Yun via the embedded WiFi connection.
For Serial communications, the library 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 Bluetooth Low Energy communications, the library has been tested with the Adafruit BLE nRF8001 breakout board.
To use the library with Arduino boards you will need the latest version of the Arduino IDE:
To use the library with the ESP8266 WiFi chip you will need to install the required module from the Boards Manager of the Arduino IDE. These are the steps to install the ESP8266 package inside the Arduino IDE:
http://arduino.esp8266.com/stable/package_esp8266com_index.json
into the Additional Board Manager URLs field. You can add multiple URLs, separating them with commas.To use the library with the ESP32 WiFi chip you will need to install the board definitions for the Arduino IDE. These are the steps to install support for the ESP32 chip inside the Arduino IDE:
To use aREST with the MKR1000 board, you first need to install the MKR1000 board definition from the Arduino IDE board manager. You also need to install the following library:
To install the library, simply clone this repository in the /libraries folder of your Arduino folder.
arduino.local/mode/8/o
to set the pin as an outputarduino.local/digital/8/1
and the LED should turn on192.168.2.2/mode/8/o
to set the pin as an output192.168.2.2/digital/8/1
and the LED should turn on/mode/8/o
to set the pin as an output/digital/8/1
and the LED should turn on/mode/8/o /
to set the pin as an output/digital/8/1 /
and the LED should turn on192.168.1.103/mode/5/o
to set the pin as an output192.168.1.103/digital/5/1
and the LED should turn oncloud.arest.io/47fd9g/mode/8/o
to set the pin as an outputcloud.arest.io/47fd9g/digital/8/1
and the LED should turn oncloud.arest.io/47fd9g/mode/5/o
to set the pin as an outputcloud.arest.io/47fd9g/digital/5/1
and the LED should turn onThe 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 inputYou can also directly call variables that are defined in your sketch. Integer variables are supported by the library. Float and String variables are also supported, but only by the Arduino Mega board & by the ESP8266.
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 formatYou 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 functionYou can also directly tell your board to log data on our cloud server, to be stored there & retrieved later or displayed on the aREST cloud dashboard. This is useful when you want for example to record the data coming from a sensor at regular intervals. The data is then stored along with the current date, the ID of the device sending the data, and also an event name that is used to identifiy the data. This can be done via the following commands:
rest.publish(client, "temperature", data);
logs the value of data
with the event name temperature
https://cloud.arest.io/47fd9g/events
retrieves the last events logged by the device 47fd9g
You can also access a description of all the variables that were declared on the board with a single command. This is useful to automatically build graphical interfaces based on the variables exposed to the API. This can be done via the following calls:
/
or /id
To know the activity of the library while the sketch is running, there is the possibility to connect a LED to a pin to show this activity in real-time. Simply connect a 220 Ohm resistor in series with a 5mm LED to the pin of your choice, and enter this line in the setup() function of your Arduino sketch:
rest.set_status_led(led_pin);
There is the possibility to use a lightweight mode for aREST. This means that for commands to control the Arduino board (like digitalWrite commands), no data is returned at all. For commands that ask for data to be sent back (like asking for a variable), in this mode the library will only return the value of the data that was requested.
This mode was made for cases where the memory footprint of the aREST library has to be as small as possible, or with devices that can't send/receive a lot of data at the same time, like Bluetooth LE. To enable this lightweight mode, simply start your sketch with:
#define LIGHTWEIGHT 1
In case you cannot access your Arduino board via the CC3000 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
This project exists thanks to all the people who contribute. [Contribute].
Thank you to all our backers! 🙏 [Become a backer]
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]