JavaScript Robotics: Board API (Johnny-Five)

Parameters
Shape
Component Initialization
Usage
API
Events

The Board class constructs objects that represent the physical board itself. All device objects depend on an initialized and ready board object.

Johnny-Five (sans IO Plugin) has been tested on, but is not limited to, the following boards:

For non-Arduino based projects, a number of IO Plugins are available:

Parameters

options Optional object of themselves optional parameters.

Property	Type	Value/Description	Default	Required
id	Number, String	Any. User definable identification	Generated	no
port	String or object	eg. `/dev/ttyAM0`, `COM1`, `new SerialPort()`. Path or name of device port/COM or SerialPort object	Detected	no
repl	Boolean	`true`, `false`. Set to `false` to disable REPL	`true`	no
debug	Boolean	`true`, `false`. Set to `false` to disable debugging output	`true`	no
timeout	Number	Timeout in milliseconds for the board to get connected	`10000`	no

Shape

Property Name	Description	Read Only
`io`	A reference to the IO protocol layer.	No
`id`	A user definable id value. Defaults to a generated uid.	No
`repl`	A reference to the active REPL.	No

Component Initialization

To initialize control of a board, construct an instance of the Board class.

When connecting to a USB serial device, such as an Arduino, you do not need to specify the device path or COM port, Johnny-Five will determine which to connect to and connect automatically.

new five.Board();

You may optionally specify the port by providing it as a property of the options object parameter.

// OSX
new five.Board({ port: "/dev/tty.usbmodem****" });

// Linux
new five.Board({ port: "/dev/ttyUSB*" });

// Windows
new five.Board({ port: "COM*" });

* Denotes system specific enumeration value (ie. a number)

You can specify a SerialPort object by providing it as a property of the options object parameter:

var SerialPort = require("serialport").SerialPort;
var five = require("johnny-five");
var board = new five.Board({
  port: new SerialPort("COM4", {
    baudrate: 9600,
    buffersize: 1
  })
});

Usage

A basic, but complete example usage of the Board constructor:

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

board.on("ready", function() {
  /*
    Initialize pin 13, which 
    controls the built-in LED
  */
  var led = new five.Led(13);
  
  /*
    Injecting object into the REPL
    allow access while the program
    is running. 
    
    Try these in the REPL: 
    
    led.on();
    led.off();
    led.blink();

    (One at a time to see each action)
  */
  this.repl.inject({
    led: led
  });
});

Sub-process Usage

When running Johnny-Five programs as a sub-process (eg. init.d, or npm scripts), be sure to shut the REPL off!

var five = require("johnny-five");
var board = new five.Board({
  repl: false,
  debug: false,
});

board.on("ready", function() {
  // it's very quiet in here now!
});

API

Logging

info(class, message [, ...detail]) Displays an info message in the console (when debug: true, which is the default) and emits an event of the same name, as well as a generic message event. class is the class that triggered the message, or that is being reported for; message is any relevant message. This argument accept an arbitrary number of detail arguments. If the last detail argument is an object or array, it will be passed along as the value of a data property of the event object.
```
board.info("Board", "I got somethin' to say!", { foo: 1 });

board.info("Servo", "This pin doesn't have hardware PWM support, but will function correctly with software Servo support.");
```
warn(class, message [, ...detail]) Displays a warn message in the console (when debug: true, which is the default) and emits an event of the same name, as well as a generic message event. class is the class that triggered the message, or that is being reported for; message is any relevant message. This argument accept an arbitrary number of detail arguments. If the last detail argument is an object or array, it will be passed along as the value of a data property of the event object.
```
board.warn("Board", "Watch out!", { bar: 2 });
```
fail(class, message [, ...detail]) Displays a fail message in the console (when debug: true, which is the default) and emits an event of the same name, as well as a generic message event. class is the class that triggered the message, or that is being reported for; message is any relevant message. This argument accept an arbitrary number of detail arguments. If the last detail argument is an object or array, it will be passed along as the value of a data property of the event object.
```
board.fail("Led", "This pin is already in use!", { baz: NaN });

board.fail("Board", "This program attempted to do something that isn't possible");  
```

See Events for specific log event details.

