LED Strip

The Training Village supports an addressable LED strip connected to the Raspberry Pi via SPI. The strip uses the Pi5Neo library and is configured through SETTINGS → LED STRIP SETTINGS.


Setup

Hardware connection

The LED strip connects to its designated connector on the box board (3-pin connector: 5 V, GND, and signal).

Enabling SPI

The LED strip is driven through the SPI interface, which must be enabled in Preferences → Control Centre → Interfaces (it already is in the Raspberry Pi Disk Image). For long strips or matrices, also increase the SPI buffer size, as explained in the manual installation (spidev.bufsiz).

Finding the device path

Verify the device is present:

ls /dev/spidev*

A typical output is:

/dev/spidev0.0   /dev/spidev0.1

Use the path that matches your wiring — the first device (/dev/spidev0.0) is the default.

Settings

First enable the strip with LED_STRIP_BOX (SETTINGS → BOX SETTINGS): while it is OFF, the strip is not used at all (see the note in Using It in Tasks). Then configure it under SETTINGS → LED STRIP SETTINGS. Changes are applied when Village is restarted.

SPI_DEVICE

Path of the SPI device node. Default: /dev/spidev0.0.

Change this only if you are using a non-default chip select or a second SPI bus (e.g. /dev/spidev0.1 or /dev/spidev1.0).

NUMBER_OF_LEDS

Total number of LEDs in the strip. Must match the physical strip length exactly — an incorrect value will cause some LEDs to be unreachable or produce incorrect color output.

SPI_SPEED_KHZ

SPI bus clock speed in kHz. Default: 800 (800 kHz).

Most WS2812-compatible strips work reliably at 800 kHz. If you observe flickering or communication errors, try lowering this value (e.g. 400).

PIXEL_TYPE

Color channel order of the strip’s pixels. Default: RGB. This setting must match the hardware of your specific LED strip:

Value

Description

RGB

3-channel, red–green–blue order

GRB

3-channel, green–red–blue order (most common for WS2812B)

RGBW

4-channel, with a dedicated white channel

GRBW

4-channel, green–red–blue–white order

Note

WS2812B LEDs are physically wired as GRB even though the chip is commonly called “RGB”. If colors appear swapped, switch between RGB and GRB.


Using It in Tasks

Import the module-level instance and call its methods directly:

from village.devices.led_strip import led_strip

# Set LED at index 0 to red
led_strip.set_led_color(0, 255, 0, 0)

# Set LED at index 1 to green
led_strip.set_led_color(1, 0, 255, 0)

# Apply the changes — nothing is visible until update_strip() is called
led_strip.update_strip(sleep_duration=None)

# Turn off all LEDs
led_strip.clear_strip()
led_strip.update_strip(sleep_duration=None)

Method reference

Method

Arguments

Description

set_led_color(index, red, green, blue, white=0)

index: int, colors: 0–255; white only for RGBW/GRBW strips

Stages a color change for one LED.

fill_strip(red, green, blue, white=0)

colors: 0–255

Stages the same color for every LED.

clear_strip()

—

Stages all LEDs off.

update_strip(sleep_duration=0.1)

sleep_duration: seconds, or None

Sends all staged changes to the strip, then waits sleep_duration seconds.

update_strip() waits 0.1 s by default

After sending the colors, update_strip() waits sleep_duration seconds, 0.1 by default (a value of the Pi5Neo library). The strip does not need that wait, and it blocks whatever called it: a trigger or a task would lose 100 ms on every update. Pass sleep_duration=None, as in the example above, to return as soon as the colors are sent (a few ms, see Timing).

Note

If LED_STRIP_BOX is OFF, or the strip cannot be initialised (SPI not enabled, wrong device path, etc.), the system uses a NullLEDStrip instance instead: calls to its methods have no effect, so tasks still run without errors, but nothing lights up. When the initialisation fails, an error is logged at startup.

LED matrices

Addressable LEDs are not limited to linear strips. The same hardware and settings work with 2D LED matrices, where rows of LEDs are wired end-to-end in a serpentine or sequential layout. From the software’s perspective a matrix is just a longer strip: NUMBER_OF_LEDS should be set to width × height (total pixel count), and each LED is still addressed by a single integer index.

To target a specific cell, convert its row and column to a linear index:

def led_index(row: int, col: int, width: int) -> int:
    return row * width + col

If the matrix uses a serpentine layout (alternating rows run in opposite directions, which is common in pre-assembled panels), odd rows must be mirrored:

def led_index_serpentine(row: int, col: int, width: int) -> int:
    if row % 2 == 0:
        return row * width + col
    else:
        return row * width + (width - 1 - col)