rgbmatrix

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 install go-rpi-rgb-led-matrix is:

go get github.com/Sunoo/go-rpi-rgb-led-matrix

Then you will get an expected error like this:

# github.com/Sunoo/go-rpi-rgb-led-matrix
/usr/bin/ld: cannot find -lrgbmatrix
collect2: error: ld returned 1 exit status

This happens because you need to compile the rgbmatrix C bindings:

cd $GOPATH/src/github.com/Sunoo/go-rpi-rgb-led-matrix/vendor/rpi-rgb-led-matrix/
git submodule update --init
make
cd $GOPATH/src/github.com/Sunoo/go-rpi-rgb-led-matrix/
go install -v ./...

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.

License

MIT, see LICENSE

Documentation

Index

• Constants
• Variables
• type Animation
• type Canvas
  • func NewCanvas(m Matrix) *Canvas
  • func (c *Canvas) At(x, y int) color.Color
  • func (c *Canvas) Bounds() image.Rectangle
  • func (c *Canvas) Clear() error
  • func (c *Canvas) Close() error
  • func (c *Canvas) ColorModel() color.Model
  • func (c *Canvas) Render() error
  • func (c *Canvas) RenderKeep() error
  • func (c *Canvas) Set(x, y int, color color.Color)
• type HardwareConfig
• type Matrix
  • func NewRGBLedMatrix(config *HardwareConfig) (c Matrix, err error)
• type RGBLedMatrix
  • func (c *RGBLedMatrix) Apply(leds []color.Color) error
  • func (c *RGBLedMatrix) At(position int) color.Color
  • func (c *RGBLedMatrix) Close() error
  • func (c *RGBLedMatrix) Geometry() (width, height int)
  • func (c *RGBLedMatrix) Initialize() error
  • func (c *RGBLedMatrix) Render() error
  • func (c *RGBLedMatrix) RenderActual(keepContents bool) error
  • func (c *RGBLedMatrix) RenderKeep() error
  • func (c *RGBLedMatrix) Set(position int, color color.Color)
  • func (c *RGBLedMatrix) SetBrightness(brightness int)
• type ScanMode
• type ToolKit
  • func NewToolKit(m Matrix) *ToolKit
  • func (tk *ToolKit) Close() error
  • func (tk *ToolKit) PlayAnimation(a Animation) error
  • func (tk *ToolKit) PlayGIF(r io.Reader) (chan bool, error)
  • func (tk *ToolKit) PlayImage(i image.Image, delay time.Duration) error
  • func (tk *ToolKit) PlayImageUntil(i image.Image, notify <-chan time.Time) error
  • func (tk *ToolKit) PlayImages(images []image.Image, delay []time.Duration, loop int) chan bool

Constants

const MatrixEmulatorENV = "MATRIX_EMULATOR"

Variables

var DefaultConfig = HardwareConfig{
	Rows:              32,
	Cols:              32,
	ChainLength:       1,
	Parallel:          1,
	PWMBits:           11,
	PWMLSBNanoseconds: 130,
	Brightness:        100,
	ScanMode:          Progressive,
}

DefaultConfig default WS281x configuration

Types

type Animation

type Animation interface {
	Next() (image.Image, <-chan time.Time, error)
}

type Canvas

type Canvas struct {
	// contains filtered or unexported fields
}

Canvas is a image.Image representation of a WS281x matrix, it implements image.Image interface and can be used with draw.Draw for example

func NewCanvas

func NewCanvas(m Matrix) *Canvas

NewCanvas returns a new Canvas using the given width and height and creates a new WS281x matrix using the given config

func (*Canvas) At

func (c *Canvas) At(x, y int) color.Color

At returns the color of the pixel at (x, y)

func (*Canvas) Bounds

func (c *Canvas) Bounds() image.Rectangle

Bounds return the topology of the Canvas

func (*Canvas) Clear

func (c *Canvas) Clear() error

Clear set all the leds on the matrix with color.Black

func (*Canvas) Close

func (c *Canvas) Close() error

Close clears the matrix and close the matrix

func (*Canvas) ColorModel

func (c *Canvas) ColorModel() color.Model

ColorModel returns the canvas' color model, always color.RGBAModel

func (*Canvas) Render

func (c *Canvas) Render() error

Render update the display with the data from the LED buffer

func (*Canvas) RenderKeep

func (c *Canvas) RenderKeep() error

Render update the display with the data from the LED buffer

func (*Canvas) Set

func (c *Canvas) Set(x, y int, color color.Color)

Set set LED at position x,y to the provided 24-bit color value

type HardwareConfig