repl This is a reference to the active REPL automatically created by the Board class. This object has an inject method that may be called as many times as desired:

repl.inject(object) Inject objects or values, from the program, into the REPL session.

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

board.on("ready", function() {
  // Initialize an LED directly in the REPL
  this.repl.inject({
    led: new five.Led(13)
  });  
});
/*
  From the terminal...

  $ node program.js
  1423012815316 Device(s) /dev/cu.usbmodem1421
  1423012818908 Connected /dev/cu.usbmodem1421
  1423012818908 Repl Initialized  
  >> led.on();
  >> led.off();
  
*/

pinMode(pin, mode) Set the mode of a specific pin, one of INPUT, OUTPUT, ANALOG, PWM, SERVO. Mode constants are exposed via the Pin class

Mode	Value	Constant
INPUT	0	Pin.INPUT
OUTPUT	1	Pin.OUTPUT
ANALOG	2	Pin.ANALOG
PWM	3	Pin.PWM
SERVO	4	Pin.SERVO

// Set a pin to INPUT mode
var five = require("johnny-five");
var board = new five.Board();

board.on("ready", function() {
  
  // pin mode constants are available on the Pin class
  this.pinMode(13, five.Pin.INPUT);
});

analogWrite(pin, value) Write an unsigned, 8-bit value (0-255) to an analog pin.

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

board.on("ready", function() {
  // Assuming an Led is attached to pin 9, 
  // this will turn it on at full brightness
  // PWM is the mode used to write ANALOG 
  // signals to a digital pin
  this.pinMode(9, five.Pin.PWM);
  this.analogWrite(9, 255);
});

analogRead(pin, handler(voltage)) Register a handler to be called whenever the board reports the voltage value (0-1023) of the specified analog pin.

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

board.on("ready", function() {
  // Assuming a sensor is attached to pin "A1"
  this.pinMode(1, five.Pin.ANALOG);
  this.analogRead(1, function(voltage) {
    console.log(voltage);
  });
});

digitalWrite(pin, value) Write a digital value (0 or 1) to a digital pin.

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

board.on("ready", function() {
  // Assuming an Led is attached to pin 13, this will turn it on
  this.pinMode(13, five.Pin.OUTPUT);
  this.digitalWrite(13, 1);
});

digitalRead(pin, handler(value)) Register a handler to be called whenever the board reports the value (0 or 1) of the specified digital pin.

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

board.on("ready", function() {
  // Assuming a button is attached to pin 9
  this.pinMode(9, five.Pin.INPUT);
  this.digitalRead(9, function(value) {
    console.log(value);
  });
});

Note: digitalRead will only call its handler when the value of the pin changes.

i2cConfig([milliseconds] | options) This must be called prior to any I2C reads or writes.
- May be called with a period in milliseconds to delay between read operations.
- May be called with an object containing options relevant to the platform for which the code is being written. For more information, see: IO-Plugins, i2cConfig(options)

i2cWrite(address, arrayOfBytes) Write an arrayOfBytes to the component at address.

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

board.on("ready", function() {
  this.i2cConfig();
  this.i2cWrite(0x01, [0x02, 0x03]);
});

i2cWrite(address, register, arrayOfBytes) Write an arrayOfBytes to the component at address, for a specific register.

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

board.on("ready", function() {
  this.i2cConfig();
  this.i2cWrite(0x01, 0x00, [0x02, 0x03]);
});

i2cWriteReg(address, register, byte) Write a single byte to the component at address, for a specific register.

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

board.on("ready", function() {
  this.i2cConfig();
  this.i2cWriteReg(0x01, 0x00, 0x7e);
});

i2cRead(address, bytesToRead, handler(arrayOfBytes)) Repeatedly read the specified number of bytes (bytesToRead) and call handler with the results as arrayOfBytes.

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

board.on("ready", function() {
  this.i2cConfig();
  this.i2cRead(0x01, 0x02, 6, function(bytes) {
    console.log("Bytes read: ", bytes);
  });
});

i2cRead(address, register, bytesToRead, handler(arrayOfBytes)) Repeatedly read the specified number of bytes (bytesToRead), starting at a specific register, and call handler with the results as arrayOfBytes.

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

