@tomsith/red-contrib-ws2812-pi5 1.0.9

Node-RED module for controlling WS2812/NeoPixel LED strips via SPI on Raspberry Pi 5

npm install @tomsith/red-contrib-ws2812-pi5

node-red-contrib-ws2812-pi5

Control WS2812 / WS2812B / NeoPixel addressable LED strips on Raspberry Pi 5 using SPI (/dev/spidev0.0) in Node-RED.

---

📋 Table of Contents

• Features
• Prerequisites
• Installation
• Hardware Setup
• Node Configuration
• Usage
  • String Colors
  • Built-in Effects
  • Hex Colors
  • Individual LED Control
• Examples
• Troubleshooting
• Safety & Best Practices
• API Reference
• License

---

✨ Features

• ✅ Raspberry Pi 5 optimized – uses SPI hardware for reliable timing
• ✅ Simple payload formats – strings, hex colors, or arrays
• ✅ Built-in effects – rainbow, lava, blink, pulse, sparkle
• ✅ Per-LED control – set individual pixel colors
• ✅ Auto-cleanup – LEDs turn off when node stops
• ✅ No sudo required – runs as normal user (with correct permissions)

---

🔧 Prerequisites

1. Enable SPI on Raspberry Pi 5

sudo raspi-config

Navigate to:
Interfacing Options → SPI → Enable

Or edit /boot/firmware/config.txt and add:

dtparam=spi=on

Reboot:

sudo reboot

2. Add User to SPI Group

sudo usermod -a -G spi $USER
sudo usermod -a -G gpio $USER

Log out and back in for group changes to take effect.

3. Verify SPI Device

ls -l /dev/spidev0.0

Should show:

crw-rw---- 1 root spi 153, 0 Jan 19 10:00 /dev/spidev0.0

4. Node-RED Requirements

• Node.js: v12.0.0 or higher
• Node-RED: v1.0.0 or higher

---

📦 Installation

Option 1: Via Node-RED Palette Manager (Recommended)

1. Open Node-RED editor
2. Click Menu (☰) → Manage palette
3. Go to Install tab
4. Search for @tomsith/red-contrib-ws2812-pi5
5. Click Install

Option 2: Via npm

cd ~/.node-red
npm install @tomsith/red-contrib-ws2812-pi5

Restart Node-RED:

node-red-restart

Or:

sudo systemctl restart nodered

---

🔌 Hardware Setup

Wiring

Raspberry Pi 5	WS2812 Strip
GPIO 10 (MOSI / SPI0_MOSI)	DIN (Data In)
GND	GND
5V (see warning)	5V / VCC

⚠️ Important Notes

1. Power Supply

   • For < 10 LEDs: Pi's 5V pin may work
   • For > 10 LEDs: Use external 5V power supply (connect GND to Pi)
   • Never power long strips from Pi's 5V rail (risk of brownout/SD corruption)

2. Logic Level

   • WS2812 expects 5V logic, Pi outputs 3.3V
   • Usually works at short distances (< 30cm wire)
   • For reliability: use a 74HCT245 level shifter or 74AHCT125 buffer

3. Common Ground

   • Always connect Pi GND to LED strip GND
   • If using external PSU, connect PSU GND to Pi GND

4. Capacitor (optional but recommended)

   • 1000µF capacitor across strip's +5V and GND (near strip input)

---

⚙️ Node Configuration

Drag ws2812-pi5 node from the palette (under hardware category).

Settings

Parameter	Description	Default
Name	Node label in flow	WS2812 Pi5
Number of LEDs	Total pixels in strip	10

Note: SPI device is fixed to /dev/spidev0.0 (Pi 5 default).

---

🎨 Usage

Send messages to the node via msg.payload.

String Colors

Use HTML color names:

msg.payload = "red";
msg.payload = "blue";
msg.payload = "green";
msg.payload = "purple";
msg.payload = "orange";
msg.payload = "white";

