agl-sense-hat-led

1.0.4 • Public • Published

Control a Raspberry Pi Sense HAT LED Display with Node.js

Node module to control the Raspberry Pi Sense HAT 8x8 RGB LED matrix using javascript, used in the Astro Pi mission. Hardware

Note

This is a fork of trbll/sense-hat-led that updates dependencies for at least Node v12.

(Originally a fork of Jochen Hinrichsen's sense-hat-matrix library).

Install:

Install the Sense HAT software by opening a Terminal window and entering the following commands (while connected to the Internet):

npm install sense-hat-led

Usage:

example:

"use strict";
const sense = require("sense-hat-led");

sense.setPixel(0, 7, [244, 0, 0], (err) => {
  sense.getPixel(0, 7, (err, color) => {
    console.log(color);  
  })
});

API should follow the sense hat python library except all methods names are in camelCase and an added callback as the last parameter of the asynchronous methods. The callbacks are passed arguments (err, data), where data is the return value (if any) of the synchronous version of the function.

The synchronous functions are methods of the sync object.

example:

"use strict";
const sense = require("sense-hat-led").sync;

sense.setPixel(0, 7, [244, 0, 0]);
var color = sense.getPixel(0,7);

All LED Matrix methods are implemented. For sensors use nodeimu.

Sense HAT LED MATRIX API Reference

setRotation(r, [redraw])

setRotation(r, [redraw], callback)

If you're using the Pi upside down or sideways you can use this function to correct the orientation of the image being shown.

Parameter Type Valid values Explanation
r Integer 0 90 180 270 The angle in degrees to rotate the LED matrix though. 0 is with the Raspberry Pi HDMI port facing downwards.
redraw Boolean true false Whether or not to redraw what is already being displayed on the LED matrix. Defaults to true
Returned / callback data type Explanation
None
var sense = require("sense-hat-led");

sense.setRotation(180);
# alternatives
sense.rotation = 180;

flipH([redraw])

Flips the image on the LED matrix horizontally.

Parameter Type Valid values Explanation
redraw Boolean true false Whether or not to redraw what is already being displayed on the LED matrix. Defaults to true
Returned / callback data type Explanation
Array An array containing 64 smaller arrays of [R, G, B] pixels (red, green, blue) representing the flipped image.
var sense = require("sense-hat-led").sync;

sense.flipH();

flipV([redraw])

Flips the image on the LED matrix vertically.

Parameter Type Valid values Explanation
redraw Boolean true false Whether or not to redraw what is already being displayed on the LED matrix when flipped. Defaults to true
Returned / callback data type Explanation
Array An array containing 64 smaller arrays of [R, G, B] pixels (red, green, blue) representing the flipped image.
var sense = require("sense-hat-led");

sense.flipV(false,  (err, pixelArray)=>{
 if err return colsole.err(err);
 console.log('Flipped Array: ');
 console.log(pixelArray);
}););

setPixels(pixelArray)

Updates the entire LED matrix based on a 64 length array of pixel values.

Parameter Type Valid values Explanation
pixelArray Array [[R,G,B]*64] An array containing 64 smaller arrays of [R, G, B] pixels (red, green, blue). Each R-G-B element must be an integer between 0 and 255.
Returned / callback data type Explanation
None
var sense = require("sense-hat-led");

var X = [255, 0, 0];  // Red
var O = [255, 255, 255];  // White

var questionMark = [
O, O, O, X, X, O, O, O,
O, O, X, O, O, X, O, O,
O, O, O, O, O, X, O, O,
O, O, O, O, X, O, O, O,
O, O, O, X, O, O, O, O,
O, O, O, X, O, O, O, O,
O, O, O, O, O, O, O, O,
O, O, O, X, O, O, O, O
];

sense.setPixels(questionMark);

getPixels()

Returned / callback data type Explanation
Array An array containing 64 smaller arrays of [R, G, B] pixels (red, green, blue) representing the currently displayed image.
var sense = require("sense-hat-led").sync;

var pixelArray = sense.getPixels();

async:

var sense = require("sense-hat-led");

sense.getPixels((err, pixelArray)=>{
  console.log(pixelArray[0])
});

Note: You will notice that the pixel values you pass into setPixels sometimes change when you read them back with getPixels. This is because we specify each pixel element as 8 bit numbers (0 to 255) but when they're passed into the Linux frame buffer for the LED matrix the numbers are bit shifted down to fit into RGB 565. 5 bits for red, 6 bits for green and 5 bits for blue. The loss of binary precision when performing this conversion (3 bits lost for red, 2 for green and 3 for blue) accounts for the discrepancies you see.

The getPixels function provides a correct representation of how the pixels end up in frame buffer memory after you've called setPixels.


setPixel(x, y, r, g b)

or

setPixel(x, y, rgb)

Sets an individual LED matrix pixel at the specified X-Y coordinate to the specified colour.

Parameter Type Valid values Explanation
x Integer 0-7 0 is on the left, 7 on the right.
y Integer 0-7 0 is at the top, 7 at the bottom.
Colour can either be passed as an RGB array:
pixel Array (r, g, b) Each element must be an integer between 0 and 255.
Or three separate values for red, green and blue:
r Integer 0-255 The Red element of the pixel.
g Integer 0-255 The Green element of the pixel.
b Integer 0-255 The Blue element of the pixel.
Returned / callback data type Explanation
None
var sense = require("sense-hat-led").sync;

// examples using (x, y, r, g, b)

sense.setPixel(0, 0, 255, 0, 0);
sense.setPixel(0, 7, 0, 255, 0);
sense.setPixel(7, 0, 0, 0, 255);
sense.setPixel(7, 7, 255, 0, 255);

red = [255, 0, 0];
green = [0, 255, 0];
blue = [0, 0, 255];

// examples using (x, y, pixel)

sense.setPixel(0, 0, red);
sense.setPixel(0, 0, green);
sense.setPixel(0, 0, blue);

getPixel(x, y)

Parameter Type Valid values Explanation
x Integer 0 - 7 0 is on the left, 7 on the right.
y Integer 0 - 7 0 is at the top, 7 at the bottom.
Returned / callback data type Explanation
Array Returns An array of [R, G, B] representing the colour of an individual LED matrix pixel at the specified X-Y coordinate.
var sense = require("sense-hat-led").sync;

var topLeftPixel = sense.getPixel(0, 0);

async:

var sense = require("sense-hat-led");

sense.getPixel(0, 0 , (err, topLeftPixel)=>{
  console.log(topLeftPixel[0]); // red value
});

Note: Please read the note under getPixels


loadImage(filePath, [redraw])

Loads an image file, converts it to RGB format and displays it on the LED matrix. The image must be 8 x 8 pixels in size.

Parameter Type Valid values Explanation
filePath String Any valid file path. The file system path to the image file to load.
redraw Boolean true false Whether or not to redraw the loaded image file on the LED matrix. Defaults to true
var sense = require("sense-hat-led");

sense.loadImage("space_invader.png");
Returned / callback data type Explanation
Array An array containing 64 smaller arrays of [R, G, B] pixels (red, green, blue) representing the loaded image after RGB conversion.
var sense = require("sense-hat-led").sync;

var invaderPixels = sense.loadImage("space_invader.png", redraw=false);

async:

var sense = require("sense-hat-led");

sense.loadImage("space_invader.png", redraw=false, (err, invaderPixels) =>{
  console.log(invaderPixels.length);
});

clear(colour)

or

clear(r,g,b)

Sets the entire LED matrix to a single colour, defaults to blank / off.

Parameter Type Valid values Explanation
colour Array (r,g,b) An array containing the RGB (red, green, blue) values of the colour. Each element must be an integer between 0 and 255. Defaults to (0, 0, 0).

Alternatively, the RGB values can be passed individually:

Parameter Type Valid values Explanation
r Integer 0 - 255 The Red element of the colour.
g Integer 0 - 255 The Green element of the colour.
b Integer 0 - 255 The Blue element of the colour.
var sense = require("sense-hat-led").sync;

var red = [255, 0, 0];

sense.clear();  // no arguments defaults to off
sense.clear(red) // passing in an RGB array
sense.clear(255, 255, 255);  // passing in r, g and b values of a colour

showMessage(textString, [scrollSpeed, textColour, backColour])

Scrolls a text message from right to left across the LED matrix and at the specified speed, in the specified colour and background colour.

Parameter Type Valid values Explanation
textString String Any text string. The message to scroll.
scrollSpeed Number Any positive number. The speed at which the text should scroll. This value represents the time in seconds paused for between shifting the text to the left by one column of pixels. Defaults to 0.1
textColour Array [R,G,B] An array containing the R-G-B (red, green, blue) colour of the text. Each R-G-B element must be an integer between 0 and 255. Defaults to [255, 255, 255] white.
backColour Array [R,G,B] An array containing the R-G-B (red, green, blue) colour of the background. Each R-G-B element must be an integer between 0 and 255. Defaults to [0, 0, 0] black / off.
Returned / callback data type Explanation
None

Sync:

var sense = require("sense-hat-led").sync;

sense.showMessage("One small step for Pi!");
// or
sense.showMessage("One giant leap for Pikind!", 0.2, [255,0,0], [0,255,0]);

Async:

var sense = require("sense-hat-led");

sense.showMessage("One small step for Pi!", 0.1, [255, 0, 0], done);

function done(){
  console.log("finished message");
}

showLetter(character, [textColour, backColour])

Displays a single text character on the LED matrix.

