sled: The satanic LED controller

Modular LED Matrix controller.

Manual

Read the Satanic Bible by Anton Szandor LaVey.

Getting started (SDL2 Tutorial for Development)

• Debian:

sudo apt-get install gcc make git libsdl2-dev
git clone https://github.com/shinyblink/sled.git
cd sled
make
./sled

• Nix:

git clone https://github.com/shinyblink/sled.git
cd sled
nix-shell --run make
./sled

You can overwrite the default build by using sledconf locally. Examples are given in the Makefiles/ folder. You might just copy one e.g. cp Makefiles/sledconf.sdl2 sledconf to get a sensible initial configuration.

Getting started on developing modules

This assumes you already got something to run (see Getting Started)

How to select modules

Modules are compiled into *.so files into modules/. You can delete any module you don't want to run from the modules/ folder.

Additionally the GNUmakefile includes the sledconf file which selects which modules are build with the MODULES variable. It should contain at least one outputmodule and one additional module to run. Please copy a file from Makefiles/ to sledconf for changing your build locally and don't change the GNUmakefile.

MODULES := $(MODULES_DEFAULT) out_$(DEFAULT_OUTMOD)

This will build all modules that are listed in the GNUmakefile.

MODULES := out_$(DEFAULT_OUTMOD)
MODULES += gfx_newshinyeffect
MODULES += gfx_another_effect gfx_effect3

