rpi_ws281x_lua

Lua scripting interface for WS281x (NeoPixel) LED strips on Raspberry Pi.

Write Lua scripts to control WS2812, SK6812RGB, and SK6812RGBW LED strips and matrices using simple function calls, without writing C code.

Status

This project has not been tested on actual hardware. It was developed using a mock layer (ws2811_mocks.c) that simulates the WS281x driver. If you test it on real hardware, please open an issue with your results.

Features

• Control WS281x LED strips via Lua scripts
• 2D LED matrix support with (x, y) coordinate addressing
• Multiple LED ordering patterns (Z-serpentine, W-serpentine, linear)
• Configurable strip type, GPIO pin, DMA channel, and frequency
• Mock driver for development/testing without hardware
• Static binary builds for portability across Raspberry Pi models

Building

Prerequisites

• GCC (or ARM cross-compiler for cross-compilation)
• CMake 3.0+

1. Build the WS281x library

cd external/rpi_ws281x
mkdir -p build && cd build
cmake -DBUILD_SHARED=OFF -DBUILD_TEST=OFF ..
make

2. Build Lua

cd external/lua/lua-5.4.7
make

3. Build rpi_ws281x_lua

For Raspberry Pi (native or cross-compile):

cd src
gcc -static -I ../external/lua/lua-5.4.7/src -I ../external/rpi_ws281x \
    -L ../external/lua/lua-5.4.7/src -L ../external/rpi_ws281x/build \
    -o rpi_ws281x_lua main.c lua_functions.c utils.c \
    -llua -lws2811 -lm -ldl

For testing without hardware (using mock driver):

cd src
gcc -I ../external/lua/lua-5.4.7/src -I ../external/rpi_ws281x \
    -L ../external/lua/lua-5.4.7/src \
    -o rpi_ws281x_lua_test main.c lua_functions.c utils.c ws2811_mocks.c \
    -llua -lm -ldl

Usage

# Run a single Lua script
./rpi_ws281x_lua -f script.lua

# Run all scripts from a directory
./rpi_ws281x_lua -d my_scripts/

# Enable verbose logging (-v for more, -vvv for maximum)
./rpi_ws281x_lua -vv -f script.lua

Your Lua script must define a main() function:

local WIDTH = 4
local HEIGHT = 4
local STRIP_TYPE = 0x00080010 -- WS2811_STRIP_GBR

function main()
    init_ws2811(800000, 10, 18, WIDTH, HEIGHT, STRIP_TYPE, 0, string.byte("Z"))

    -- Set all LEDs to red
    for y = 0, HEIGHT - 1 do
        for x = 0, WIDTH - 1 do
            write_led_buffer(x, y, 0xFF0000)
        end
    end

    render_ws2811()
    wait_ws2811()
    fini_ws2811()
end

See the examples/ directory for more.

Lua API

Function	Description
init_ws2811(freq, dma, gpio, width, height, strip_type, invert, ordering)	Initialize the LED strip
render_ws2811()	Send the LED buffer to hardware
wait_ws2811()	Wait for DMA completion
fini_ws2811()	Clean up and release resources
set_led(x, y, color)	Set a single LED and immediately render
clear_all_leds()	Clear all LEDs and render
write_led_buffer(x, y, color)	Write to buffer without rendering
read_led_buffer(buffer)	Copy LED state to a userdata buffer

LED Ordering

The ordering parameter controls how (x, y) coordinates map to the physical LED strip:

• Z — Row-by-row serpentine (even rows left-to-right, odd rows right-to-left)
• W — Column-by-column serpentine
• = — Simple linear (left-to-right, top-to-bottom)

Strip Types

Common values for strip_type:

Constant	Value
WS2811_STRIP_RGB	0x00100800
WS2811_STRIP_GBR	0x00080010
WS2811_STRIP_GRB	0x00081000
SK6812_STRIP_RGBW	0x18100800

See the rpi_ws281x documentation for the full list.

Dependencies

• rpi_ws281x — Userspace Raspberry Pi WS281x library (included as submodule, BSD-2-Clause license)
• Lua 5.4.7 — Lua scripting language (included in external/lua/, MIT license)

License

MIT — see LICENSE.