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

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

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 restToSerial directory to your user directory or desktop or wherever you like to work. Then open a terminal window and change directories into the restToSerial 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'));
  app.use('/css', express.static(__dirname + '/css'));

// 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

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. It 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 jQuery-ui, an extension of the popular jQuery client-side JavaScript framework, that’s good for making UI elements. If you look at the index.html page included in the project repository, you’ll see DIV elements for each of the sliders and their text values. The CSS in the head of the index page sets the positions of these elements, and the colors of the text elements. The JavaScript making it all happen, though, is in the /js directory. It’s called sliders.js.

In sliders.js, there’s a function that defines each slider that looks like this:

$(function(){
   $('#redSlider').slider({
      orientation:'vertical',
      range: 'min',
      value: '0',
      stop: function( event, ui ) {
         $.get(
            "/output/r/" + ui.value,
            function(data) {
                $("#redLabel").html(ui.value);
            }
         );
      }
   });
});

If you’re not used to JavaScript, this can be hard to read. So here’s a breakdown: the slider() function from jquery-ui defines each slider. You pass it the ID of the DIV element in the HTML document where you want that slider. In this example, it’s the DIV called #redSlider. The one parameter for the slider() function is a JSON object defining the slider. You need to give it a bunch of parameters: the orientation, the range, the initial value, and a function to run when it stops, starts, or moves. In this case, you’re only adding a function for when it stops.

When the slider stops, it calls a function you’re giving it to make a HTTP GET request. This is where you’re going to make the call to set the LED. That GET function also needs some parameters: the URL you want to get from the server (/output/r/ + whatever the slider’s value is) and the function you want to run when the GET request is complete. In this case, when the request is complete, you set the DIV called #redLabel with the value of the slider.

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!