The Blink Sketch

To blink an LED, you have to run a “sketch” on the Arduino. An Arduino sketch hides a lot of the complexity from a microcontroller. The Arduino IDE comes with a number of sketch examples to learn embedded development. Writing, building, and uploading a Blink sketch will give you a first feeling of how microcontrollers work.

If you create a new Arduino sketch, you’ll see the following basic code structure:

void setup() {
}

void loop() {
}

These two functions are the foundation of every Arduino program. The setup() function is where you put code to configure the hardware and initialize variables. This function will only run once when your Arduino is turned on. The loop() function is where the the “main” program goes. We’ll see shortly how this looks for a blinking LED. Note that most Arduino boards have an LED connected to pin 13, which you can easily toggle for testing.

The separation of code into setup() and main loop() is common in the embedded world. First, you’ll have a function to configure your microcontroller and peripherals. Then follows an infinite loop, where different instructions are executed. The code in the infinite loop is repeated as long as the device has power. To make an LED blink with an Arduino forever, you would use the following:

void setup() {
    // initialize the digital pin as an output.
    pinMode(13, OUTPUT);
    }

void loop() {
    digitalWrite(13, HIGH);  // turn LED on
    delay(1000);             // wait for a second
    digitalWrite(13, LOW);   // toggle LED
    delay(400);              // wait 400 ms
    }

While keywords such as void are part of C, Arduino programs contain more keyword-like commands such as pinMode, delay, and digitalWrite as just shown. These commands are part of a hardware abstraction layer (or HAL) Arduino provides to hide the lower-level complexities of a microcontroller. No matter which Arduino board you use, these statements are properly translated to pin configurations. By the way, pinMode configures the mode of a pin (i.e., if it is an input or output). If a pin is configured as output, you can write state with digitalWrite. If the pin is an input, you can read state with digitalRead.

Note the name of the instructions to change the state of pins. The Arduino nomenclature has made its way into some JavaScript libraries, as you will see shortly. Before examining how, let’s see the Arduino example in action.

A look at the Arduino IDE (shown in Figure 2-4) quickly reveals two functions: a “verify” button that compiles C and C++ to byte sequences that a microcontroller can run and an “upload” button that places your code in the free program memory of a microcontroller (ROM).

Figure 2-4. The Arduino IDE

If you have an Arduino and press the compile button, in the console you will see:

Sketch uses 1,030 bytes (3%) of program storage space. Maximum is 30,720 bytes.
Global variables use 9 bytes (0%) of dynamic memory, leaving 2,039 bytes for
  local variables. Maximum is 2,048 bytes.

This shows how compact the code is. The code will use only 1 KB of flash memory. And, only 9 bytes of RAM are necessary!

Next, you can press the upload button. After a brief wait while the device is flashed, you will see LED 13 blinking, as shown in Figure 2-5.

Figure 2-5. The default LED to blink on the Arduino Uno

Similarly, you could explore using input pins or different forms of output signals. We’ll discuss more features of microcontrollers later. Let’s first look at controlling an Arduino with JavaScript.

Programming an Arduino with JavaScript

Once you have checked your connection to an Arduino with a Firmata test client, you can bind a JavaScript process to your board.

To talk with Firmata from JavaScript, you can use the Firmata library, originally written by Julian Gautier and currently maintained by Rick Waldron.

In a new project, you can start with:

$ npm init --y
$ npm install --save firmata

With this library, we can connect to input and output pins.

Let’s look at a blinking LED again:

// blink_led.js
// the Firmata protocol provides a simple protocol to an embedded system
var Board = require('firmata');