Only the listed modules will be build. This is good for testing. The third line can be commented out fast (by putting a # in front of the line) so only gfx_newshinyeffect will be build.

The old modules will still be in the modules/ folder and thus will still be loaded by sled. You can remove them with rm modules/gfx_* or make clean before building with make.

Build a new module

The sources for the modules are located in src/modules/. Looking inside a graphic effect module (e.g. gfx_rainbow.c) you see that gfx modules provide an interface via four functions.

int init(int moduleno, char* argstr); // Called once at program start
int deinit(int moduleno); // Called once on program exit
void reset(int moduleno); // Called on module change to this module
int draw(int moduleno, int argc, char* argv[]); // Called once per frame

All other functions and variables should be declared static and used internally only.

The draw(...) function should returns 0 while the module is running and 1 if it's done. Also each module has it's own timer that is controlled with timer_add(...) from timers.h that controls the next time draw(...) is called. This mechanism allows modules to control their own framerates. You can use matrix_set(...) and matrix_render() to output images platform independently.

To get an idea of how gfx_* modules work just look (and copy/modify) some modules.

Testing

If you wrote a module add it to MODULES in sledconf to test it locally or add it to MODULES_DEFAULT in the GNUmakefile if it's done.

Also try it with different output sizes. MATRIX_X and MATRIX_Y can be used to control the output size for the sdl2 output.

Before you commit/merge into master

Check that:

• [ ] It compiles after a make clean

• [ ] It works with other modules and quits after a reasonable time

• [ ] It works with different display sizes

  • [ ] not 2^n
  • [ ] Landscape
  • [ ] Portrait
  • [ ] small sizes (<=16x16)
  • [ ] big sizes (>=256x256)

• [ ] It has a short description

• [ ] It's well formatted (no mixed tabs/spaces) (have you considered astyle)

Hardware

Matrix consisting of ws2812b pixels, or HUB75/HUB75E LED matrix panels. Minimum recommended size of a matrix is 8x8, anything less and you won't see much of the effects.

Can handle a ~~maximum 256x256~~ pretty ridiculous matrix (switched to ints) in either plain or snake tiling. Plain means every row starts with the left pixel, while snake means it changes starting position every tile. Both start upper left, as that is (0, 0) for this code.

Connected to the ports of the specific board you're using.

• Raspberry Pi (Zero): See rpi_ws281x.

• I can recommend using PCM, little chance it is used. It is used by default. Pin 40 on the Zero.

• You might need a level shifter to shift the 3.3V logic level to 5V the strips want.

• ESP8266 DevBoard with UDP Sketch

• Uses output D2 by default, but you can use almost anything the Adafruit NeoPixel library supports.

• You might need a level shifter to shift the 3.3V logic level to 5V the strips want.

• ESP32 DevBoard

  • Supported via FreeRTOS.
  • Use Makefiles/sledconf.esp32 as the reference.
  • Use make libsled.a to build the shared library (firmware binary not yet provided)
  • Make sure to pull in the needed FreeRTOS dependencies via platformio.
  • Alternatively use Docker for building: docker build -f scripts/Dockerfile.esp32 -t esp32-builder . && docker run -v$PWD:/home/build/sled/ esp32-builder

• Raspberry Pi 3: Bitbanging HUB75 LED panels.

• High performance RaspberryPi is needed as bitbanging is quite resource intensive.

• iCEBreaker FPGA with LED Panel Driver Pmod

• You can use the MPSSE SPI sled output module in combination with @smunaut rgb_led panel design.

Note: When buying HUB75 LED panels be very careful what shift registers are used for the panel. When buying from Aliexpress you should explicitly ask for Panels with the ICN2037. Note: If you have HUB75 LED panels that use for example the FM6126A shift registers you will need a driver that can set up the panels on power up. For more information refer to the lengthy discussion on hzeller's RPi LED Matrix repo.

Building Options

Common:

• Some C99 compiler
• Some libc
• GNU Make

Platforms might need additional dependencies, check below.

Your local SLED configuration is in sledconf, which is thus .gitignore'd by default. Examples are given in the Makefiles directory, check sledconf.*. It can override various settings:

• PROJECT

  • The name of the final binary.
  • Defaults to 'sled'.

• PLATFORM

  • The platform being compiled for.
  • Defaults to 'unix'.
  • See src/os_unix.c and similar.

• DEBUG

  • Set to 1 to add debug information to all files and disable -O2.
  • Defaults to 0.

• CFLAGS

  • Defaults to -O2 -march=native or -march=native -Og -ggdb dependent on DEBUG.

• STATIC

  • Set to 1 to use static linking.
  • Set to 0 to use -ldl based linking.
  • Defaults to 0.

• DEFAULT_OUTMOD

  • The default -o parameter.
  • Defaults to "sdl2".

• DEFAULT_MODULEDIR

  • The default -m parameter.
  • Defaults to "./modules".

• MODULES

  • The modules being compiled.
  • MODULES_AVAILABLE contains all available GFX modules.
  • Default is this & DEFAULT_OUTMOD prefixed with out_.

Compile with simply make.

Output modules

• out_sdl2

  • SDL2-based virtual matrix for development.

• out_rpi_ws2812b

  • Uses rpi_ws281x to drive the strips.
  • Uses PCM, DMA channel 10 and SoC pin 21/RPI header pin 40 by default.

• out_udp

  • UDP output following the protocol of CalcProgrammer1/KeyboardVisualizer's LED strip output.
  • An ESP8266 Arduino sketch will be uploaded here soon. In the meantime, CalcProgrammer1's repository has a compatible sketch, I believe.

• out_pixelflut

  • Streaming onto a pixelflut server.
  • You need to specify the server on the command line, e.g. ./sled -o pixelflut:192.168.69.42:1234,320x240+640+480
  • Option string format is: pixelflut:[IP_ADDR]:[PORT],[SIZE_X]x[SIZE_Y]+[OFFSET_X]+[OFFSET_Y],[STRATEGY]
    • where STRATEGY is either linear or random

• out_rpi_hub75

  • A backend that drives HUB75-style matrices using https://github.com/hzeller/rpi-rgb-led-matrix
  • Does not use MATRIX_X/MATRIX_Y, as that's a bit more complicated.
  • Instead, use ./sled -o "rpi_hub75:--led-rows=32 --led-cols=64 --led-multiplexing=1 --led-chain=2 --led-pixel-mapper=U-mapper", for example. Arguments are explained at the library's project page.

• out_mpsse_spi

  • Uses libmpsse to speak SPI using USB FTDI chips utilizing the FTDI MPSSE engine.
  • Use this to speak with @smunaut's RGB matrix driver for iCEBreaker FPGA boards.
  • Also does not use MATRIX_X/MATRIX_Y.

Modules

By default, only modules with zero dependencies are built. Apart from the output modules, of course. They are the following:

Effects/Graphic Modules

• gfx_random_static: Randomized static color.

• gfx_random_rects: Random colored rectangle animation.

  • Note, your matrix axies have to be dividable by 4.

• gfx_twinkle: Twinkle, twinkle, little star? Made by @20kdc.

• gfx_text: Displays text using custom proportional font. Made by @20kdc.

  • "Hack me" greeting by default, obviously. 8x8 or bigger required.

• bgm_fish: FIfo Shell. A small FIFO-based queue manipulator. Made by @20kdc.

  • Shouldn't have background CPU usage as of the select abuse. Creates sled.fish FIFO in the sled tree.

• gfx_gol: A simple black and white Conway's Game of Life clone.

• gfx_golc: A Conway's Game of Life clone; with fading, color inheritance and loop detection, made by @orithena.

• gfx_rainbow: A simple rainbow animation.

• gfx_math_sinpi: A sinus curve of Pi.

• gfx_plasma: A plasma animation, ported fro