Arduino Rest API is a mechanism to exchange data between Arduino and other external systems. Using Arduino Rest API framework it is possible to control Arduino remotely. The convergence between API and IoT opens new integration scenarios. The development of an API ecosystem is an interesting topic and the way we access to IoT service, exposed by remote IoT boards, using API is a challenging aspect.
In more details, exploiting Arduino Rest API a client application reads or sends information to Arduino board. A typical use case of HTTP Rest API is an external system or application that retrieves sensor values. Arduino Rest API framework can be used in IoT projects when different systems and boards are connected together and exchange information. Even IoT cloud platforms use the Arduino Rest API mechanism. Generally speaking, this kind of mechanism is useful when an external application (client) sends a request to Arduino and it replies with some data. Arduino Rest API works over HTTP protocol so this kind of requests are synchronous. In IoT applications, there are other protocols that can be used like MQTT. Arduino API over HTTP plays an important role in a client-server scenario where Arduino acts as a server. MQTT, for example, uses a different pattern like publish-subscriber.
If you are new to the Internet of things and want to get started building your first IoT project, I suggest you read how to send sensor data to Google sheet using Arduino.
The video below shows the final result. Using a browser we are able to control Arduino:
Arduino Rest API framework: aRest library
To implement a Rest API framework there is an interesting library called aRest. This library is a framework that supports Restful services and provides several interesting features. This library supports different dev boards like Arduino, Raspberry, ES8266. You can find more information on aRest website.
This library is simple to use and can be downloaded directly from the Arduino library through Arduino IDE.
Using this library we can implement the API because of aRest support:
- reading pin values in rest style
- writing pin values in rest style
- Remote sketch function call
For example, an external application or system can read the Arduino pin value using a simple HTTP request. Moreover, the same app or system can set the pin value using an HTTP Rest request. This is useful when we have an app that runs on a smartphone that wants to interact with Arduino board. This interaction takes place exploiting Arduino Rest API.
One interesting aspect of aRest library is the capability to expose the Arduino sketch function in a Rest style. These sketch functions are called directly using a Rest HTTP request. Let us see how to use HTTP API in practice with Arduino.
Arduino Rest API implementation
Now we know the basic concepts and how to use it to integrate Arduino with an external system, it is time to describes how to put it into practice. In this example, we want to control a LED strip using Rest API calls. The sketch is simple because we have to focus on the Arduino Rest API. The LED strip is Neopixels RGB Stick Board and using the Adafruit library is possible to select the single RGB led color. The sketch below shows how to wire it to Arduino UNO.
This picture uses different Neopixel components but the connections are the same.
If you want to know more about Arduino and API you can read:
- Integrate Arduino and Android
- How to invoke HTTPS Rest services using ESP8266
- How to implement a Rest server using ESP32
Using Rest JSON API request, we want to set the led strip color. The color is passed to the sketch function as a parameter in HEX format. This example demonstrates how powerful is this library. The Arduino code is simple:
// Create aREST instance
aREST rest = aREST();
// NeoPixel Init
Adafruit_NeoPixel pixels = Adafruit_NeoPixel(NUMPIXELS, PIN, NEO_GRB + NEO_KHZ800);
void setup() {
Serial.begin(115200);
// Register RGB function
rest.function("rgb", setPixelColor);
Serial.println("Try DHCP...");
if (Ethernet.begin(macAdd) == 0) {
Serial.println("DHCP FAIL...Static IP");
Ethernet.begin(macAdd , ip, myDns, myGateway) ;
}
server.begin();
Serial.print("server IP: ");
Serial.println(Ethernet.localIP());
pixels.begin();
Serial.println("Setup complete.\n");
}
void loop() {
// listen for incoming clients
EthernetClient client = server.available();
rest.handle(client);
wdt_reset();
}
int setPixelColor(String hexColor) {
hexColor="0x" + hexColor;
Serial.println("Hex color " + hexColor);
long n = strtol( &hexColor[0], NULL, 16);
Serial.println("N :" + String(n));
long r = n << 16;
long g = n << 8 && 0xFF;
long b = n && 0xFF;
// set single pixel color
return 1;
}Code language: JavaScript (javascript)The Arduino function that we want to make available as Arduino HTTP Rest API is setColor. So the sketch registers it at line 36 calling it rgb.
Let’s run the sketch on Arduino UNO board and make a simple HTTP request using the browser. Let us suppose we want to set the red color, the result is shown below:
http://192.168.1.5/rgb?param=_FFFF00Code language: JavaScript (javascript)These are some screenshots with different led colors, controlled by HTTP requests from a browser.
If you have an ESP32, you can read how to implement API Server with ESP32. If you want to see the APIs in action you can read this tutorial covering how to use computer vision with ESP32-CAM using API.
Wrapping up
At the end of this tutorial, you gained the knowledge about how to use Arduino Rest API to send and receive data from Arduino using Rest style requests. You can further extend this project by implementing new features. You can apply the same paradigm to other kinds of IoT boards like ESP8266 and so on. In this example, we have covered how to send data to Arduino invoking an Arduino Rest API, but you can use the same mechanism to read Arduino pin values.
