Skip to content

Latest commit

 

History

History
96 lines (63 loc) · 3.57 KB

README.md

File metadata and controls

96 lines (63 loc) · 3.57 KB
Raw

🚥 piixel

Control WS281X LEDs from a Raspberry Pi using TypeScript / Node.js

This is a Node.js / Node-API wrapper around the rpi-ws281x library.

Requirements

  • Raspberry Pi (Tested on Raspberry Pi 4 Model B). NOTE: It will NOT work on Raspberry Pi 5, see: jgarff/rpi_ws281x#528 for details.
  • A WS281X LED Strip, for example one of the many Adafruit NeoPixels
  • Node.js v18.x or later

Installation

Note: This package will only work on a Raspberry Pi.

npm install piixel

# or if you prefer to install it system-wide
npm install -g piixel

Usage

See API documentation and the examples directory.

Minimal Example

This will light up all LEDs in different colors of the color wheel.

// example.ts

import {colorwheel, StripType, ws281x} from 'piixel'

const LEDS = 16

// Configure the library. Must be called before calling `render`.
// See APIDocs for the full list of options
// https://github.com/bjoerge/pipixel/blob/main/docs/piixel.ws281xconfig.md
ws281x.configure({
  gpio: 18,
  leds: LEDS,
  type: StripType.WS2811_STRIP_GRB,
})

const pixels = new Uint32Array(LEDS)
for (let i = 0; i < LEDS; i++) {
  pixels[i] = colorwheel((i * 256) / LEDS)
}

// Render pixels to the LED strip
ws281x.render(pixels)

// Optionally, render with brightness
ws281x.render({pixels, brightness: 0.4})

Use ts-node or tsx to run

tsx ./example.ts

Note: Depending on which GPIO pin you use, you might need to run the script with sudo. See the README of rpi-ws281x for more information.

Development

Since this library only works on a Raspberry Pi, development on other platforms becomes a bit cumbersome. To make it easier to develop on your local machine, there's a MOCK_PIIXEL environment variable that can be set that will mock the hardware module and instead allow you to (optionally) render pixels to the terminal. terminal-mock.gif

The environment variable can be set to the following values:

  • 1 - Enables terminal rendering, and renders all pixels in a single row.
  • -1 – Enables mocking, but turns off terminal rendering.
  • n - Distributes pixels across n rows.
  • HxW - Renders pixels in an HxW grid. Any pixel outside the HxW grid will be ignored.

Examples:

  • MOCK_PIIXEL=1 tsx ./my-example.ts - Renders all pixels in a single row.
  • MOCK_PIIXEL=8 tsx ./my-example.ts - Distributes pixels in an 8xN grid.
  • MOCK_PIIXEL=8x8 tsx ./my-example.ts - Renders pixels in an 8x8 square. Any pixel outside the 8x8 grid will be ignored.
  • MOCK_PIIXEL=-1 tsx ./my-example.ts - Mock the hardware module, but don't render anything to the terminal.

Credits

  • Thanks to Jeremy Garff for writing and maintaining the rpi-ws281x C library.

  • This project has taken a lot of inspiration from meg768/rpi-ws281x. It originally started as an attempt to make it work on a Raspberry Pi 4b, but I kept running into issues with random memory corruptions, so figured I'd instead write something from scratch using the Node-API, which is more stable and future-proof than the legacy Native Abstractions for Node.js (NAN) used in that module. After the rewrite, the memory corruptions were gone.

License

MIT