shl

sense-hat-led

Raspberry Pi Sense HAT LED matrix driver

Showing:

Popularity

Downloads/wk

120

GitHub Stars

21

Maintenance

Last Commit

2yrs ago

Contributors

5

Package

Dependencies

3

Size (min+gzip)

22.9KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

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

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.

ParameterTypeValid valuesExplanation
rInteger0 90 180 270The angle in degrees to rotate the LED matrix though. 0 is with the Raspberry Pi HDMI port facing downwards.
redrawBooleantrue falseWhether or not to redraw what is already being displayed on the LED matrix. Defaults to true
Returned / callback data typeExplanation
None
var sense = require("sense-hat-led");

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

flipH([redraw])

Flips the image on the LED matrix horizontally.

ParameterTypeValid valuesExplanation
redrawBooleantrue falseWhether or not to redraw what is already being displayed on the LED matrix. Defaults to true
Returned / callback data typeExplanation
ArrayAn 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.

ParameterTypeValid valuesExplanation
redrawBooleantrue falseWhether or not to redraw what is already being displayed on the LED matrix when flipped. Defaults to true
Returned / callback data typeExplanation
ArrayAn 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.

ParameterTypeValid valuesExplanation
pixelArrayArray[[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 typeExplanation
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 typeExplanation
ArrayAn 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.

ParameterTypeValid valuesExplanation
xInteger0-70 is on the left, 7 on the right.
yInteger0-70 is at the top, 7 at the bottom.
Colour can either be passed as an RGB array:
pixelArray(r, g, b)Each element must be an integer between 0 and 255.
Or three separate values for red, green and blue:
rInteger0-255The Red element of the pixel.
gInteger0-255The Green element of the pixel.
bInteger0-255The Blue element of the pixel.
Returned / callback data typeExplanation
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)

ParameterTypeValid valuesExplanation
xInteger0 - 70 is on the left, 7 on the right.
yInteger0 - 70 is at the top, 7 at the bottom.
Returned / callback data typeExplanation
ArrayReturns 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.

ParameterTypeValid valuesExplanation
filePathStringAny valid file path.The file system path to the image file to load.
redrawBooleantrue falseWhether 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 typeExplanation
ArrayAn 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.

ParameterTypeValid valuesExplanation
colourArray(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:

ParameterTypeValid valuesExplanation
rInteger0 - 255The Red element of the colour.
gInteger0 - 255The Green element of the colour.
bInteger0 - 255The 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.

ParameterTypeValid valuesExplanation
textStringStringAny text string.The message to scroll.
scrollSpeedNumberAny 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
textColourArray[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.
backColourArray[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 typeExplanation
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.

ParameterTypeValid valuesExplanation
characterStringA text string of length 1.The letter to show.
textColourArray[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.
backColourArray[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 typeExplanation
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.

ParameterTypeValid valuesExplanation
textStringStringAny text string.The message to flash.
speedNumberAny number.The speed at which the text should flash. This value represents the time in seconds paused for between letters. Defaults to 0.1
textColourArray[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.
backColourArray[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 typeExplanation
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.

TypeValid valuesExplanation
ArrayArray of length 32 containing Integers between 0 and 31Gamma 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.

ParameterTypeValid valuesExplanation
timeNumberAny number.the time in seconds to pause
Returned / callback data typeExplanation
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);
  });
}


Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial