Neopixels for Raspberry Pi
npm install rpi-neopixelsA lightweight Node.js library for driving WS281x / NeoPixel LEDs on Raspberry Pi.
This version focuses on synchronous, blocking rendering, including built‑in support for fade transitions handled inside render().
---
- Direct, synchronous LED rendering (no async / await required)
- Smooth fading transitions handled internally
- RGB and RGBW support (0xWWRRGGBB or 0x00RRGGBB)
- Works with Uint32Array buffers
- Optional serpentine mapping for LED matrices
---
``bash`
npm install rpi-neopixels
---
`js
const neo = require('rpi-neopixels');
// Configure strip or matrix
neo.configure({ leds: 64, gpio: 18, brightness: 128, stripType: 'rgb' });
const next = new Uint32Array(64).fill(0x000000FF); // blue
// Fade from previous frame to blue over 500 ms
neo.render(next, { fade: true, durationMs: 500 });
// Instant update (no fade)
neo.render(next);
// Gamma-corrected fade example
neo.render(next, { fade: true, durationMs: 700, gamma: 2.2 });
`
---
Initializes the LED driver.
Common options:
- leds (number) – total number of LEDsgpio
- (number) – BCM pin (e.g., 18)brightness
- (0–255) – global brightnessstripType
- (string) – rgb, grb, rgbw, etc.width
- / height (number, optional) – for LED matricesmap
- (Uint32Array or 'serpentine', optional) – custom index mapping
---
Renders the current pixel buffer to the LED strip or matrix, with optional blocking fade transitions handled entirely inside the function.
This function is synchronous — it does not use promises or async/await — and will block the Node.js event loop while the fade is in progress.
#### Parameters
| Name | Type | Default | Description |
| -------------------- | -------- | ------------------- | ------------------------------------------------------------ |
| options | object | {} | Optional configuration object |options.transition
| | 'fade' | – | When set to 'fade', performs a synchronous cross-fade between frames. |options.duration
| | number | 100 | Fade duration in milliseconds. Values ≤ 0 disable the fade (instant draw). |options.speed
| | number | (auto-calibrated) | Optional override for step speed. If omitted, the method measures its own runtime and updates this.speed adaptively. |
#### Behavior
1. Uses the previously rendered frame (this.content) as the start frame this.pixels
and the current frame () as the target.numSteps = duration * this.speed
2. Calculates . 0xRRGGBB
This determines how many intermediate frames will be rendered.
3. For each step:
- Unpacks RGB channels from both frames ().red = r1 + (step * (r2 - r1)) / numSteps
- Linearly interpolates each color component:
(same for green and blue).this.tmp[i] = (red << 16) | (green << 8) | blue
- Packs the interpolated color into .ws281x.render(this.tmp)
- Calls to display the intermediate frame.this.speed
4. After the fade completes:
- Updates if options.speed was not specified this.pixels
(simple moving average based on measured duration).
- Copies into this.content (new “previous” frame).ws281x.render(this.pixels)
- Performs a final to show the exact target frame.
#### Notes
- Color values are truncated to integers through bitwise operations.
No rounding or clamping is applied.
- Operates on RGB only (0xRRGGBB); white channel is ignored.speed
- Fades are blocking — while in progress, no other JavaScript executes.
- auto-adjustment provides smoother fades over time
without manual calibration.
- After each fade, the exact target frame is re-rendered once for consistency.
#### Example
`js
// Instant draw (no fade)
pixels.fill(0xFF0000); // red
renderer.pixels = pixels;
renderer.render();
// 300 ms blocking fade to blue
pixels.fill(0x0000FF);
renderer.pixels = pixels;
renderer.render({ transition: 'fade', duration: 300 });
`
Turns off the LEDs and releases driver resources.
---
- Solid color fill
- Smooth fade‑in/out transitions
- Matrix serpentine animations
> Tip: Use gamma correction (e.g., gamma: 2.2) for visually linear fades.
---
`bash`
npm install
npm test
npm run lint
---
MIT
---
⚠️ Note: render()` is fully synchronous and will block the Node.js event loop during fades.
If non‑blocking behavior is needed, handle fades in a separate process or thread.