Using REST as a command protocol for web-to-serial applications

Updated 19 Jan 2014

The address you type into your browser’s address bar is often the location of a particular document on a server. For example, http://tigoe.net/index.html refers to an HTML document living in the main directory of my server, tigoe.net. But URLs can be used to represent more than a file address. They can also be used to set or get the state of web-based application. For example, http://www.mystore.com/item/3045/price could be used to tell the application you want the price of item 3045. If you want the set the price, you could use http://www.mystore.com/item/3045/price/4.99. Web frameworks like Sinatra (for Ruby), Flask (for Python) and Express (for JavaScript through node.js) make it possible for you to build a web server that uses Representational State Transfer, or REST, as the control protocol for your application.

REST is a style of formatting URLs such that the URL itself describes the state of the thing it’s addressing. In the store example above, the URL is a representation of the item in the store (http://www.mystore.com/item/3045/price).  To change the state of the item, you use another URL to represent that change (http://www.mystore.com/item/3045/price/4.99).  At its simplest, REST means organizing your web application so that the URLs provide clear, sensible meaning as to what’s going on. For a more detailed explanation, see Understanding REST or Building Web Services the REST way. In this post, you’ll learn how to use a RESTian scheme as a communications protocol between a microcontroller and a web page using node.js and a little client-side JavaScript in the middle.

This post assumes you understand:

To make this happen you’ll need:

• An Arduino, and the Arduino IDE
• An RGB LED. I used this common anode model from Adafruit, but you could make it work with a common cathode LED too, with some modification of the Arduino sketch.
• An HTML5-capable browser. I used Chrome, but Opera or Firefox or Safari will work too)
• node.js and the following libraries for node:
  • express.js
  • node-serialport
  • open

To get set up, download the project from my GitHub repository. If you’re familiar with git, just clone the whole NetworkExamples repository. If you’re not familiar with git, then download the .zip file and copy the nodeRestToSerial directory to your user directory or desktop or wherever you like to work. Then open a terminal window and change directories into the nodeRestToSerial directory you just created. Finally, to install all the necessary libraries for node, type

npm install

  // configure server to serve static files from /js and /css:
  app.use('/js', express.static(__dirname + '/js'));

// respond to web GET requests with the index.html page:
app.get('/', function (request, response) {
  response.sendfile(__dirname + '/index.html');
});

// take anything that begins with /output:
app.get('/output*', function (request, response) {
  // the route is the first parameter of the URL request:
  var brightnessCommand = request.params[0];
  // send it out the serial port:
  myPort.write(brightnessCommand);
  // send an HTTP header to the client:
  response.writeHead(200, {'Content-Type': 'text/html'});
  // send the data and close the connection:
  response.end(brightnessCommand);
});

node restToSerial.js portName

node restToSerial.js /dev/tty.usbmodem-411

You’ll get a message like this:

opening serial port: /dev/tty.usbmodem-411
Listening for new clients on port 8080

The node app will also open a browser window to show you the user interface. Don’t worry about the fact that you haven’t programmed the Arduino yet; for now you just want to see the server’s response to the client. When the server script is running, open a web browser and type

You’ll get a reply like this:

/r/45/g/67/b/123

That’s the server sending you back what you sent it. You can change the values for red, green, and blue and get different replies. The server script is also sending those values out the serial port, so now it’s time to write an Arduino sketch to read them.

Stop the server script before working on the Arduino sketch because only one application can control a serial port at a time.

The Arduino Sketch

The Arduino sketch included in the gitHub repository for this project, RGBLEDControl.ino, controls an RGB LED using three PWM pins, pins 9, 10, and 11. The image below shows the wiring; the yellow wire is for the common anode.

The sketch starts by listening for incoming serial data, and filters for the relevant characters, r, g, or b, like so:

if (Serial.available() > 0) {
    int inByte = Serial.read();

    // respond to the values 'r', 'g', 'b'.
    // you don't care about any other value:
    switch (inByte) {
    case'r':     // red
      currentPin = redPin;
      break;
    case 'g':    // green
      currentPin = greenPin;

      break;
    case 'b':    // blue
      currentPin = bluePin;
      break;
    }

Given one of those three values, it sets the value of the output pin it will control. When the sketch has a legitimate pin number to set (anything other than 0) it starts looking for a value to use to set the pin, like so:

    // if you have a legitimate pin number,
    // use the parseInt function to listen for a level:
    if (currentPin != 0){
      int brightness = Serial.parseInt();

      // map the result to a level from 0 to 255
      // note: the reversal of the output values is because
      // you're using a common anode LED, and taking one of
      // the cathodes HIGH actually turns that channel off:
      brightness = map(brightness, 0, 100, 255, 0);

      // set the brightness for this color:
      analogWrite(currentPin, brightness);
    }
  }

Any characters that come in the serial port once the pin number is chosen are parsed to see if they represent an integer using the Serial.parseInt() function. Anything that’s not an r, g, b or a numeric character is ignored.

Upload the sketch included in the repository to your Arduino. Then open the Serial Monitor and type a few commands to it, like:

/r/45/g/67/b/123

You should see the RGB LED light up accordingly. Now close the Serial Monitor and run the server script again. Then open the same URLs you opened before. You should see the LED lighting up just like when you did it from the Serial Monitor. The server script is just passing that part of the URL through to your Arduino. Neat, isn’t it?

But wait! There’s more!

The Client-Side Script

Run the server script and type in:

You’ll get a page that looks like this:

Try sliding the sliders up and down. They should change the brightness of the LEDs on your Arduino.

The sliders on this page are made using the HTML5 input range elements. There’s a little javaScript in the head of the indes.html page that uses the values of these range elements to set the text of the input elements, and to make the HTTP calls, as follows:

function setColor(ui, display) {
    display.value= ui.value;
    $.get("/output/"+ display.id + "/" + ui.value);
}

This snippet is using Zepto.js, a smaller version of JQuery, to make the HTTP calls.

The sliders call the JavaScript setColor() function when their values change. setColor() sets the value of the textbox next to the slider, and uses the value of the slider to make an HTTP GET request. This is where you’re going to set the LED. the URL for your request to the server looks like this:

The server then takes everything that follows /output and sends it out the serial port to the Arduinom where it’s used to set the LED, as you saw above.

Making a GET request from scripts within a page like this lets you perform multiple exchanges with the server just using HTTP, no websockets required. You can update elements within the page this way without refreshing the whole page. It’s handy because you can check your requests directly from the browser’s address bar, using a URL that’s easy to remember because it’s a representation of what you want to happen. It’s also good because each request is a discrete transaction. Once the request is complete, there’s no connection between the server and client, so if you lose your network connection, both sides have a representation of the state of the system when they were last connected.

Because the requests are coming from the elements within the page, though, you don’t need to refresh the whole page every time something changes. You get an interface that’s quick and responsive to the user and robust in terms of connection between the server and client. See? REST in action!