Supports all CSS color names (140+ colors).

---

Built-in Effects

Send effect name as string:

Effect	Description
"rainbow"	Cycles through 7 rainbow colors
"lava"	Random red/orange flicker
"blink"	White on/off toggle
"pulse"	Smooth brightness fade in/out
"sparkle"	Random white twinkles

Example:

msg.payload = "rainbow";
return msg;

Stop an effect: Send any new color/effect or turn off:

msg.payload = "black"; // turns off

---

Hex Colors

Send hex color strings:

msg.payload = "#FF5733";  // Orange-red
msg.payload = "#00FF00";  // Green
msg.payload = "#0080FF";  // Blue

---

Individual LED Control

Send an array of RGB arrays (one per LED):

msg.payload = [
  [255, 0, 0],    // LED 0: Red
  [0, 255, 0],    // LED 1: Green
  [0, 0, 255],    // LED 2: Blue
  [255, 255, 0],  // LED 3: Yellow
  [0, 0, 0]       // LED 4: Off
];
return msg;

Notes:

• Array length can be ≤ number of LEDs configured
• Missing LEDs default to [0, 0, 0] (off)
• RGB values: 0–255

---

📚 Examples

Example flows are included in examples/ folder:

• blink.json – Simple white blink effect
• single-led.json – Control one LED
• rainbow.json – Rainbow cycle
• array.json – Per-pixel color array

Import Examples

1. Menu (☰) → Import → Examples
2. Navigate to @tomsith/red-contrib-ws2812-pi5
3. Select example flow

---

🐛 Troubleshooting

LEDs don't light up

Check SPI is enabled:

lsmod | grep spi

Should show spi_bcm2835 or similar.

Check device permissions:

ls -l /dev/spidev0.0

User must be in spi group.

Check wiring:

• MOSI (GPIO 10) → DIN
• GND → GND
• 5V → VCC (with proper power supply)

---

Colors are wrong

• Green/Red swapped: Some strips use GRB order (this driver uses GRB internally, so should be correct)
• Dim/flickering: Insufficient power supply
• Random colors: Bad ground connection or signal integrity issue

---

"Cannot open SPI device" error

sudo chmod 666 /dev/spidev0.0

Or add user to spi group (see Prerequisites).

---

Effects won't stop

Send a new message with a static color:

msg.payload = "black";

Or redeploy the flow (triggers node.on("close")).

---

Only first LED works

• Data line broken after first LED
• Insufficient power causing voltage drop
• Wrong LED count in node config

---

🛡️ Safety & Best Practices

1. Never hot-plug LED strips while powered
2. Use external PSU for > 10 LEDs (5V, 60mA per LED at full white)
3. Add 1000µF capacitor across power rails near strip input
4. Use 330Ω resistor in series with data line (optional, reduces ringing)
5. Keep data wire short (< 30cm) or use level shifter for longer runs
6. Common ground between Pi and LED PSU is mandatory
7. Test with low brightness first before full white (reduces current draw)

---

📖 API Reference

Input Payload Formats

Type	Example	Description
String (color name)	"red"	HTML color name
String (hex)	"#FF0000"	Hex color code
String (effect)	"rainbow"	Built-in effect
Array of RGB	[[255,0,0], [0,255,0]]	Per-LED colors

Effects

• rainbow – 200ms cycle through 7 colors
• lava – 150ms random red/orange flicker
• blink – 500ms white on/off
• pulse – 50ms smooth fade (0–255)
• sparkle – 150ms random pixel twinkles

---

📄 License

MIT License

Copyright (c) 2024 Tom Schmitz

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

🙏 Acknowledgments

• Built for Raspberry Pi 5 SPI hardware
• Uses spi-device for SPI communication
• Inspired by various WS2812 Node-RED implementations

---

📞 Support

• Issues: GitHub Issues
• Email: [email protected]

---

Enjoy your LED projects! 🌈✨