shinyblink / sled

Satanic/Sexy/Stupid/Silly/Shiny LED matrix controller
https://shinyblink.github.io/sled/
ISC License
122 stars 25 forks source link
34c3 3ds 3ds-homebrew c card10 freebsd hacktoberfest hub75 led-controller led-matrix-displays linux raspberry-pi sdl2 ws2812b

sled: The satanic LED controller

GitHub Actions CI Join the chat at https://gitter.im/shinyblink/sled

Modular LED Matrix controller.

Manual

Read the Satanic Bible by Anton Szandor LaVey.

Getting started (SDL2 Tutorial for Development)

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:

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.

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:

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:

Compile with simply make.

Output modules

Modules

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

Effects/Graphic Modules

If you want to only build a specific set of modules, change the "MODULES" array in your sledconf file.

If you want to build a specific module later on, you can do the same but with just the module you wanna build. It'll get added to the same directory where the others are. Or, if you are particularly lazy, just add the module name to the make invocation.

FISh

The sled.fish FiFo supports the following commands:

Command Action
<modulename> [parameters] Run the module with optional arguments directly
/blank Blank the output
/error42 Exit the program
/next Jump to the next effect
/then <modulename/command> [parameters] Schedule the given module or command with optional parameters after the current one

Examples:

echo '/next' > sled.fish
echo '/then /blank' > sled.fish
echo '/then autoterminal execute htop' > sled.fish
echo '/then text "Hello World"' > sled.fish
echo 'text "Hello World"' > sled.fish

Running echo 'text Ipsum' > sled.fish has the same effext as echo -e "/then text Ipsum\n/next" > sled.fish.

License

Most non-trivial files contain an explicit statement regarding the license.

Anything with no statement follows the ISC, with the copyright holder being Adrian "vifino" Pistol, as per the COPYING file in this project.

Support

Support for sled is done on a if-i-can-find-the-time basis. Mostly, this project is for myself.

I'll try to help everyone, but I might take some time.

If you'd like to support my work or me in general, you can sponsor me via GitHub!

Most of the donations tracable to anything sled related will be spend buying different LED matrices and other hardware.

Plus, buying Mate, Rum and Limes to motivate me and others by making Tschunk. ;)