Pi5Neo

Simplifying NeoPixel LED Control on Raspberry Pi 5 via SPI (GPIO 10)

Pi5Neo is a Python library for controlling NeoPixel LED strips on the Raspberry Pi 5 (or equivalent boards) over the SPI interface. It supports both RGB (WS2812B) and RGBW (SK6812) strips, exposes a clean context-manager API, and ships with a growing set of ready-to-run examples.

---

What's New in v1.1.0

• RGBW / SK6812 support — new EPixelType enum (RGB, GRB, RGBW, GRBW) lets you select the exact channel order for your strip hardware.
• LEDColor dataclass — represent colors as structured objects; read back any LED's current state with get_led_color().
• set_led_color_object() / get_led_color() — object-oriented helpers alongside the existing index-based API.
• Context-manager support — with Pi5Neo(...) as neo: guarantees the strip is cleared and SPI is released on exit, even after exceptions.
• quiet_mode parameter — suppress all console output for production scripts.
• Configurable update_strip delay — pass sleep_duration=None to skip the latch delay, or any float for custom timing.
• Reorganised examples — split into basic/, animations/, and effects/ sub-directories with clean, well-commented scripts.
• Deprecated helpers — rgb_to_spi_bitstream() and rgbw_to_spi_bitstream() now emit DeprecationWarning; use color_to_spi_bitstream() instead.

---

Key Features

• RGB and RGBW support — WS2812B (GRB) and SK6812 (RGBW/GRBW) out of the box.
• LEDColor dataclass — structured colour values with per-channel access.
• Context-manager API — automatic cleanup with with statements.
• Quiet mode — silence all print output for daemon/production use.
• Smooth animations — rainbow, breathing, comet, meteor, fireworks, theater chase, and more.
• Minimal dependencies — only spidev required.
• High LED count support — configurable kernel SPI buffer for 170+ LEDs.

---

Installation

pip install pi5neo

Requirements

• Python 3.6+
• spidev (installed automatically)

Hardware

• Raspberry Pi 5 (or equivalent board with SPI)
• NeoPixel LED strip — WS2812B (RGB/GRB) or SK6812 (RGBW/GRBW)

---

Setup: Enable SPI

sudo raspi-config
# → 3 Interface Options → I4 SPI → Yes

---

Quick Start

from pi5neo import Pi5Neo

# Initialize with 10 LEDs at 800 kHz on /dev/spidev0.0
neo = Pi5Neo('/dev/spidev0.0', num_leds=10, spi_speed_khz=800)

neo.fill_strip(255, 0, 0)   # Red
neo.update_strip()

neo.set_led_color(4, 0, 0, 255)  # Blue on LED #5
neo.update_strip()

Context Manager (recommended)

The strip is always cleared and SPI released on exit, even if an exception occurs:

from pi5neo import Pi5Neo

with Pi5Neo('/dev/spidev0.0', num_leds=10, spi_speed_khz=800, quiet_mode=True) as neo:
    neo.fill_strip(0, 255, 0)   # Green
    neo.update_strip()
    # SPI closed and strip cleared automatically here

RGBW / SK6812 Strips

from pi5neo import Pi5Neo, EPixelType

with Pi5Neo('/dev/spidev0.0', num_leds=10, spi_speed_khz=800,
            pixel_type=EPixelType.GRBW, quiet_mode=True) as neo:
    neo.fill_strip(0, 0, 0, 255)   # White channel only
    neo.update_strip()

LEDColor Objects

from pi5neo import Pi5Neo, LEDColor

with Pi5Neo('/dev/spidev0.0', num_leds=10, spi_speed_khz=800, quiet_mode=True) as neo:
    color = LEDColor(red=255, green=128, blue=0)
    neo.set_led_color_object(0, color)
    neo.update_strip()

    # Read the current colour of any LED
    current = neo.get_led_color(0)
    print(current)   # LEDColor(red=255, green=128, blue=0, white=0)

---

API Reference

Pi5Neo(spi_device, num_leds, spi_speed_khz, pixel_type, quiet_mode)

Parameter	Type	Default	Description
spi_device	str	'/dev/spidev0.0'	SPI device path
num_leds	int	10	Number of LEDs in the strip
spi_speed_khz	int	800	SPI clock speed in kHz
pixel_type	EPixelType	EPixelType.GRB	Channel order — RGB, GRB, RGBW, or GRBW
quiet_mode	bool	False	Suppress all console output

Methods

Method	Description
fill_strip(r, g, b, w=0)	Set every LED to the same colour
set_led_color(index, r, g, b, w=0)	Set a single LED by index
set_led_color_object(index, LEDColor)	Set a single LED using an LEDColor instance
get_led_color(index)	Return the current LEDColor for an LED (copy)
clear_strip()	Turn off all LEDs
update_strip(sleep_duration=0.1)	Flush state to the strip; pass None to skip latch delay
close()	Close the SPI device

EPixelType

Value	Strip type
EPixelType.GRB	WS2812B (most common)
EPixelType.RGB	Some RGB strips
EPixelType.GRBW	SK6812 RGBW (GRB channel order)
EPixelType.RGBW	SK6812 RGBW (RGB channel order)

LEDColor

from pi5neo import LEDColor

c = LEDColor(red=255, green=0, blue=128, white=0)

All fields default to 0. The white field is only used with RGBW pixel types.

---

Examples

Examples are organized under the examples/ directory:

examples/
├── basic/
│   ├── example_usage.py      # Solid color + rainbow cycle
│   ├── single_led.py         # Single LED control
│   ├── random_blink.py       # Random blinking LEDs
│   ├── pixel_types.py        # EPixelType demo (RGB / RGBW)
│   ├── led_color_object.py   # LEDColor dataclass + color shifting
│   └── context_manager.py    # Context manager / safe cleanup
├── animations/
│   ├── breath.py             # Breathing / pulse effect
│   ├── fade.py               # Fade in / fade out
│   ├── smooth_fade.py        # Cosine smooth fade
│   ├── rainbow.py            # Rainbow wave
│   └── thinking.py           # "Thinking" spinner animation
└── effects/
    ├── comet.py              # Comet tail
    ├── meteor.py             # Meteor shower
    ├── firework.py           # Firework burst
    ├── knight_rider.py       # Knight Rider scanner
    ├── snake.py              # Snake crawl
    ├── ripple.py             # Ripple effect
    ├── twinkle.py            # Random twinkle
    ├── loading.py            # Loading bar
    ├── colour_bounce.py      # Colour bounce
    └── theater_chase.py      # Theater chase

---

Driving High LED Counts

The default spidev kernel buffer is 4096 bytes, which supports up to ~170 LEDs. For larger strips, increase the buffer by appending to the single line in /boot/firmware/cmdline.txt and rebooting:

spidev.bufsiz=32768

For RGBW strips the per-LED byte cost is higher (32 bytes vs. 24), so adjust accordingly.

---

Contributing

1. Fork the repo.
2. Create a branch: git checkout -b my-feature
3. Commit your changes: git commit -m 'Add new feature'
4. Push: git push origin my-feature
5. Open a Pull Request.

Issues and feature requests are welcome!

---

License

MIT License — see LICENSE for details.

---

Acknowledgements

Pi5Neo was inspired by various open-source NeoPixel and SPI projects. Thanks to all contributors and to the maintainers of spidev and the Raspberry Pi ecosystem.

---

Useful Links

• Pi5Neo on PyPI
• Pi5Neo GitHub Repository
• Raspberry Pi Official Website