Led.Matrix

The Led.Matrix class constructs an object that may represent one or more (chained) 8x8 LED Matrix (MAX7219, MAX7221 and HT16K33) devices attached to the physical board. Up to 8 devices can be controlled with one instance, giving you 512 controllable LEDs.

Known supported devices:

See all on Tindie!

• Shift Register Devices

  • MAX7219
    • MAX7219 Dot Matrix MCU LED Display Control Module Kit For Arduino With Dupont Cable
    • LED Matrix Kit
    • DIY MAX7219 Red LED Dot Matrix Display Module for Arduino
    • Dot Matrix Display Kit w/MAX7219 IC, PCB
    • Dot Matrix Chain Display Kit Max7219 V2

• I2C devices

  • HT16K33
    • Adafruit 0.8 8x8 LED Matrix (Any color)
    • Adafruit 1.2 8x8 LED Matrix bicolor
    • Adafruit 1.2 8x8 LED Matrix (Any color)
    • Adafruit 1.2 16x8 LED Matrix (Any color)
    • OCROBOT 8x8 LED Matrix - bicolor

If you are working with HT16K33 devices, you will need to run at least version 2.4.0 of Firmata on the board, currently available in beta.

Adafruit offers a selection of 8x8 matrices in various colors:

• White
• Amber
• Yellow
• Green
• Blue

(This list only represents devices that I've personally confirmed, please add devices as needed.)

Parameters

• shift register options An object of property parameters.

Property Name	Type	Value(s)	Properties	Required
pins	Object	A valid pins object or pins array	data, clock, cs	yes
devices	Number	1-8	For single device cases, this can be omitted. Defaults to 1.	no

• I2C options (Requires StandardFirmata 2.4.0 or greater)

Property Name	Type	Value(s)	Properties	Required
controller	string	A valid controller model name	HT16K33	yes
addresses	array	An array of I2C addresses	Defaults to array of addresses in range 0x70 - 0x77, up to length specified by devices	no
isBicolor	Boolean	true|false	Defaults to false	no
is16x8	Boolean	true|false	The devices being used are each 16x8 units.	no

// Shift Register device
var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

// I2C device
var matrix = new five.Led.Matrix({ 
  controller: "HT16K33",
  isBicolor: true
});

Shape

{ 
  isMatrix: true. READONLY
  devices: ...Number of devices controlled. READONLY
}

Usage

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

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

  var matrix = new five.Led.Matrix({
    pins: {
      data: 2,
      clock: 3,
      cs: 4
    }, 
    devices: 1
  });

  matrix.on();

  this.repl.inject({
    display: matrix.device(0)
  });
});

API

NOTE: When the device is turned off (with the off method), data is retained and will be displayed on the device when turned on (with the on method). This is useful when powering the devices from a battery, by providing a power saving mechanism.

• on() Turn on all matrix devices.
• on(device index) Turn on matrix device at specified device index.

var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

// Turn on a specific device by device index.
matrix.on(0);

// Turn on all devices
matrix.on();

• off() Turn off all matrix devices.
• off(device index) Turn off matrix device at specified device index.

var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

// Turn off a specific device by device index.
matrix.off(0);

// Turn off all devices
matrix.off();

// Send data to the the matrix
// ...Turn on the device to see the data displayed

• clear() Shut off all LEDs, for all devices.
• clear(device index) Shut off all LEDs, for a device at specified device index.

Note: clear() does not shut off the device.

var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

// Clear the entire display of a specified device.
matrix.clear(0);

// Clear the entire display for all devices
matrix.clear();

• brightness(0-100) Set the brightness from 0-100%, of all devices.
• brightness(device index, 0-100) Set the brightness from 0-100%, for a device at specified device index.

var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

// Set the brightness of a specified device.
matrix.brightness(0, 100);

// Set the brightness for all devices
matrix.brightness(100);

• led(row, col, state) Set on/off/color state for led at row and col (0-8, 0-8), of all devices.
• led(device index, row, col, state) Set on/off/color state for led at row and col (00-8), for a device at the specified device index.

// Shift Register device
var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

// Turn on the top-left led of the specified device
matrix.led(0, 0, 0, 1);

// Turn on the top-left led of all devices
matrix.led(0, 0, 1);

// Turn off the top-left led of all devices
matrix.led(0, 0, 0);

// I2C device (bicolor)
var matrix = new five.Led.Matrix({ 
  controller: "HT16K33",
  isBicolor: true
});
// Turn top-left led of the specified device yellow
matrix.led(0, 0, 0, LedControl.COLORS.YELLOW);

• row(row, 0-255) Set row (0-8) value to 8-bit byte (0-255), of all devices.
• row(device index, row, 0-255) Set row (0-8) value to 8-bit byte (0-255), for a device at the specified device index.

var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

// Turn on the entire first row of the specified device
matrix.row(0, 0, 255);

// Turn on the entire first row of all devices
matrix.row(0, 255);

• column(column, 0-255) Set column (0-8) value to 8-bit byte (0-255), of all devices.
• column(device index, column, 0-255) Set column (0-8) value to 8-bit byte (0-255), for a device at the specified device index.

var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

// Turn on the entire first column of the specified device
matrix.column(0, 0, 255);

// Turn on the entire first column of all devices
matrix.column(0, 255);

• draw(character) Draw a "character" to all devices.
• draw(device index, character) Draw a "character" to a device at the specified device index.

Valid "character" values:

• A single character string, eg. "A", "b", "1", "$"
• An 8 element array of 8-bit values, eg. [0x00, 0x04, 0x15, 0x0E, 0x15, 0x04, 0x00, 0x00] (That array represents * character).
• An 8 element array of 8-bit binary string values, eg.

[
  "01100110",
  "10011001",
  "10000001",
  "10000001",
  "01000010",
  "00100100",
  "00011000",
  "00000000"
];

var matrix = new five.Led.Matrix({
  pins: {
    data: 2,
    clock: 3,
    cs: 4
  }
});

var heart = [
  "01100110",
  "10011001",
  "10000001",
  "10000001",
  "01000010",
  "00100100",
  "00011000",
  "00000000"
];

// Draw a heart to the specified device
matrix.draw(0, heart);

// Draw a heart to all devices
matrix.draw(heart);

// NOTE: this is actually a predefined character
var exclamation = [
  0x04, 
  0x04, 
  0x04, 
  0x04, 
  0x00, 
  0x00, 
  0x04, 
  0x00
];

// Draw an exclamation to the specified device
matrix.draw(0, exclamation);

// Draw an exclamation to all devices
matrix.draw(exclamation);

var asterisk = "*";

// Draw an asterisk to the specified device
matrix.draw(0, asterisk);

// Draw an asterisk to all devices
matrix.draw(asterisk);

Predefined Characters

Led.Matrix.CHARS

0 1 2 3 4 5 6 7 8 9   
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ 
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` 
a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~

Events

Led.Matrix objects are output only and therefore do not emit any events.