board.on("ready", function() {
  this.i2cConfig();
  this.i2cRead(0x01, 0x00, 6, function(bytes) {
    console.log("Bytes read: ", bytes);
  });
});

i2cReadOnce(address, register, bytesToRead, handler(arrayOfBytes)) Read the specified number of bytes (bytesToRead), starting at a specific register, and call handler with the results as arrayOfBytes.

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

board.on("ready", function() {
  this.i2cConfig();
  this.i2cReadOnce(0x01, 0x02, 6, function(bytes) {
    console.log("Bytes read: ", bytes);
    console.log("Done!");
  });
});

i2cReadOnce(address, bytesToRead, handler) Read the specified number of bytes (bytesToRead) and call handler with the results as arrayOfBytes.

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

board.on("ready", function() {
  this.i2cConfig();
  this.i2cRead(0x01, 6, function(bytes) {
    console.log("Bytes read: ", bytes);
    console.log("Done!");
  });
});

servoWrite(pin, angle) Write an angle in degrees from 0-180 to a servo.

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

board.on("ready", function() {
  this.pinMode(9, five.Pin.SERVO);
  this.servoWrite(9, 90);
});

shiftOut(dataPin, clockPin, isBigEndian, value) Write a byte to dataPin, followed by toggling the clockPin. Understanding Big and Little Endian Byte Order

wait(milliseconds, handler()) Register a handler to be called once in another execution turn and after milliseconds has elapsed.

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

board.on("ready", function() {
  // Assuming an Led is attached to pin 13
  this.pinMode(13, this.MODES.OUTPUT);

  // Turn it on...
  this.digitalWrite(13, 1);

  this.wait(1000, function() {
    // Turn it off...
    this.digitalWrite(13, 0);
  });
});

loop(milliseconds, handler()) Register a handler to be called repeatedly, in another execution turn, every milliseconds period. handler recieves one argument which is a function that will cancel the loop if called.

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

board.on("ready", function() {
  var state = 0;

  this.pinMode(13, this.MODES.OUTPUT);

  this.loop(500, () => {
    this.digitalWrite(13, (state ^= 1));
  });
});

Events

connect This event will emit once the program has "connected" to the board. This may be immediate, or after some amount of time, but is always asynchronous. For on-board execution, connect should emit as soon as possible, but asynchronously.
ready This event will emit after the connect event and only when the Board instance object has completed any hardware initialization that must take place before the program can operate. This process is asynchronous, and completion is signified to the program via a "ready" event. For on-board execution, ready should emit after connect.
exit This event is emitted synchronously on SIGINT. Use this handler to do any necessary cleanup before your program is "disconnected" from the board.
close This event is emmited when the device does not respond. Can be used to detect if board gets disconnected.

info This event will emit for board.info(class, message [, ...])

board.on("info", function(event) {
  /*
    Event {
      type: "info"|"warn"|"fail",
      timestamp: Time of event in milliseconds,
      class: name of relevant component class,
      message: message [+ ...detail]
    }
  */
  console.log("%s sent an 'info' message: %s", event.class, event.message);
});

warn This event will emit for board.warn(class, message [, ...])

board.on("warn", function(event) {
  /*
    Event {
      type: "info"|"warn"|"fail",
      timestamp: Time of event in milliseconds,
      class: name of relevant component class,
      message: message [+ ...detail]
    }
  */
  console.log("%s sent a 'warn' message: %s", event.class, event.message);
});

fail This event will emit for board.fail(class, message [, ...])

board.on("fail", function(event) {
  /*
    Event {
      type: "info"|"warn"|"fail",
      timestamp: Time of event in milliseconds,
      class: name of relevant component class,
      message: message [+ ...detail]
    }
  */
  console.log("%s sent a 'fail' message: %s", event.class, event.message);
});

message This event will emit for any logging message: info, warn or fail.

board.on("message", function(event) {
  /*
    Event {
      type: "info"|"warn"|"fail",
      timestamp: Time of event in milliseconds,
      class: name of relevant component class,
      message: message [+ ...detail]
    }
  */
  console.log("Received a %s message, from %s, reporting: %s", event.type, event.class, event.message);
});