Board.requestPort(function(error, port) {
  if (error) {
    console.log(error);
    return;
  }
  var board = new Board(port.comName);

  // start to blink when the Arduino is ready
  board.on("ready", function() {

    // main part
    console.log('connected:  ' +  modem);
    var ledOn = true;

    // configure pin 13 as output
    board.pinMode(13, board.MODES.OUTPUT);
    // blink the LED
    setInterval(function() {
      if (ledOn) {
        console.log('ON');
        board.digitalWrite(13, board.HIGH);
      } else {
        console.log('OFF');
        board.digitalWrite(13, board.LOW);
      }
      ledOn = !ledOn;
    }, 500);
  });

To blink the LED, run the preceding script with Node.js:

$ node blink_led

If everything worked, you should see the LED turning on and off. This is also a good moment to compare the differences in code expressed in terms of Arduino and JavaScript.

In the JavaScript example, you get a board object, where you can listen to events from the hardware. For the blink example, you first wait until the board emits the “ready” event (the connection works properly). Once this happens, you can change the state of the board with functions using digitalWrite and pinMode. You could easily interact with the JavaScript board object in a web server or web interface too (we’ll discuss how to do this in Chapters 9 and 10).

Pins

Pins of an MCU come in two categories: inputs and outputs. A pin can either “drive” signals to peripherals and components, or it can “detect” changes from the outside.

Inputs and outputs are technically quite different. While inputs are all about capturing the state of signals, outputs can drive current into components. Because Arduino boards are capable of driving several milliamperes of current, they’re a good fit for controlling small actuators such as motors or lights.

Besides acting as “force” (output pin) or “sink” (input pin), pins carry analog or digital signal types (see the following sidebar for details on how this works).

When writing embedded software, the first step is to locate and configure the pins of the microcontroller. For example, an Arduino Uno has 5 analog inputs and 13 digital pins known as general-purpose input/outputs (GPIOs). Of these 13 GPIOs, 5 pins can emulate an analog output with the help of pulse-width modulation (PWM), as will be discussed in “Pulse-Width Modulation”.

On an Arduino, you first configure the direction of a pin. To read data from it with software, you must configure the pin as input. With Arduino and Firmata, if you want GPIO pin 12 to be an input, you would configure it as follows:

board.pinMode(12, board.MODES.INPUT);

Or, to write data to another device, you can configure another pin as output:

board.pinMode(12, board.MODES.OUTPUT);

On an Arduino, toggling a digital pin to a high voltage is done with:

board.digitalWrite(13, board.HIGH);

To write a low voltage, you would write:

board.digitalWrite(13, board.LOW);

Besides simple inputs and outputs, port pins often provide more functions. This means you not only can read a digital state, or write it, you can also start up special forms of communication, such as PWM and hardware communication protocols.

When different resources on a chip use the same port pins, we are referring to “multiplexing” pin functions. The way this works is defined by the chip architecture of a microcontroller defines how multiplexing works. Let’s dig into the building blocks of a microcontroller starting with its CPU.

Microcontroller Versus Microprocessor

On top of providing pins for building circuits, microcontrollers can run programs with the help of a CPU. The datasheets for a microcontroller provide all the details, and the following specs are of particular interest:

• The amount of memory (volatile and nonvolatile) to store variables and code

• The type of instruction set to execute code and operations with variables

• The timers to change pin states with high timing accuracy

• The power consumption at a certain operating frequency

Compared to the CPU of a bigger computer, these parameters make a microcontroller nice for embedded systems on a battery. Moreover, the costs of microcontrollers can be significantly lower than those of microprocessors (though microprocessors are becoming cheaper due to high volume demands).

However, microcontrollers also have disadvantages. In particular, their performance for computations can be a problem. If you want to connect a microcontroller to a network, or if you want to run a web server or database, this is where microprocessors become very interesting.

Microprocessors (MPUs) have many more pins, more memory, and much more power for computations. The boundaries between MCU and MPU are not always clear, but you will usually have to deal with some tradeoffs when chosing a board with a microcontroller or microprocessor.

In earlier code examples, we worked with a number of functional blocks of a microcontroller. As you can see from the block diagram, Arduino provides several hardware abstractions.

Let’s look a bit deeper into the structures and functions of the main building blocks of an Arduino Uno: the Atmel ATmega328 microcontroller.

Block Diagrams

To understand how the software in the microcontroller blinks the LED, let’s look at the block diagram of the ATmega328 microcontroller, shown in Figure 2-8. In general, understanding functional block diagrams is important when developing software for embedded devices.

The block diagram in Figure 2-8 shows the typical building blocks of a microcontroller. The CPU of the ATmega328 has an 8-bit instruction set. Instruction sets provide operations around which programmers build programming languages and compilers.

The code and data are stored in different forms of memory. In Figure 2-8, the memory is shown in the upper-right part. “Flash” generally means slow, nonvolatile memory, and SRAM means fast but volatile memory. You generally store programs in flash, while the RAM at runtime of a program is stored in SRAM.

Besides these building blocks, what is interesting from a software perspective are the interfaces of the microcontroller. These are all the arrows that come out and go in on the bottom and left—for example, the ports.

Figure 2-8. A functional block diagram of the datasheet from the ATmega 328 microcontroller

With GPIOs, it is possible to read and write data. From the block diagram, you can see that an Atmel MCU has GPIOs that are organized in three ports: Port B, Port C, and Port D (seen near the bottom of Figure 2-8).

So-called “peripherals” are also important for communication and sensing the outside world. Some peripherals act as input and output ports. Timers can measure the time between stop and start events. And, analog-to-digital converters can convert continuous analog signals into bits and bytes for digital processing.

The ATmega328 Atmel chip multiplexes the following blocks to the ports:

Port D provides USART and UART

Many embedded devices must transfer data from one side to another. One kind of serial data transfer uses a Universal Synchronous Asynchronous Receiver/Transmitter (USART). This peripheral function drives data bits from a sender to a receiver via two wires and an extra clock line. One variation on USART is called UART (Universal Asynchronous Receiver/Transmitter). In this form, a clock can be generated on the devices, and there is no need for an extra clock line. We’ll discuss serial communication in several places throughout the book.

Port B provides SPI communication

Serial peripheral interface (SPI) is another approach to communicating between devices. SPI connects devices in a “master” and “slave” fashion.² This means one device controls the communication flow. This kind of communication is a relatively fast form of serial communication. The SPI protocol requires four signals for communication. Since it always uses a clock line, the communication happens synchronous.

Port C provides TWI

The ATmega328 includes another form of serial communication called a two-wire interface (TWI). It is more commonly known as I2C (“i squared c”) and is popular for slow communication with sensors or displays. I2C uses one line for a clock signal, which means that I2C communication also happens synchronous.

Most communication modes are directly supported by JavaScript libraries. Serial communication is very common for many use cases. A JavaScript library for serial communication will be discussed in Chapter 8. Let’s continue with pins that are important to sense the physical world around us.

Analog Inputs

Looking at the building blocks in Figure 2-8, we can see a rectangle “A/D conversion.” Not all pins on the Arduino support reading analog values, only pins A0 to A5. The analog input block provides a number of “channels” to measure the physical environment with sensors.

In the Arduino language, these pins read a variable (“analog”) voltage and report that value as a 10-bit number representing 0–5V. An analog value has a “continuous” value in a range, so it does not represent a state. The range is represented by a resolution with bits—for example, a 10-bit A/D converter has 2¹⁰ different values, or 1024 values (in hex values the range would be 0x00–0x3ff).

The simplest approach to understanding what happens when reading an analog input is with a potentiometer.

If you connect a potentiometer to analog input A0 as shown in Figure 2-9, you can read the analog voltage on the input pin with:

board.analogRead(0, function(data) {
  console.log(data);
});

Figure 2-9. Potentiometer connected to analog input A0

You could influence the delay of the blinking LED on an Arduino as follows:

// analog_read.js
// load firmata dependency
var Board = require('firmata');

// pin definitions
const LED = 5;
const POT = 0;

// init variables
var ledOn = 0;  // whether LED is ON or OFF
var delay = 0;  // blink delay

// make connection
Board.requestPort(function(error, port) {

  if (error) {
     console.log(error);
     return;
  }

  var board = new Board(port.comName);

  // wait for connection
  board.on("ready", function() {

    function blink() {
      board.digitalWrite(LED, ledOn);
      ledOn = !ledOn;
      setTimeout(blink, delay);
    }

    // update variable
    board.analogRead(0, function(d) {
      delay = d;
    });

    blink();
  });
});

Often, you need to scale the input range of a sensor, or as in this example, the potentiometer (POT). In this case, the value from the analog pins returns a value between 0 an 1023. This values affects the delay for blinking.

When the blink delay is below 100 ms, the human eye cannot perceive the blink of the LED anymore. To map the blink delay to a range that can be seen by the human eye, you use a “map” function. The function from Arduino map can be rewritten in JavaScript as follows:

function map(x, in_min, in_max, out_min, out_max)
{
    return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
}
// e.g. map(value, 0, 1023, 400, 1600) --> maps a value in a range from 400 to 1600

Now, the full variable blink example reads:

// map_example.js
var Board = require('firmata');

// pin definitions
const LED = 5;
const POT = 0;

// init variables
var ledOn = 0;  // whether LED is ON or OFF
var delay = 0;  // blink delay

function map(x, in_min, in_max, out_min, out_max)
{
    return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
}

// make connection
Board.requestPort(function(error, port) {

  if (error) {
     console.log(error);
     return;
  }

  var board = new Board(port.comName);

  // wait for connection
  board.on("ready", function() {

  function blink() {
    board.digitalWrite(LED, ledOn);
    ledOn = !ledOn;
    setTimeout(blink, delay);
  }

  // update variable
  board.analogRead(0, function(d) {
    delay = map(d, 0, 1023, 400, 1600);
  });

      blink();
    });
  });

If you turn the knob of the potentiometer to the left, you get a minimum blink delay of 400 ms. If you turn the knob to the right, the delay will be 1.6 s.

Pulse-Width Modulation

In many projects, you not only have the requirement to sense the environment, you will also need to change the environment. This is what actuators are about. An actuator can be a motor, a loudspeaker, or again, the blink of an LED.

Actuators respond to signals with different forms. Pulses with different widths are especially common. This modulation scheme is called pulse-width modulation (PWM). As you can see in Figure 2-10, you specify the percentage of the time that the signal is high, also known as the “duty cycle.” This results in an often uneven square wave, as the pin approximates a percentage of the full signal by quickly toggling how long the signal is on versus off within a short period.

Figure 2-10. Pulse-width modulation; play with it here http://embeddednodejs.com/pwm

To generate PWM signals, a microcontroller often can often reuse exisiting blocks, such as GPIO and internal timers on the chips.

The mechanism behind PWM is as follows: an internal timer on the MCU sets the state of a pin to HIGH for a certain time, and LOW for the rest of a cycle. On average, the output is an analog voltage between ground and the supply voltage. This approximates an analog value and works fine for slow actuators. If you want fast-changing analog signals, such as needed for good quality audio, you’ll need to explore the use of digital-to-analog converters (DACs). Unfortunately, simple Arduinos don’t have DACs onboard.

Let’s now get some practice using PWM to fade an LED. The Arduino example “fade” can be translated to JavaScript as follows:

// analog_write.js
var Board = require('firmata');

// led pin
const LED = 5;

var brightness = 0;
var fadeAmount = 5;
Board.requestPort(function(error, port) {

if (error) {
   console.log(error);
   return;
}

var board = new Board(port.comName);
board.on("ready", function() {

// configure pin as PWM
board.pinMode(LED, board.MODES.PWM);

// fade the LED every 30 ms
function fadeLed() {
  brightness += fadeAmount;

      if (brightness == 0 || brightness == 255) {
        fadeAmount = -fadeAmount;
      }
      board.analogWrite(LED, brightness);
      setTimeout(fadeLed, 30);
    }
    fadeLed();
  });
});

A small warning: not every digital pin has access to a timer/counter. So, not every pin is able to drive a PWM output. On an Arduino, there are usually six pins with PWM functionality. These pins are commonly marked with a tilde.

Pinouts

Because reading functions of pins in datasheets is a time-intensive process, so-called pinout diagrams—like the one shown in Figure 2-11—help visualize pin functions.

While datasheets provide many details of what is going inside a chip, software developers are mostly interested in the interfaces of chips. To make writing embedded software easier, pinouts are a handy way to look up the names or locations of pins.

Figure 2-11. An Arduino Uno pinout that shows the location and functions of pins (http://www.pighixxx.com/test/pinouts/boards/uno.pdf)

From this pinout, we quickly get an overview of the different pin functions. In addition to the pin mapping that Arduino libraries use, you’ll see the name of the lower-level name and function from the datasheet. For example:

Arduino Pin 9 | Physical Pin 15 | Port B | Output/Compare/Timer 1

For beginners of embedded development, consulting a pinout can be simpler than reading dense datasheets. Later, when you get more familiar with a microcontroller, you can explore the alternative functions of pins in a pinout or datasheet.

PighiXXX provides pinout diagrams for a number of popular Arduino boards.

Command-Line Interface

Install Tessel 2’s CLI with:

$ npm install -g t2-cli

Then plug in your Tessel 2 to your computer using USB. If you are using the Tessel 2 for the first time, the starting tutorial is a good place to learn about the setup. You should give your Tessel 2 a name and allow provisioning from the computer that you use for development.

To check that your Tessel 2 is connected properly, you can type:

$ t2 list

Let’s start a fresh project to blink an LED. In the directory where you want to work (perhaps make a new folder), type:

$ t2 init

This fills out the folder on your computer with a standard Node package.json and a file called index.js that contains the blinking LED example.

Here’s the simplest version of a blinking LED example on Tessel 2:

// import the interface to Tessel hardware using the standard Node "require"
var tessel = require('tessel');

// blink!
setInterval(function () {
  tessel.led[2].toggle();
}, 100);

That’s it! Requiring “tessel” in Node.js gives you access to the JavaScript API for the board’s hardware. With the help of the tessel JavaScript library, you get objects and functions that can be performed on hardware such as an LED (see the full hardware API at https://tessel.io/docs/hardwareAPI). You can toggle this LED object. Internally, the Tessel firmware maps the LED name to a path in the OpenWRT filesystem.

To make this code run on Tessel 2, run the following command:

$ t2 run index.js

After you press Enter, you will see the following output:

INFO Looking for your Tessel...
INFO Connected to hellotessel.
INFO Building project.
INFO Writing project to RAM on hellotessel (3.072 kB)...
INFO Deployed.
INFO Running index.js...
I'm blinking! (Press CTRL + C to stop)

The t2 run command tells your computer to find your Tessel (either over USB or over your LAN), gain root access, copy over any necessary files from your directory, and then run your entry point file.

One of the LEDs on your Tessel 2 should now be blinking!

You can push the code over more permanently. Instead of t2 run, you can write:

$ t2 push

With this command, you can keep the same code between power cycles. This lets you unplug your Tessel and change it to a different power source, such as a battery.

You can also reprogram your Tessel while it is connected to a battery, as long as you are authorized (with the t2 provision command) and connected on the LAN.

You can also log in to your Tessel 2’s Linux filesystem with the command:

$ t2 root
INFO Looking for your Tessel...
INFO Connected to hellotessel.
INFO Starting SSH Session on Tessel. Type "exit" at the prompt to end.

BusyBox v1.23.2 (2016-04-07 13:52:07 EDT) built-in shell (ash)

Tessel 2  /  Built on OpenWrt
root@hellotessel:~#

From here, you can explore the OpenWRT filesystem. Also, if you need to debug a setup, root access to the Tessel 2 can be helpful. An extended list of commands is available at https://gist.github.com/flaki/a1efdb438292dd8c56c3.

Another very useful function is to turn the Tessel 2 into a WiFi access point:

$ t2 ap -n SSID -p PASS

Using this method, you can manage multiple edge devices with a single Tessel 2.

Digital Pins

On a Tessel, pinMode configuration (input vs output) happens implicitly whether you read or write to a pin. Take a look at this example in JavaScript:

var tessel = require('tessel');

var pin0 = tessel.port.B.pin[0];
var pin1 = tessel.port.B.pin[1];

// pin0 acts as output when you write data to it
pin0.output(1);

// pin1 acts as input when you read data from it
setInterval(function () {
  pin1.read(function(err, val) {
      console.log(val);
  });
}, 600);

Writing to pin0 is done with the function pin0.output(…). Reading digital data is done with pin1.read(…) pin functions.

Analog Pins

To work with analog signals, you can use analogRead(…) and analogWrite(…).

pin.analogRead(function(error, value) {
  console.log(value);
});

This can be used easily for fading an LED with a potentiometer, as was shown in earlier chapters.

For writing an analog value there, use analogWrite(…). However, analog write can only be used on Pin 7 of Port B currently.

Working with SD Cards

To run Node.js inside a board, you may have to prepare an SD card with an operating system and Node.js first. This is true for Raspberry Pi, Beaglebone, Upboard, and Intel Edison, among others. Let’s look how this is done, and why it is needed.

Most boards require micro SD cards. With an adapter (shown in Figure 6-7), you can easily use the card in older (nonmicro SD) card readers or a Raspberry Pi model A too. It is a good idea to buy several SD cards of 4 GB or more from eBay so you can experiment easily with different settings and operating systems.

Figure 6-7. An SD card with adapter

Once you have the cards, you must download the image of an operating system.

When using a Raspberry Pi, you can download a Debian image. For Raspberry Pi, there are many articles that discuss how to install the image. For example, good instructions can be found here.

When using an Intel Edison or Galileo, you can download the “IOT Kit SDK Image” from Intel.

Using a terminal or archive program, you can extract the image to a temporary location. To burn an image onto the SD card, you can copy blocks 1:1 from the source file to a destination drive.

When you are on Linux or Mac OS X, you can do this by using the dd command. You may need to check the location of your SD card in the filesystem and unmount it first. On a Mac, this can be done with:

$ diskutil list
$ diskutil unmountDisk /dev/diskN

N is the location of the card, such as 1, 2, or another drive.

Then, copy the image over to the SD card:

$ sudo dd if=iot-devkit-YYYYMMDDHHMM-mmcblkp0.direct of=/dev/disk1 bs=8m

Note that you copy the image directly onto the drive, not to a partition. This is important in order to obtain a card that can boot. bs specifies the “blocksize” for the copy process. Generally, an 8 MB block provides a good compromise between quality and speed of the copying process. Note that on some machines you must use a capital “M” for this (e.g., bs=8M).

Now that you have a board where we can install and run Node.js, let’s review the role of the operating system.

Embedded Linux Distributions

There are different Linux distributions. One main parameter in choosing an operating system distribution is its size.

If you prepare an SD card for an Intel Galileo and boot from it, you’ll see all kinds of processes running, as shown in Figure 6-8.

Figure 6-8. Booting a Galileo with the SD card image

Once an operating system is loaded, it manages the board’s resources, including disk space, memory, and computing capacity.

When you then run a web server or a logger process for temperature, for example, you request resources from the operating system at different levels. Hardware resources are managed inside a “kernel.” In Linux, these resources are mounted in the filesystem with “drivers” or “kernel modules.”

In addition to providing better management of computing resources, operating systems often support running Node.js inside of an embedded system.

Because an operating system influences the way we develop with an embedded system and Node.js, let’s briefly review some popular operating systems for embedded Node.js. This discussion is important to better understand board configuration.

OpenWRT

The history of OpenWRT is interesting. The company Linksys had to release its router firmware because it violated the GPL license of some Linux tools inside. The first public release of WRT to OpenWRT was in 2003.

With OpenWRT, it was possible for others to extend and configure router firmware as needed. One such project is Linino, which can be found in the Arduino Yun project. Another offspring of OpenWRT is the Freifunk project, a community-driven wireless network approach. OpenWRT is at the heart of the Tessel 2 and Onion Omega development boards.

The package manager of OpenWRT is called opkg and is similar to Debian’s dpkg. Node.js can be installed, for example, with:

$ opkg update
$ opkg install node

A number of Node.js modules are available for OpenWRT, such as node-serialport.

Debian

Debian is one of the Unix distributions that runs on many different kinds of hardware, from servers to desktop computers to embedded devices.

As a first step, it is often good advice to configure the connectivity of the device. This is done with some entries in the networks directory.

For users of the Raspberry Pi, a popular Debian distribution is the Raspbian distribution. For users of x86-embedded boards, such as an Intel Edison or UpBoard, a good choice is Ubilinux.

Once installed, you can easily run the Aptitude package manager:

# apt-get update

To ensure scripts are started during startup, you can place links to scripts in the directory /etc/init.d/.

Yocto

The Yocto project provides tools and packages specifically for embedded systems. The project was announced 2010.

The package manager of Yocto is “smart” (more information about “smart” is available in the blog post “Get smart with smart package manager”).

The Intel Edison runs Poky Linux image by default, which is based on a Yocto image. One difference from the Poky image to the Debian one is handling services. Poky uses the newer systemd to manage services and configurations of the board.

Breadboards

Breadboards provide a simple yet effective approach for learning about components and systems. They include premade connections that you can use to build basic circuits with jumper wires. In most cases, the breadboard provides vertical and horizontal connections. The outer part of a breadboard is then often used for supply voltages and a common ground.

There are many examples of electronic circuits on a breadboard. For example, to build a simple input button, it is necessary to provide a default voltage to the input pin of a microcontroller. This can be done with the circuit shown in Figure 7-1 where a pull-down resistor prevents a floating input voltage.

Figure 7-1. Simple switch on a breadboard

Building a circuit can take some time. On a breadboard, the more jumper wires and components you place, the more fragile a setup becomes. On the other hand, you don’t need tools and skills for soldering if you use a breadboard, and you can get basic components working quickly.

Let’s look at some other options for exploring circuits.

Grove Kit

For building circuits with a “plug and play” experience, the Grove Kits from Seeed Studio provide an interesting entry point (see Figure 7-2).

Figure 7-2. The Grove base shield (top right) provides headers to easily connect components (left and bottom)

The Grove kit is based on three ideas:

• A simple “base shield” in an Arduino form factor provides standard headers for cables

• Cables from components can then easily be plugged into the base shield

• Components such as a button, a potentiometer, some sensors, a buzzer, and a display with the same standard header connectors as the base shield

Compared with a breadboard, you’ll easily have access to a button or potentiometer, for example. Instead of wiring up a button with a pull-up resistor as before, you’ll now have a button component as shown in Figure 7-3.

Figure 7-3. A simple button from the Grove Starter Kit

You can solder Grove headers to your own boards too. Some boards, such as the BeagleBone Green, have Grove headers mounted by default already.

Besides the Arduino form factor, the Grove headers make customs setups a bit harder to design. For example, when you need multiple buttons or potentiometers, it is better to design and solder your own boards. But for many software developers, the Grove system is a good start to explore electronics for embedded software development.

Soldering

It can be fun to learn soldering and build components yourself. Components that arrive unsoldered to a breakout can be cheaper, and you have some more flexbility to make components as you need them. Additionally, for debugging a setup, learning to solder can be important. For example, an LED soldered to a resistor, such as the one in Figure 7-4, can often be helpful to quickly check the voltage on a pin.

Figure 7-4. An LED with resistor for debugging

Similarly, you can turn a potentiometer into a debugging tool by soldering jumper wires onto it. A potentiometer typically has three pins: GND, full scale, and a divided voltage. When working on a sensor device, this last pin is one you want to attach to an analog pin of a microcontroller. When you adjust the potentiometer, the divided voltage moves up or down an analog scale from ground (0V) to the full-scale voltage.

Figure 7-5. A potentiometer with jumper wires soldered onto it

Printed Circuit Boards

Soldering circuits with wires yourself quickly becomes time consuming for larger circuits. In these situations, a good option is to move to printed circuit boards (PCBs).

Many vendors such as SparkFun or Adafruit offer PCBs including a schematic of the board and the board layout including the used parts. Besides companies that promote open source hardware, a good place to find PCBs is at OSHpark, Tindie, or GitHub.

With computer programs such as Eagle or Kicad, you can easily adapt PCBs to your own needs. This is a two-phase process. First, you capture a circuit in a schematic editor. Then you turn the schematic into a layout that can be manufactured. For boards with two layers, you can order boards for less than $10 at places like OSHpark or DirtyPCBs.

While learning PCB design takes some time, it will save time later when you start building more complicated hardware devices. This can already be seen from the number of wires on a simple breakout board with LEDs, as shown in Figure 7-6.

Figure 7-6. LEDs on a breakout board on a breadboard (you can find a simple PCB doing the same thing at https://oshpark.com/shared_projects/ZsQu0dA9)

For prototyping, breakout boards with small circuits to accompany components are especially useful. Breakout boards make components easier to access and often provide some basic configuration for components. Breakout boards not only work with “simple” components, but also with advanced components such as microprocessors and microcontrollers. For example, to turn the small pins of an Intel Edison into something useful for prototyping, a number of interesting boards, such as the ones pictured in Figure 7-7, can be used. The boards shown here were purchased from SparkFun.

For some boards, such as the Arduino Uno or a BeagleBone, there exist special boards that you can plug onto the “motherboard.” This idea of an Arduino shield is nicely explained at the Arduino website:

Shields are boards that can be plugged on top of the Arduino PCB extending its capabilities. The different shields follow the same philosophy as the original toolkit: they are easy to mount, and cheap to produce.

These shields (or “capes” for BeagleBone) can be very interesting for prototyping. If you want to focus purely on software development, these boards allow you to avoid thinking about circuit design almost completely.

A nice example for an Arduino shield is shown in Figure 7-8. This Arduino Uno–compatible shield provides a number of components, such as a real-time clock, temperature sensor, and input buttons. The board was designed by Dan Hienzsch and was funded with a Kickstarter campaign.

Figure 7-7. Some examples of breakout boards for the Intel Edison from SparkFun (in red)

Figure 7-8. The I2C education shield

Tessel Modules

The capabilities of a Tessel can be extended via “modules.” On the Tessel 2, there are two module headers that provide pins to communicate with external devices. With modules, you can add the circuits and components needed to control motors or sensors. You can also build your own modules—for example, with help of Eagle or Kicad software packages. Figure 7-9, shows a simple diagram of an Eagle device for the Tessel module format.

Figure 7-9. A simple Tessel module design for Eagle (https://github.com/embeddednodejs/tessellib)

Different Tessel modules will be shown in later chapters. For now, you can observe that the ports of a Tessel are meant to easily control external components. The module header pins can communicate with sensors or actuators, for example.

Datasheets

Electronic components are documented in datasheets. Typically, datasheets discuss the limits and constraints of device operation.

Most datasheets can be found online today. There are special search engines for datasheets, such as Parts.io. Companies like SparkFun or Adafruit can help you to translate abstract datasheets into easy-to-understand information for components that they sell.

Key information you will find in a datasheet includes:

Operational voltage

To protect your boards and other parts, it is often important to identify the operational voltage of components. For example, a Raspberry Pi works on 3.3V, and connecting a 5V pin of an Arduino might do some harm.

Communication with a part, such as what protocol it uses

Simpler parts might output a digital signal or analog voltage. Others might specify PWM. On parts with their own microcontrollers, the datasheet will have details on the part’s use of communication protocols such as I2C or SPI.

Symbols and footprint

Schematics and footprints show how the various pins (e.g., the power and communication pins) need to be connected in order to function.

Passive Components

Many “passive” components are needed to adjust voltages or signal shapes. One simple passive component is the simple ceramic resistor, a physically static component made of ceramic and wire. In more advanced forms, passive components come as switches and potentiometers.

Potentiometers are often used to tune a voltage to a certain level. For example, a potentiometer can be used to adjust the volume of sound or the brightness of an LCD display. Another good use of a potentiometer is as an easy way to “simulate” a sensor. Sensors often output varying voltages. Turning the knob of a potentiometer that is connected to an analog pin often has a similar effect, but is easier to set up than the environment a sensor requires.

Besides providing voltage references, resistors and potentiometers also can protect active components such as an LED against high currents.

As shown in Figure 7-10, SparkFun provides a nice collection of passive and electromechanical components in the form of device libraries. A device library helps to organize components in a PCB project. The device libraries from SparkFun provide many useful prebuilt components. This includes electromechanical devices, such as tactile switches and trimming potentiometers.

Figure 7-10. Eagle device library with passive components from SparkFun

LEDs

LEDs are simple “active” components because they convert electrical energy into light energy. In their earliest days, LEDs were used as simple outputs in displays, as shown in the Altair 8800 computer (Figure 7-11).

Figure 7-11. The Altair 8800 uses LEDs as a simple user display (source: https://flic.kr/p/5XrzTu)

In many embedded projects, LEDs are helpful to determine whether a device carries current or not. The LED datasheet shows two pins of an LED. The longer one (anode) is used for the positive voltage, while the shorter one (cathode) is used for the negative voltage. If the voltage difference between anode and cathode is above a certain level, the LED will emit light.

Different colors for LEDs usually have different operational voltages. This “forward voltage” at a certain operating current influences how brightly the LED shines. Depending on the operational voltage of your system, you can again calculate if and how much resistance you must apply to protect the LED.

Working with LEDs has many advantages: they are an easy way to visualize the working of a circuit and to check working software. You just have to apply a forward voltage and the LED will light up.

With a time-varying PWM signal, you also can modulate the brightness of an LED.

Motion

Detecting motion can often be useful for robotics applications. A nice foundation for these kinds of projects is given by accelerometers, gyroscopes, and magnetometers. These components are often combined; for example, the SparkFun “9 Degrees of Freedom Board” uses the LSM9DS0 9DOF inertial measurement unit (IMU), as shown in Figure 7-14.

Another option to explore motion with an embedded device is the MPU6050. You will find a number of interesting examples online showing how to connect an Arduino to this component.

Figure 7-14. The IMU breakout board from SparkFun

Another good option to experiment with motion is by purchasing a Nintendo Wii Nunchuk controller (shown in Figure 7-15) and attaching a breakout board to it. The Nunchuk gives you an accelerometer and a gyroscope in the plus version.

Figure 7-15. A Wii Nunchuk

Ultrasonic Distance

With ultrasonic distance sensors, you can easily add detection for obstacles to an embedded project. Several sensors exist but the SFR-10 is a popular one. The SFR-10 adds some filtering to the input signal and makes processing the signal easier.

Figure 7-16. An SFR-10 mounted on a robot

Servo Motors

Servo motors allow you to position something, such as pointers or steering wheels. They provide rotational motion in a limited range—imagine mapping a servo motor’s range as a dial from zero to 100.

“Continuous” servo motors, so called because they do not have a limited range, are popular to turn cogs or wheels. Instead of setting position, on a continuous servo motor you can set the speed within a range, such as to control the speed of a vehicle.

Figure 7-18 shows a small servo motor. A servo motor has a gear box, a DC motor, and a rotor to move something. It typically has three wires: GND, power, and a reference signal.

Figure 7-18. A standard servo motor with three wires (in a ribbon cable)

The servo motor is contolled by an electric signal which measures the position of the rotor and determines the amount of movement based on feedback coming from the microcontroller.

Stepper Motors

Stepper motors are similar to servo motors in that they can be used to position something. The motor can rotate in certain “steps.” A stepper motor is typically able to drive with more force than a servo motor, which is useful if you want to move something heavy. Stepper motors can be very precise.

DC Motors

DC motors leave much control to the engineer. Typically, they are used as power train for remote control vehicles. The speed of a motor is controlled by a voltage. The higher the voltage, the higher the current and the faster the motor rotates. However, building a feedback loop to accurately control speed or position with a DC motor is more difficult.

Jumper Wires

Generally if you work with hardware it is a good idea to build an inventory of different kinds of jumper wires. There are male-to-female wires, male-to-male wires, and female-to-female wires.

USB Cables

Working with embedded devices, it is often a good idea to gather a number of USB cables with different plug types.

The USB Micro B type is slowly becoming a default for programming microcontroller boards. Yet, you’ll also encounter boards and setups where you require USB Mini or type A cables.

FTDI-USB-Cable

Most microcontroller boards have a serial port that can be used for debugging signals. Sometimes, direct access to the serial port of a processor is the only way to see output when debugging firmware.

To make working with serial ports for development easier, it is often a good idea to build or buy an adapter cable to use on a serial port.

Network Cables

The last type of cable that is useful when developing IoT devices are classic network cables. Network cables in combination with USB-to-Ethernet adapters are also useful to share Internet connections.

Serial Communication with JavaScript

Why would JavaScript for serial communication be more interesting than using another programming language? The CodeBender platform offers a good example. As shown in Figure 8-3, the website allows you to flash your Arduino directly from the browser. While the embedded code is built on the server, the code is uploaded to the devices via the browser and a USB cable. Behind the scenes is serial communication with JavaScript at work.

After you flash your Arduino with the example code shown here, you can monitor the value of a sensor in the serial console of the browser. This example is an excellent demonstration of serial communication.

Have a look at Figure 8-4. In general, serial communication is based on the following idea: a transmitter (TX) has one line to send data and a receiver (RX) has another line to receive data. Two wires allow you to send and receive data independently from each other, which is called full-duplex communication.

Because TX and RX are hard-wired signals between devices, the communication protocol can be kept simple. By defining a data rate beforehand, a clock signal is not necessary. When you want to have more flexible communication, you can share a clock signal to share timing information between transmitter and receiver.

Figure 8-3. The CodeBender platform links an Arduino to a web browser with serial communication

Figure 8-4. Serial communication provides a protocol to transfer data between devices

The core building block of a serial port is a universal asynchronous receiver and transmitter (UART). Some datasheets refer to ports that are based on a universal synchronous/asynchronous receiver and transmitter (USART). In the case of a UART, clock information is automatically recovered from the incoming data stream, which simplifies the configuration of a port somewhat, while a USART can be driven by an external clock signal allowing for much faster transmission speeds and support for a variety of protocols.

On a host computer, an operating system connects to the UART via a software driver. The driver takes care of inputs and outputs and configuration of the signals (“I/O control,” or ioctl in embedded language). This means if you want to talk to an Arduino from your laptop with Node.js, your JavaScript will actually talk to the driver for the serial port of the operating system.

With these concepts, you are ready to explore the node-serialport library. First, we will discuss how to scan for devices with JavaScript. Then, once you can find your device, the next step is to receive data, or to “dump” data coming from a device. Finally, you will learn how to send data from JavaScript to a device.

Scanning for Devices

To get started with the serialport library, let’s first create a fresh JavaScript project and add this module to it:

$ npm install --save-dev serialport

After the module has been downloaded, you are ready to start some serial communication fun:

// list_ports.js
var serialPort = require("serialport");
serialPort.list(function (err, ports) {
  ports.forEach(function(port) {
    console.log(port.comName);
  });
});

Now connect an Arduino with a USB cable to your computer. After the devices are connected, run:

$ node list_ports.js

You should see something similar to:

$ node list_ports.js
/dev/cu.Bluetooth-Incoming-Port |
/dev/cu.Bluetooth-Modem |
/dev/cu.usbmodem1411 | Arduino (www.arduino.cc)

In this case, there is an Arduino connected at /dev/cu.usbmodem1411. Because listing connected devices at the serial port is a useful command, you can add a shortcut in the package.json to extend npm with new features:

"scripts": {
  "list_ports": "node list_ports.js"
}

You can now run the following npm command:

$ npm run list_ports

> ch08@1.0.0 list_ports
> node list_ports.js

/dev/cu.Bluetooth-Incoming-Port |
/dev/cu.Bluetooth-Modem |
/dev/cu.usbmodem1411 | Arduino (www.arduino.cc)

Receiving Data from Arduino

Now that you can list devices that are attached on a serial port, let’s capture some data from a device. You must pass the port name, something like COM1 on Windows or /dev/ttyS0 on POSIX platforms. In the example above, the Arduino is on port /dev/cu.usbmodem1411.

Let’s prepare an Arduino to send some data over to your host computer. Instead of using a sensor, let’s use counter.ino, a simpler Arduino sketch that simply increases a counter (you’ll see how to capture that data with Node.js momentarily):

// Arduino sketch for testing serial communication
setup() {
  Serial.begin(9600);
}

int i=0;
void loop() {
  Serial.println(i++);
  delay(100); // poll every 100ms
}

The last “delay” gives the laptop some time to process the data. Providing a delay is a good idea when you want to watch a data stream with human eyes instead of a CPU’s.

For Arduino projects, a good choice for transmission speed is 9600 baud, because it is slow enough to watch incoming bits “live.” If there is a speed mismatch between your computer and your Arduino, you’ll see garbled output.

To read bits from the port with JavaScript, you must first open the port:

// read_port.js
var serialport = require("serialport");
var SerialPort = serialport.SerialPort;

var serialPort = new SerialPort("/dev/cu.usbmodem14131", {
  baudrate: 9600,
  parser: serialport.parsers.readline("\n")
});

serialPort.on("open", function () {
  // capture data
});

When the serial port is instantiated (as var serialPort = new SerialPort), the final argument sets a parser for the incoming data. In this example, we use the default readline parser, which yields human-readable text broken up by newlines.

Once the serial port is open, you have access to its data stream. The easiest thing to do is dump data from the stream to the terminal:

// read_port.js
var serialport = require("serialport");
var SerialPort = serialport.SerialPort;

var serialPort = new SerialPort("/dev/cu.usbmodem14131", {
  baudrate: 9600,
  parser: serialport.parsers.readline("\n")
});

serialPort.on("open", function () {
  console.log('open');
  serialPort.on('data', function(data) {
    console.log(data);
  });
});

As you can see, the serialPort object listens to the data events from the port. The received bits are displayed to the screen with console.log(data).

If everything works out, you’ll see some numbers from the Arduino scrolling down on the screen. By adding some components, you can easily dump data from measurements (e.g., temperature or positions from a potentiometer).

Sending Data to Arduino

Let’s now look at sending data to an embedded device—for example, simple control commands.

To see how this works, let’s write a very basic command parser for an Arduino board:

// Arduino sketch to test receiving data
if (Serial.available() > 0) {
  incoming = Serial.parseInt();

  if (Serial.read() == '\n') {
     // light the display
  }
}

With this code, the Arduino examines its UART to determine whether there is data in the receive buffer. If so, the Arduino parses the data and does something, such as toggling LEDs. To see some options, have a look in the ReadASCIIString example or the parseInt API in the Arduino documentation.

On the JavaScript side, you can define a “write” callback to write to the serial port. When you include the serial port in the previous example, the code becomes:

// write_data.js
var Stream = require('stream');

var modem = 'cu.usbmodem14231';

var ws = new Stream();
ws.writable = true;

ws.write = function(data) {
  serialPort.write(data);
};

ws.end = function(buf) {
  console.log('bye');
}

var serialPort = new SerialPort('/dev/' + modem, {
  baudrate: 9600,
  parser: serialport.parsers.readline("\n")
});

process.stdin.pipe(ws);

The idea behind this JavaScript code is that you redirect the output from, for example, the computer console into a writable stream. Data from this stream is then written into the serial port with serialPort.write(data).

An Empty Project

To begin, you need an empty project from which you can install JavaScript dependencies.

On your host machine, let’s create an empty project with:

$ mkdir led13

Next, you can use the npm to initialize the project:

$ npm init -y

The first dependency to install is Johnny-Five.

This library includes plugins for various boards including Intel Galileo and Edison boards. You can install Johnny-Five as follows:

$ npm install --save johnny-five

As you can see in the directory, you now have a file called package.json. This is the project manifest, where you can add different dependencies.

Depending on the board you are working with, you must use a board “adapter.” For example, in the case of the Intel Edison, this means:

$ npm install --save edison-io

With these libraries, you are ready to go.

The Board Object

The core class of a Johnny-Five project is the board class. In its simplest form (connecting to an Arduino Uno), the board is initialized as follows:

// board_ready.js
var five = require("johnny-five");
var board = new five.Board();

The script will search for an Arduino connected to the host computer. To specify the serial port where the board is connected, you can add a parameter port as follows:

var board = new five.Board({
  port: '/dev/cu.usbmodem12'
});

Johnny-Five supports many different boards. For example, if you want to control an Intel Edison with Johnny-Five, you pass the Edison board adapter when you set up the board:

var edison = require('edison-io');

var board = new five.Board({
  io: new Edison()
});

Once you have a board instance, you can easily capture events from a board object. For example, the board will emit a “ready” event that you can capture like this:

board.on("ready", function() {
  console.log("Board is ready!");
});

The fun really starts with objects inside the “ready” callback.

The Johnny-Five REPL

As a first experiment with hardware, let’s set up the read-eval-print-loop (REPL). Similar to working with a console or terminal, a REPL gives you the chance to interactively inspect a hardware setup. It’s like having a command line for your hardware.

You can also inject variables into an interactive programming session with:

// simple_repl.js
var five = require("johnny-five");

var Edison = require("edison-io");
var board = new five.Board({
  io: new Edison()
});

board.on("ready", function() {
  console.log("Board is ready!");

  this.repl.inject({
    led13: new five.Led(led13)
  });
});

The LED13 is now available in the console once you run this script with:

$ node simple_repl.js

We can then do some simple tests in the Node REPL:

>> led13.low();
>> led13.high();

Now that we have a working system with a blinking LED, let’s look at capturing user input.

Buttons

The simplest way to capture user input is with buttons. Johnny-Five makes working with buttons very easy, as you can simply “subscribe” to events from a button. The events a button can emit are “down,” “up,” and “hold.” To see how this works, let’s look at the following example:

// button_tests.js

// import dependencies
var five = require("johnny-five");
var Edison = require("edison-io");
var board = new five.Board({
  io: new Edison()
});

var button, oe;

// init board
board.on("ready", function() {

button = new five.Button(7);
button.on('down', function() {
  console.log('button down');
});

button.on('up', function() {
  console.log('button up');
});

button.on('hold', function() {
  console.log('button hold');
});

  // provide variables for interactive session
  this.repl.inject({
button: button
  });
});

With these simple events, you could build a simple stopwatch—the first button press starts the clock, the second press stops the clock, and a “hold” event resets the clock.

Analog Inputs

A user can easily change the state of a device with a button press. In an application, you might need analog inputs instead of digital buttons. In contrast to a digital input such as a button, an analog input is more like a measurement.

With Johnny-Five, you can directly read data from an “analog” component such as a potentiometer, slider, or sensor.

Let’s take a look at how to do this:

// read_analog.js

var five = require('johnny-five');
var Edison = require('edison-io');

var board = new five.Board({
  io: new Edison()
});

board.on("ready", function() {

var slider = new five.Sensor("A0");

  // "slide" is an alias for "change"
  slider.scale([0, 100]).on("slide", function() {
    console.log("slide", this.value);
  });
});

There are two differences between working with an analog input and working with a button: first, you provide a scale for the input, and second, you listen for “change” events and do something with its value.

Another example for analog inputs is reading data from sensors. Or, to read data from a whole lot of sensors such as the Nintendo Wii Nunchuk.

Proximity

If you want to build a robot, one common approach for obstacle detection is an ultrasonic distance meter. Johnny-Five has a nice module to work with proximity detectors.

Look at the following code for an example based on the SRF10 sensor:

// check_proximity.js

var five = require("johnny-five");
var board = new five.Board();

board.on("ready", function() {
  var proximity = new five.Proximity({
    controller: "SRF10"
  });

proximity.on("data", function() {
  console.log(this.cm + "cm", this.in + "in");
});

  proximity.on("change", function() {
    console.log("The obstruction has moved.");
  });
});

Nodebot

Johnny-Five was built for robots. Thanks to the Nodebot class, you can program a simple robot with only 12 lines of code:

// simple_nodebot.js
var five, Nodebot;

five = require("johnny-five");

five.Board().on("ready", function() {
  Nodebot = new five.Nodebot({
    right: 10,
    left: 11
  });

  this.repl.inject({
    n: Nodebot
  });
})

When you start this program, you’ll have a REPL from which you can control the robot. In this case, the robot has two servo motors for a moving robot. If you want to test this out with a serial cable, it can be handy to mount the robot in a position in which it does not move.

We will learn more about building robots in Chapter 12.

The I2C Library

Compared to serial communication via UART, communication via I2C is a bit more complex. Many sensors and electronic components support I2C because it supports many sensors on the same bus using only two wires.

The I2C bus is a half-duplex interface, which means two nodes (usually called “master” and “slave”) can only communicate over the wires in turn. When one node is listening, the other node can talk and vice versa. Imagine a phone call where only one party is allowed to speak and the other one must listen.

In I2C communication, the data line for communication is called SDA. The I2C bus adds another wire for providing timing information. The two wires, SDA (data) and SCL (clock), are both bidirectional.

The I2C specification version 3.0 defines four speed categories: Standard mode at up to 100 kbits/s, Fast mode at up to 400 kbits/s, Fast mode Plus at up to 1 Mbits/s, and High Speed mode at up to 3.4 Mbits/s.

There are different Node.js I2C libraries for I2C, for example using sysfs.

MRAA Setup

MRAA is based on C++ libraries that access the operating system on a low level. This means that to use MRAA from JavaScript, you must install some C libraries first.

On an Intel Edison, this means adding libmraa dependencies to the board first:

echo "src mraa-upm http://iotdk.intel.com/repos/1.1/intelgalactic" >
  /etc/opkg/mraa-upm.conf
opkg update
opkg install libmraa0

With this, you can install the Node.js bindings to libmraa with:

npm install --save mraa

Let’s check that it worked by creating a file called hello.js:

// hello.js
var mraa = require('mraa');
console.log('MRAA Version: ' + mraa.getVersion());

If everything worked, you should see:

# node hello.js
MRAA Version: v0.8.0

Let’s look next at processing inputs and outputs with MRAA.

Outputs

Similar to Arduino, libmraa provides different output modes for pins.

As usual, digital outputs provide a good start for exploring a setup. In MRAA, a digital output can take a state 0 or 1:

// simple_blink.js
var mraa=require('mraa');

var led = new mraa.Gpio(8);
led.dir(mraa.DIR_OUT);

With led.dir(mraa.DIR_OUT) you specify the direction of a GPIO. In this case, it acts as an output. Then you could use the event loop in JavaScript to write 0 and 1 to the pin as follows:

var blink = 0;
setInterval(function() {
  blink = !blink;
  blink ? led.write(1) : led.write(0);
}, 2000);

In this example, the timeout is 2000 milliseconds (2 seconds).

You can also generate PWM signals (because the PWM signal is generated by the Linux operating system, the granularity of the PWM is a bit lower than on a microcontroller):

// hello_pwm.js
var pin = new mraa.Pwm(3);
pin.period(200);
pin.enable(true);

var level = 0;
setInterval(function() {
  pin.write(level);
  level+=0.01;
  if (level >= 1) {
    level = 0;
  }
}, 50);

This concludes our introduction to pins as outputs. Let’s take a look at input pins.

Reading Inputs

To use a pin as digital input, you must declare the direction of the pin first:

// simple_buttons.js
var button = new mraa.Gpio(4);
button.dir(mraa.DIR_IN);

Next, you can read the state of the pin with:

setInterval(function() {
  var input = button.read();
  console.log(input);
}, 200);

To read an analog input, you’ll address the pin with:

var analogPin0 = new mraa.Aio(0);

Now you can fetch the data with:

setInterval(function() {
  var sample = analogPin0.read();
  var sampleFloat = analogPin0.readFloat();
  console.log(sample);
  console.log(sampleFloat);
}, 300);

As you can see, the pin abstractions from MRAA are very low-level. To prevent re-writing drivers for sensors and components from scratch, you can load JavaScript drivers for MRAA projects with the UPM project. UPM stands for “useful packages and modules,” and a number of drivers exist already, such as https://www.npmjs.com/package/jsupm_joystick12.

Interrupts

In contrast to other JavaScript libraries, LibMRAA allows you to bind functions to external interrupts from pins. This means you can avoid “blocking” code to detect pin changes and jump to code directly when it is needed.

The following example shows the usage of an interrupt on a GPIO pin:

// interrupt_check.js
var mraa = require('mraa');

function h() {
  console.log('button press');
}

var pin = new mraa.Gpio(4);
pin.isr(mraa.EDGE_FALLING, h);

setInterval(function() {
  console.log("nothing happened");
}, 400);

On the hardware side, you can add a button to digital pin 4 of a Galileo or Edison. If you then run the code:

$ node isr_example.js

You should see something like:

nothing happened
nothing happened
button press
nothing happened

As soon as GPIO 4 goes down, the interrupt is triggered. In this case, the callback function is executed.

Communications

LibMRAA also provides a number of low-level libraries for communication with other hardware devices. For example, to communicate with I2C:

var x = new mraa.I2c(0);
x.address(0x62);
x.writeReg(0, 0);

This can be tested with a simple I2C memory, for example.

For UART, you can use the following code:

u.setBaudRate(115200);
u.setMode(8, 0, 1);
u.setFlowcontrol(false, false);
u.writeStr("test\n");

Requesting the Weather

Due to their simplicity, weather displays and stations offer an easy-to-understand illustration of the usage of requests and responses of HTTP with embedded devices. On the hardware side, you could build a simple weather display with Grove components (discussed in Chapter 7). Another option would be to buy a small display and temperature/humidity sensors from eBay, SparkFun, or Adafruit and solder them together.

Gathering the components for a weather display might take some time. In the meantime, you can study its functions by looking at the weather app on your smartphone first. What happens if you request the weather for a certain location?

As you can see on the left side of Figure 9-1, your smartphone acts as a user agent that requests weather data from a public weather database. The smartphone is an “output” device that consists of a display and a network connection.

Figure 9-1. Weather information comes from different locations and has different outputs (displays) and inputs (sensors)

By adding “input” devices with sensors, you could connect your own weather stations to a weather display. This is shown on the right side of Figure 9-1.

Input and output devices do not translate directly to requests and responses of HTTP. According to RFC2616, responses provide a status code and an information body. It is this information body that should be processed and rendered on the display.

JavaScript allows you to prototype a weather display in a web browser, on the command line, and on the embedded devices. Instead of a web browser, the Node.js script acts as “user agent.” The script requests the weather station on behalf of the user. Different weather displays can fetch weather data from the same (public) database as shown in Figure 9-2.

Figure 9-2. Clients for weather data and weather stations

There are different public databases that provide weather data. And at npm you will find different modules to work with weather data. A good option is weather-js.

In a new directory, you first initialize the project and install the module with:

$ npm init -y
$ npm install weather-js

Next, you can set up a script to fetch the weather data from the MSN weather forecast service:

// hello_weather.js
var weather = require('weather-js');
var location = 'Paris, France';
var degreeType = 'C';

weather.find({search: location, degreeType: degreeType}, function(err, result) {
  if (err) {
      console.log(err);
      process.exit(0);
   }
   console.log(result);
});

Behind the scenes, the Node.js modules request and xml2js make an HTTP request and provide the response as a JSON object. Before attaching an embedded device to interact with the weather, let’s quickly check that the API works from the command line.

If you run:

$ node hello_weather.js

You’ll see:

current:
 { temperature: '10',
   skycode: '31',
   skytext: 'Clear',
   date: '2016-03-27',
   observationtime: '22:00:00',
   observationpoint: 'Paris, Paris, France',
   feelslike: '7',
   humidity: '66',
   winddisplay: '28 km/h South',
   day: 'Sunday',
   shortday: 'Sun',
   windspeed: '28 km/h',
   imageUrl: 'http://blob.weather.microsoft.com/static/weather4/en-us/law/31.gif' },
forecast: ...

The next step is to allow users of an embedded device to fetch weather data with the press of a button. Instead of the computer console, we want to display the result to an output (i.e., a screen).

Putting together hardware for a weather display with an Arduino can be as simple as the setup shown in Figure 9-3. You can connect a button to D4 on a Grove shield and an LCD display to the I2C bus.

Figure 9-3. Arduino with push button and LCD display

Programming the screen on a button press is similar to the examples from the previous chapters. With the Johnny-Five library, it looks like this:

$ npm install --save johnny-five

Then, capture a button press as follows:

// weather_display.js
var five = require('johnny-five');
var board = new five.Board();

board.on('ready', function() {

var button = new five.Button(4);

// To display weather information
var lcd = new five.LCD({
   controller: "JHD1313M1"
});

  // Update screen on button press
  button.on('press', function() {
    console.log('press');
    lcd.clear();
    lcd.print("hello");
  });
});

Last, you can add the hello_weather.js script to the Johnny-Five Arduino wrapper:

// weather_display.js
var weather = require('weather-js');
var location = 'Paris, France';
var degreeType = 'C';

var five = require('johnny-five');
var board = new five.Board();

board.on('ready', function() {
    var button = new five.Button(4);
    var lcd = new five.LCD({
       controller: "JHD1313M1"
    });

// on press, fetch the weather
    button.on('press', function() {
        lcd.clear();
        weather.find({search: location, degreeType: degreeType},
                     function(err, result) {
          if (err) {
              console.log("problem fetching weather");
              console.log(err);
              process.exit(0);
           }
        lcd.cursor(0,0).print(location);
        lcd.cursor(1,0).print("temp: "+ result[0].current.temperature);
      });
    });
});

If successful, you’ll see the temperature of the requested place on the LCD.

Prepare the HTTP Client

Before building your own HTTP server that acts as a weather station, it is a good idea to prepare an API client for testing. As shown in Figure 9-4, an API client handles GET requests to fetch state, and POST requests to update state.

Figure 9-4. Different usages for POST and GET requests

On npmjs.com, you’ll find many libraries that help you write custom HTTP clients. The most popular are request and superagent. We’ll use request as it is one of the most popular Node.js modules.

In a new project, install the request module with:

$ npm install --save request

A get request allows you to fetch data via a uniform resource locator (URL).

To have a script act as a user agent:

// get_request.js
var request=require('request');

// take url from command line
var url=process.argv[2];
if (!url) {
  console.log('You must add a path.');
}
console.log('GET url: ' + url);

var headers = {'User-Agent': 'Sensor Agent'};
request.get(url, {headers: headers})
       .on('error', function(err) {
           console.log(err)
   }).pipe(process.stdout);

On Linux systems, you can make the code executable with the hash-bang syntax. In front of the script, you can add:

#!/usr/bin/env node

Now to test this agent, let’s query data from the book website:

$ ./simple_agent.js http://embeddednodejs.com/dummy_data.json
GET url: http://embeddednodejs.com/dummy_data.json
[{"time":"00:00", "data": 0}, {"time":"11:11", "data": 1}]

Similarly, you can invoke POST and PUT requests:

// post_request
var request=require('request');

// the URL for the weather station to come
var url = "http://localhost:4000/measurements";

var headers = {'User-Agent': 'Sensor Agent',
               'content-type': 'application/json'};
var data = {temp: 25};
request({url: url,
         method: 'POST',
         form: data,
         headers: headers})
       .on('error', function(err) {
           console.log(err)
       }).pipe(process.stdout);

You can automate running scripts to fetch or post data with forever:

$ forever start -o log.txt --spinSleepTime 1000 get_request.js

$ npm install -g forever

Adding a Database

To store data from a sensor in the weather station, you need a database. A simple database for embedded devices is SQLite. SQLite is a file-based relational database management system (RDBMS). You can install and run SQLite with embedded Linux.

To connect to the database from JavaScript, you need a connection manager. In Node.js, a good choice is Knex. You can install it as follows:

$ npm install -g knex
$ npm install --save knex
$ npm install --save sqlite3

With the next step, you init a config file for the database connection:

$ knex init
Created ./knexfile.js

The config file can be adapted to your needs. In this case, let’s only use the development version:

// knexfile.js
// update with your config settings.

module.exports = {

  development: {
    client: 'sqlite3',
    connection: {
      filename: './dev.sqlite3'
    }
  }
};

After the database connection is established, Knex provides tools to easily manage tables in a database. For the simple weather station, the plan is to use a database schema with two tables.

One table tracks measurements from a device and another table stores data snapshots from the sensors. In the language of SQL, this means a measurement has many snapshots and a snapshot belongs to a measurement.

To build this schema, Knex can help with simple scripts:

$ knex migrate:make createMeasurements

Then, you add the table data:

// migrations/createMeasurements
var table = function(t) {
    t.increments().primary();
    t.string('name');
    t.string('comment');
    t.timestamps();
}

exports.up = function(knex, Promise) {
  return knex.schema.createTable('measurements', table)
             .then(function () {
                console.log('Measurements table is created!');
             });
};

exports.down = function(knex, Promise) {
  return knex.schema
            .dropTable('measurements', table)
            .then(function () {
               console.log('Measurements table was dropped!');
            });
};

The snapshots table can be created with:

$ knex migrate:make createSnapshots

Then you need to define a schema for the snapshots as follows:

var table = function(table) {
   table.increments().primary();
   table.integer('time');
   table.integer('temp');
   table.integer('measurement_id')
      .references('id')
      .inTable('measurements');
   table.timestamps();
}

exports.up = function(knex, Promise) {
   return knex.schema
              .createTable('weather_events', table)
              .then(function () {
                 console.log('weather events table is created!');
               });
};

exports.down = function(knex, Promise) {
   return knex.schema
               .dropTable('weather_events', table)
               .then(function () {
                  console.log('weather events table was dropped!');
                });
};

To use this connection from other scripts, you need to add “models” with the Bookshelf.js ORM. For a simple weather station, two models will do: one for measurements and one for weather snapshots. Here is the measurements snapshot:

// models/measurement.js

// load the database config
var bookshelf = require('../config');
var Snapshot = require('./snapshot');

var Measurement = bookshelf.Model.extend({
   tableName: 'measurements',
   hasTimestamps: true,

   snapshots: function() {
     return this.hasMany('Snapshot');
   }
});
module.exports = bookshelf.model('Measurement', Measurement);

Next, the weather snapshot:

// models/snapshot.js

// load the database config
var bookshelf = require('../config');
var Measurement = require('./measurement');

var Snapshot = bookshelf.Model.extend({
   tableName: 'snapshots',
   hasTimestamps: true,

   measurements: function() {
     return this.hasMany('Measurement');
   }
});
module.exports = bookshelf.model('Snapshot', Snapshot);

To test this setup, you can create scripts to add new measurements and snapshots to the database:

// scripts/add_measurement.js
var bookshelf = require('./config');
var Measurement = require('./models/measurement');

var measurement = Measurement.forge({name: 'Sensor 1'});
measurement.save().
  then(function() {
    return bookshelf.knex.destroy();
});

Then run:

$ node scripts/add_measurement.js

Now, you can see an entry in the database:

$ sqlite3 dev.sqlite3
SQLite version 3.8.10.2 2015-05-20 18:17:19
Enter ".help" for usage hints.
sqlite> select * from measurements;
1|Sensor 1||1461187585457|1461187585457

And a similar script to add snapshots:

// scripts/add_measurement.js
var bookshelf = require('../config');
var Snapshot = require('../models/snapshot');

var snapshot = Snapshot.forge({measurement_id: 1, temp: 23});
snapshot
  .save()
  .then(function() {
    return bookshelf.knex.destroy();
  });

Last, you need to integrate the database with the web server. Connecting the parts in file server.js can look like this:

// server_with_db.js
var express = require('express');
var bodyParser = require('body-parser');

// connect with db
var bookshelf = require('./config');
var Measurement = require('./models/measurement');

var port = 4000;

var app = express();
app.use(bodyParser.urlencoded({ extended: false }));

// basic routes
app.get('/', function(req, res) {
   res.writeHead(200);
   res.write('server is running');
   res.end();
});

// measurements
app.get('/measurements/:measurement_id', function(req, res) {
   res.writeHead(200);
   Measurement.collection().fetch({
     withRelated: ['snapshots']
   })
   .then(function(collection) {
       return collection.mapThen(function(model) {
         return model.toJSON();
       })
   })
   .then(function(results) {
     res.write(JSON.stringify(results, null, '  '));
     res.end();
   })
   .catch(function(e) {
     console.log(e);
     res.write('problem');
     res.end();
   });
});

app.post('/measurements', function(req, res) {
    var snapshot = Snapshot.forge({measurement_id: req.body.id,
                                  temp: req.body.temp});
    snapshot.save().
      then(function() {
        res.writeHead(200);
        res.write('snapshot saved');
        res.end();
      })
      .catch(function(err) {
        res.writeHead(200);
        res.write('problem saving snapshot');
        res.write(err);
        res.end();
      });
});

app.post('/measurements/:id', function(req, res) {
    var snapshot = Snapshot.forge({measurement_id: req.body.id,
                                  temp: req.body.temp});
    snapshot.save().
      then(function() {
        res.writeHead(200);
        res.write('snapshot saved');
        res.end();
      })
      .catch(function(err) {
        res.writeHead(200);
        res.write('problem saving snapshot');
        res.write(err);
        res.end();
      });
});

var server = app.listen(port);

Now, the whole setup can be tested with the user agents from the weather display. To test this, you run:

// get measurements
$ node get_measurements.js
GET url: http://localhost:4000/measurements/1
[
 {
  "id": 1,
  "name": "Sensor 1",
  "created_at": 1461188045864,
  "updated_at": 1461188045864,
  "snapshots": [
   {
    "id": 1,
    "temp": 23,
    "measurement_id": 1,
    "created_at": 1461188049036,
    "updated_at": 1461188049036
   }
  ]
 }

Now you can post weather data from different places in a network. Let’s take a look at how to post data from embedded devices to the measurement station.

The ws Module

To start, we are going to use the ws module. Install the module with:

$ npm install --save ws

Websockets provide bidirectional communication, which means you can send and receive messages with websockets. This is nice to control device outputs or to receive data from inputs such as sensors.

You can explore the workings of websockets for embedded devices with an Arduino and LED attached. To push data from that device with websockets, write the following:

var five = require('johnny-five');

var http = require('http');
var port = 4000;

var board = new five.Board({
  repl: false
});

// set up WebSocketServer to push bytes
function setupServer(board) {

// import a websocket server
var WebSocketServer = require('ws').Server;

// prepare server
var server = http.createServer(function (req, res) {
  res.write('ok');
  res.end();
}).listen(port);

var wss = new WebSocketServer({server: server});

// connection is set up
wss.on('connection', function(ws) {
    console.log('websocket connected');

  // incoming messages
      ws.on('message', function(message) {
        console.log('received: %s', message);
        var state = parseInt(message);
        state == 1 ? board.led.on() : board.led.off();
      });
  });
}

// start up connection
board.on('ready', function() {
  this.led = new five.Led(3);
  setupServer(this);
});

To test websockets from the command line, you can install a nice command-line tool called wscat:

$ npm install -g wscat

And run:

$ wscat -c ws://localhost:4000
connected (press CTRL+C to quit)
  > 1
  > 0

This should result in switching the LED on the embedded device. Similarly, you can “push” bytes from an embedded device to a websockets client. To see how this works, connect a button to the Arduino on pin 4.

Then you can add a button to the board object as follows:

board.on('ready', function() {
  this.button = new five.Button(9);
  setupServer(this);
});

And, hook into the button press event:

// set up WebSocketServer to push bytes
function setupServer(board) {

var WebSocketServer = require('ws').Server;

// prepare server
var server = http.createServer(function (req, res) {
  res.write('ok');
  res.end();
}).listen(port);

var wss = new WebSocketServer({server: server});

wss.on('connection', function connection(ws) {
    console.log('websocket connected');

      board.button.on('press', function() {
        ws.send('button push');
      });
  });
}

To see how it works, you simply make a connection to the web server. Now you can observe events from the button:

$ wscat -c ws://localhost:4000
connected (press CTRL+C to quit)
  < button push
  < button push
  < button push

Instead of the command-line tool wscat, you can write a small client with the ws module as follows:

var WebSocket = require('ws');

var client = new WebSocket('ws://localhost:4000');

client.on('open', function() {
  client.on('message', function() {
    console.log('push');
  });
});

Websockets are also handy to communicate between an embedded device and a web browser. Connections to the web browser will be explored in the next chapter.

Remote Procedure Calls over Websockets

Based on the WebSocket protocol, you build a medium for remote procedure calls (RPCs). With RPCs, you can invoke methods on objects that come from other devices. Figure 9-6 illustrates how this can be useful.

Figure 9-6. With RPCs, you can invoke functions from remote servers attached to outputs (LEDs, displays) and inputs (sensors)

To begin, take a simple board setup with an LED attached. Without RPCs involved, you can only control the objects within the scope of a script. The initial setup might look like this:

// led_control.js
var port = 4000;

// set up board
var five = require('johnny-five');

// select a board adapter
// var Edison = require('edison-io');
// var Galileo = require('galileo-io');
// var BeagleBone = require('beaglebone-io');

var board = new five.Board({
  // add the adapter here
  // io: new Galileo()
});

board.on("ready", function() {
  var led = new five.Led(3);

  this.repl.inject({
    led: led
  });
});

You can use the LED object on the device with the following commands:

# node led_control.js
1452444373827 Device(s) Intel Galileo Gen 2
1452444373883 Connected Intel Galileo Gen 2
1452444373969 Repl Initialized
>> led.on();

Now, with RPCs you can call the LED object from a different location and context in a network. To see how this works, you must build a web server with support for RPC.

One option is to use the dnode module by James Halliday. You can install this with:

$ npm install --save dnode

Then, wire up the server as follows:

// dnode_server.js
// port to listen to
var port = 4000;

// set up board
var five = require('johnny-five');

// board adapters
// var Edison = require('edison-io');
// var Galileo = require('galileo-io');
// var BeagleBone = require('beaglebone-io');

var board = new five.Board({
  repl: false
});

board.on("ready", function() {

    // place the pin connected to an LED
    this.led = new five.Led(13);

      // now start up server
      startupServer(this);
    });

function startupServer(board) {
  var dnode = require('dnode');
  var net = require('net');

    // create local web server
    var server = net.createServer(function(conn) {

    // set up RPC objects
    var rpc = dnode({

      // these functions can be invoked from other places
      ledOn: function() {
        console.log('on');
        board.led.on();
      },
      ledOff: function() {
        board.led.off();
      }
    });

    // connect local dnode objects with remote
    conn.pipe(rpc).pipe(conn);
    });

      server.listen(port, function() {
        console.log('Server running on port: ' + port);
      });
    }

And the client:

// dnode_client.js
var net = require('net');
var dnode = require('dnode');
var port = 4000;

var rpc = dnode();
rpc.on('remote', function (remote) {
  remote.ledOn(); // this function will be invoked on the server
});

var conn = net.connect(port, 'galileo');
conn.pipe(objects).pipe(conn);

Now you can turn the LED on and off from other places if you run:

$ node dnode_client.js