Parameter Type Valid values Explanation
character String A text string of length 1. The letter to show.
textColour Array [R,G,B] An array containing the R-G-B (red, green, blue) colour of the letter. Each R-G-B element must be an integer between 0 and 255. Defaults to [255, 255, 255] white.
backColour Array [R,G,B] An array containing the R-G-B (red, green, blue) colour of the background. Each R-G-B element must be an integer between 0 and 255. Defaults to [0, 0, 0] black / off.
Returned / callback data type Explanation
None
var sense = require("sense-hat-led").sync;


for (var i = 10; i > 0; i--){
    sense.showLetter(i.toString());
    sense.sleep(0.5);
}

async:

var sense = require("sense-hat-led");

function flash(message) {
  if (message.length === 0) return;
    
  showLetter(message[0], () => {
    if (error) return console.error(error.message);
    setTimeout(flash, speed * 1000, message.slice(1));
  });
}

flash("hello");
  

flashMessage(textString, [speed, textColour, backColour])

, Flashes a text message one character at a time LED matrix and at the specified speed, in the specified colour and background colour.

Parameter Type Valid values Explanation
textString String Any text string. The message to flash.
speed Number Any number. The speed at which the text should flash. This value represents the time in seconds paused for between letters. Defaults to 0.1
textColour Array [R,G,B] An array containing the R-G-B (red, green, blue) colour of the text. Each R-G-B element must be an integer between 0 and 255. Defaults to [255, 255, 255] white.
backColour Array [R,G,B] An array containing the R-G-B (red, green, blue) colour of the background. Each R-G-B element must be an integer between 0 and 255. Defaults to [0, 0, 0] black / off.
Returned / callback data type Explanation
None
var sense = require("sense-hat-led");

sense.flashMessage("One small step for Pi!", 0.2);

lowLight

Toggles the LED matrix low light mode, useful if the Sense HAT is being used in a dark environment.

var sense = require("sense-hat-led").sync;

sense.clear(255, 255, 255);
sense.lowLight = true;
sense.sleep(2);
sense.lowLight = false;

gamma

For advanced users. Most users will just need the lowLight Boolean property above. The Sense HAT API uses 8 bit (0 to 255) colours for R, G, B. When these are written to the Linux frame buffer they're bit shifted into RGB 5 6 5. The driver then converts them to RGB 5 5 5 before it passes them over to the ATTiny88 AVR for writing to the LEDs.

The gamma property allows you to specify a gamma lookup table for the final 5 bits of colour used. The lookup table is a list of 32 numbers that must be between 0 and 31. The value of the incoming 5 bit colour is used to index the lookup table and the value found at that position is then written to the LEDs.

Type Valid values Explanation
Array Array of length 32 containing Integers between 0 and 31 Gamma lookup table for the final 5 bits of colour
var sense = require("sense-hat-led").sync;

sense.clear(255, 127, 0);
console.log(sense.gamma);
sense.sleep(2);

sense.gamma = sense.gamma.reverse();
console.log(sense.gamma);
sense.sleep(2);

sense.lowLight = true;
console.log(sense.gamma);
sense.sleep(2);

sense.lowLight = false;

gammaReset()

A function to reset the gamma lookup table to default, ideal if you've been messing with it and want to get it back to a default state.

Returned: none

var sense = require("sense-hat-led").sync;

sense.clear(255, 127, 0);
sense.sleep(2);
sense.gamma = new Array(32).fill(0);  // Will turn the LED matrix off
sense.sleep(2);
sense.gammaReset();

sleep(time)

NOTE: Synchronous only. These calls will block execution of all JavaScript by halting Node.js' event loop!!

for the asynchronous functions use setTimeout instead.

Parameter Type Valid values Explanation
time Number Any number. the time in seconds to pause
Returned / callback data type Explanation
None
var sense = require("sense-hat-led").sync;


function flashRed(){
  sense.clear([255, 0, 0]);
  sense.sleep(0.1);
  sense.clear(); 
}

asynchronous alternative (recommended)

var sense = require("sense-hat-led");

function flashRed(){
  sense.clear([255, 0, 0]);
  setTimeout(sense.clear, 100);
}

// or

function flashGreenThenDoSomething(callback){
  sense.clear([0, 0, 255]);
  setTimeout(sense.clear, 100, callback);
}

// or with error checking

function flashBlueThenDoSomething(callback){
  sense.clear([0, 255, 0], (err) => {
    if (err) return console.error(err.message);
    setTimeout(() => {
      sense.clear((err) => {
        if (err) return console.error(err.message);
        callback(null);
      }
    }), 100);
  });
}

Package Sidebar

Install

npm i agl-sense-hat-led

Weekly Downloads

1

Version

1.0.4

License

MIT

Unpacked Size

44.4 kB

Total Files

8

Last publish

Collaborators

  • premkumars