# README

go-rpi-rgb-led-matrix

Go binding for rpi-rgb-led-matrix an excellent C++ library to control RGB LED displays with Raspberry Pi GPIO.

This library includes the basic bindings to control de LED Matrix directly and also a convenient ToolKit with more high level functions. Also some examples are included to test the library and the configuration.

The Canvas struct implements the image.Image interface from the Go standard library. This makes the interaction with the matrix simple as work with a normal image in Go, allowing the usage of any Go library build around the image.Image interface.

To learn about the configuration and the wiring go to the original library, is highly detailed and well explained.

Installation

The recommended way to add go-rpi-rgb-led-matrix package into your project is:

go get -v github.com/tfk1410/go-rpi-rgb-led-matrix

Then you will get an expected error like this:

# github.com/tfk1410/go-rpi-rgb-led-matrix
../../go/pkg/mod/github.com/tfk1410/[email protected]/matrix.go:6:10: fatal error: led-matrix-c.h: No such file or directory
    6 | #include <led-matrix-c.h>
      |          ^~~~~~~~~~~~~~~~
compilation terminated.

This happens because you need to compile the rgbmatrix C bindings. Using the path provided to the go mod package:

cd $GOPATH/go/pkg/mod/github.com/tfk1410/[email protected]/
chmod 700 .
mkdir vendor
cd vendor
git clone https://github.com/hzeller/rpi-rgb-led-matrix.git
cd rpi-rgb-led-matrix
make -j

This will compile the latest version of the library. The latest version tested with the binding is always the one as the submodule in this repo. Try with that commit if you encounter any issues.

After this is done go back to your project and execute the go get command again. This should now work:

$ go get -v github.com/tfk1410/go-rpi-rgb-led-matrix
go: finding github.com/tfk1410/go-rpi-rgb-led-matrix latest
github.com/tfk1410/go-rpi-rgb-led-matrix

Led-slowdown-gpio

In my tests I often require to change the value of the led-slowdown-gpio option from the default 1. It is not possible right now to change this option through the binding. The way to go about it is to go into the go mod package directory and into the rpi-rgb-led-matrix library. After that edit the lib/Makefile uncomment the line DEFINES+=-DRGB_SLOWDOWN_GPIO and change it to the appropriate value. Compile the whole library and rebuild your final project with all dependant packages and the setting should be applied. Example:

cd $GOPATH/go/pkg/mod/github.com/tfk1410/[email protected]/vendor/rpi-rgb-led-matrix
sed -i 's/.*RGB_SLOWDOWN_GPIO.*/DEFINE+=-DRGB_SLOWDOWN_GPIO=2/' lib/Makefile
make -j
# go back o your project
go build -a

Examples

Setting all the pixels to white:

// create a new Matrix instance with the DefaultConfig
m, _ := rgbmatrix.NewRGBLedMatrix(&rgbmatrix.DefaultConfig)

// create the Canvas, implements the image.Image interface
c := rgbmatrix.NewCanvas(m)
defer c.Close() // don't forgot close the Matrix, if not your leds will remain on
 
// using the standard draw.Draw function we copy a white image onto the Canvas
draw.Draw(c, c.Bounds(), &image.Uniform{color.White}, image.ZP, draw.Src)

// don't forget call Render to display the new led status
c.Render()

Playing a GIF into your matrix during 30 seconds:

// create a new Matrix instance with the DefaultConfig
m, _ := rgbmatrix.NewRGBLedMatrix(&rgbmatrix.DefaultConfig)

// create a ToolKit instance
tk := rgbmatrix.NewToolKit(m)
defer tk.Close() // don't forgot close the Matrix, if not your leds will remain on

// open the gif file for reading
file, _ := os.Open("mario.gif")

// play of the gif using the io.Reader
close, _ := tk.PlayGIF(f)
fatal(err)

// we wait 30 seconds and then we stop the playing gif sending a True to the returned chan
time.Sleep(time.Second * 30)
close <- true

The image of the header was recorded using this few lines, the running Mario gif, and three 32x64 pannels.

Check the folder examples folder for more examples

Matrix Emulation

As part of the library an small Matrix emulator is provided. The emulator renderize a virtual RGB matrix on a window in your desktop, without needing a real RGB matrix connected to your computer.

To execute the emulator set the MATRIX_EMULATOR environment variable to 1, then when NewRGBLedMatrix is used, a emulator.Emulator is returned instead of a interface the real board.