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 |
|---|---|
|
3-channel, red–green–blue order |
|
3-channel, green–red–blue order (most common for WS2812B) |
|
4-channel, with a dedicated white channel |
|
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 |
|---|---|---|
|
|
Stages a color change for one LED. |
|
colors: 0–255 |
Stages the same color for every LED. |
|
— |
Stages all LEDs off. |
|
|
Sends all staged changes to the strip, then waits |
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)