Chapter 4 💨

Firmata

In this chapter we look at the communication layer between the Arduino and the WebSocket Server.

Serial

The simplest way to send messages between your Computer and the Arduino is to use a serial stream over USB. Wikipedia describes serial ports like this:

“… a serial port is a serial communication physical interface through which information transfers in or out one bit at a time (in contrast to a parallel port).
Throughout most of the history of personal computers, data transfer through serial ports connected the computer to devices such as terminals and various peripherals. While such interfaces as Ethernet, FireWire, and USB all send data as a serial stream, the term serial port usually identifies hardware more or less compliant to the RS-232 standard, intended to interface with a modem or with a similar communication device.”

When developing applications for your Arduino you can use the Serial library to send messages to the Arduino IDE console.

Node.js has a library, called “node-serialport” that can be used to connect to devices connected to the USB port (or any other port that supports the RS-323 standard).

Node-SerialPort

Node-serialport is easy to install and configure but it means that you would need to write all communication methods by hand. For example, if you want to tell the Arduino to turn on a lamp. You need to send a message to the Arduino (in text). On the Arduino you would write a for-loop that looks at the serial buffer and stores all the parts of this message until you receive a end of line instruction that tells you that the entire message is now transmitted. You then have to write a lookup table, that does different things, depending on what the message says. This can quickly become a bit of a pain when you are writing large Arduino programs that need to communicate a lot with the webSocket server.

Lucky for us however, there is a protocol we can use that takes care of the Arduino and Serial side for us. This protocol is called Firmata.

Firmata

“Firmata is a generic protocol for communicating with microcontrollers from software on a host computer.” The way this works, is that you install the Firmata software on your Arduino. You can now control the Arduino by sending it Firmata instructions over the Serial port. There are Firmata implementations available in most languages.
The Firmata library for Node.js is called Firmata. If installed you can use to send instructions directly to your Arduino. This means that you now handle all your Microcontroller-logic directly from your Node.

This means that you eventually end up with a cleaner code base, where everything from, Arduino-, Socket-, Server- and Client-code is written in JavaScript. Cool, right!?

To illustrate how Firmata works, let's install the software on your Arduino and run a couple of tests:

  1. Connect your Arduino the the computer.
  2. Open the Arduino IDE and locate the example sketch called “Standard Firmata”.
    File > Examples > Firmata > StandardFirmata
  3. Install the Standard Firmata to your Arduino. (Upload)
  4. Go to firmata.org and download the “Firmata Test Program”.
  5. In order for the test program to connect to the Arduino, you need to select the right serial port first. Port > cu.usbmodem… (Pick the one your Arduino is connected to)
  6. If the program is able to connect to the firmata software connected to the port, it will load the interface.
  7. To see if everything works fine, select pin 13, and set it to "Output" and "High".
  8. You should now see the small reference light (located next to pin 13) on your Arduino, light up.

Node.js & Firmata

Before we can start programming our Arduino from Node.js we need to install Firmata via npm. The Firmata installer will also install the node-serialport library since it depends on it for serial communication.

IMPORTANT: In order for the node-serialport library to install successfully on OS X, your system needs to have a working C compiler installed. This means that you at least need to have the “Xcode command line tools” installed. You find this tool at: https://developer.apple.com/downloads

Download example file

  1. Open the terminal and navigate to the “firmataOnNode” folder you just downloaded.
  2. Type “npm install firmata” To install the firmata library.
  3. Check if the firmata library has been added to the node_modules folder.
  4. Once again to save you some time I have already prepared a little script. This script is called “firmataConnector.js”.
  5. Open the “main.js” file. To add the connector script, you need to add the following code:
    
    // Firmata
    var serialPort = '/dev/tty.usbmodem1411';
    var arduino = require('./firmataConnector').start(serialPort);
                             
    (You will need to rename the serialPort variable to the name of the port your Arduino is connected to. You find this information in the bottom-right corner of the Arduino IDE)
  6. The firmataConnector script will simply connect to the Arduino and call a “connection” event when the connection is established. To listen for the connection call add the following code to “main.js”.
    
    arduino.on('connection', function () {
        
        console.log("successfully connected to the Arduino!");
    });
                             
  7. To test the script, type “node main.js” in the Terminal.

Controlling the Arduino from Node

The following code example should give a good insight on how to program the Arduino from node.


"use strict";

/**
 * Firmata demo
 *
 * For full API overview and examples go to:
 * https://github.com/jgautier/firmata
 */
 
 
// Connect to the Arduino
var serialPort = '/dev/tty.usbmodemfa141';
var board = require('./firmataConnector').start(serialPort);


board.on('connection', function () {
    
    
    /**
     * Digital write
     */
     
    board.pinMode(13, board.OUTPUT);
    
    board.digitalWrite(13, board.HIGH);
    
    
    /**
     * Analog write
     */
     
    board.pinMode(11, board.PWM);
    
    board.analogWrite(11, 200);
    
    
    /**
     * Analog read
     */
    board.analogRead(board.A0, function(val) {   
        
        console.log(val);
    });
    
    
    /**
     * Blink the led
     */
    var isOn = true;
    
    setInterval(function () {
        
        if(isOn) {
            board.digitalWrite(13, board.LOW);
            isOn = false;
        }else{
            board.digitalWrite(13, board.HIGH);
            isOn = true;
        }    
    }, 
    1000);
});
                         

There are a couple of differences between programming an Arduino via Firmata and programming it from the Arduino IDE.
First of all, your program does not run on the Arduino. It runs on the server and communicates with the Arduino. Using a serial stream might introduce a small delay/lag to your program. Generally this is not the case since this truly is a small amount of lag but it is worth pointing out.
If you disconnect the Arduino from the server. The Arduino will not keep on running on its own, since it does not get new instructions from the server.

The firmata protocol requires you to set the pin mode to either:

In the Arduino IDE you only have have INPUT or OUTPUT. ANALOG, PWM, SERVO are determined automatically based on the operation you tell the pin to perform. The the board object returned by the “firmataConnector.js” already provides shorthands for this. You can for example write, arduino.pinMode(arduino.INPUT);

The firmataConnector also gives you a simple way to connect to your analog pins through
the use of board.A0 - board.A5.

To get a bit more familiar with the the firmata protocol. You should write the following programs.

  1. Create a program that turns a LED, connected to pin 11 on.
  2. Read the X and Y values of a joystick module.
  3. Use the analog values from your joystick module to dim the light.

Tip: The board object returned by the firmataConnector has a costume log function that can be used to log data to the same line over time. This can be handy if you have a lot of data you want to log without it filling up your console to much. Arduino.lineLog(“text”);

Note that the board object returned by the firmataConnector is based on the board object you would normally receive from the Firmata for Node.js library. Hence you can call all standard APIs as documented on:
https://github.com/jgautier/firmata

Conclusion

And that puts the last pieace in place.
In the past 3 chapters, we looked at Microcontrolers, WebSockets, and the Firmata protocol to connect the two together. In the next chapter we will put everything together to build the server lightbulb device.