type HardwareConfig struct {
	// Rows the number of rows supported by the display, so 32 or 16.
	Rows int
	// Cols the number of columns supported by the display, so 32 or 64 .
	Cols int
	// ChainLengthis the number of displays daisy-chained together
	// (output of one connected to input of next).
	ChainLength int
	// Parallel is the number of parallel chains connected to the Pi; in old Pis
	// with 26 GPIO pins, that is 1, in newer Pis with 40 interfaces pins, that
	// can also be 2 or 3. The effective number of pixels in vertical direction is
	// then thus rows * parallel.
	Parallel int
	// Set PWM bits used for output. Default is 11, but if you only deal with
	// limited comic-colors, 1 might be sufficient. Lower require less CPU and
	// increases refresh-rate.
	PWMBits int
	// Change the base time-unit for the on-time in the lowest significant bit in
	// nanoseconds.  Higher numbers provide better quality (more accurate color,
	// less ghosting), but have a negative impact on the frame rate.
	PWMLSBNanoseconds int // the DMA channel to use
	// Brightness is the initial brightness of the panel in percent. Valid range
	// is 1..100
	Brightness int
	// ScanMode progressive or interlaced
	ScanMode ScanMode // strip color layout
	// Disable the PWM hardware subsystem to create pulses. Typically, you don't
	// want to disable hardware pulsing, this is mostly for debugging and figuring
	// out if there is interference with the sound system.
	// This won't do anything if output enable is not connected to GPIO 18 in
	// non-standard wirings.
	DisableHardwarePulsing bool

	ShowRefreshRate bool
	InverseColors   bool

	// Name of GPIO mapping used
	HardwareMapping string
}

HardwareConfig rgb-led-matrix configuration

type Matrix

type Matrix interface {
	Geometry() (width, height int)
	At(position int) color.Color
	Set(position int, c color.Color)
	SetBrightness(brightness int)
	Apply([]color.Color) error
	Render() error
	RenderKeep() error
	Close() error
}

Matrix is an interface that represent any RGB matrix, very useful for testing

func NewRGBLedMatrix

func NewRGBLedMatrix(config *HardwareConfig) (c Matrix, err error)

NewRGBLedMatrix returns a new matrix using the given size and config

type RGBLedMatrix

type RGBLedMatrix struct {
	Config *HardwareConfig
	// contains filtered or unexported fields
}

RGBLedMatrix matrix representation for ws281x

func (*RGBLedMatrix) Apply

func (c *RGBLedMatrix) Apply(leds []color.Color) error

Apply set all the pixels to the values contained in leds

func (*RGBLedMatrix) At

func (c *RGBLedMatrix) At(position int) color.Color

At return an Color which allows access to the LED display data as if it were a sequence of 24-bit RGB values.

func (*RGBLedMatrix) Close

func (c *RGBLedMatrix) Close() error

Close finalizes the ws281x interface

func (*RGBLedMatrix) Geometry

func (c *RGBLedMatrix) Geometry() (width, height int)

Geometry returns the width and the height of the matrix

func (*RGBLedMatrix) Initialize

func (c *RGBLedMatrix) Initialize() error

Initialize initialize library, must be called once before other functions are called.

func (*RGBLedMatrix) Render

func (c *RGBLedMatrix) Render() error

Render update the display with the data from the LED buffer

func (*RGBLedMatrix) RenderActual

func (c *RGBLedMatrix) RenderActual(keepContents bool) error

Render update the display with the data from the LED buffer

func (*RGBLedMatrix) RenderKeep

func (c *RGBLedMatrix) RenderKeep() error

Render update the display with the data from the LED buffer

func (*RGBLedMatrix) Set

func (c *RGBLedMatrix) Set(position int, color color.Color)

Set set LED at position x,y to the provided 24-bit color value.

func (*RGBLedMatrix) SetBrightness

func (c *RGBLedMatrix) SetBrightness(brightness int)

Sets the Brightness

type ScanMode

type ScanMode int8

const (
	Progressive ScanMode = 0
	Interlaced  ScanMode = 1
)

type ToolKit

type ToolKit struct {
	// Canvas is the Canvas wrapping the Matrix, if you want to instanciate
	// a ToolKit with a custom Canvas you can use directly the struct,
	// without calling NewToolKit
	Canvas *Canvas

	// Transform function if present is applied just before draw the image to
	// the Matrix, this is a small example:
	//	tk.Transform = func(img image.Image) *image.NRGBA {
	//		return imaging.Fill(img, 64, 96, imaging.Center, imaging.Lanczos)
	//	}
	Transform func(img image.Image) *image.NRGBA
}

ToolKit is a convinient set of function to operate with a led of Matrix

func NewToolKit

func NewToolKit(m Matrix) *ToolKit

NewToolKit returns a new ToolKit wrapping the given Matrix

func (*ToolKit) Close

func (tk *ToolKit) Close() error

Close close the toolkit and the inner canvas

func (*ToolKit) PlayAnimation

func (tk *ToolKit) PlayAnimation(a Animation) error

PlayAnimation play the image during the delay returned by Next, until an err is returned, if io.EOF is returned, PlayAnimation finish without an error

func (*ToolKit) PlayGIF

func (tk *ToolKit) PlayGIF(r io.Reader) (chan bool, error)

PlayGIF reads and draw a gif file from r. It use the contained images and delays and loops over it, until a true is sent to the returned chan

func (*ToolKit) PlayImage

func (tk *ToolKit) PlayImage(i image.Image, delay time.Duration) error

PlayImage draws the given image during the given delay

func (*ToolKit) PlayImageUntil

func (tk *ToolKit) PlayImageUntil(i image.Image, notify <-chan time.Time) error

PlayImageUntil draws the given image until is notified to stop

func (*ToolKit) PlayImages

func (tk *ToolKit) PlayImages(images []image.Image, delay []time.Duration, loop int) chan bool

PlayImages draws a sequence of images during the given delays, the len of images should be equal to the len of delay. If loop is true the function loops over images until a true is sent to the returned chan