rgbmatrix

README

rgbmatrix-rpi

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 rgbmatrix-rpi is:

go get github.com/fcjr/rgbmatrix-rpi

Then you will get an expected error like this:

# github.com/fcjr/rgbmatrix-rpi
/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/fcjr/rgbmatrix-rpi/lib/rpi-rgb-led-matrix/
git submodule update --init
make
cd $GOPATH/src/github.com/fcjr/rgbmatrix-rpi/
go install -v ./...

Examples

Setting all the pixels to white:

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

// 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.Point{}, 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, &rgbmatrix.DefaultRuntimeOptions)

// 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

• Variables
• type HardwareConfig
• type RGBLedMatrix
  • func NewRGBLedMatrix(config *HardwareConfig, rtOptions *RuntimeOptions, logger *zap.Logger) (c *RGBLedMatrix, err error)
  • func (c *RGBLedMatrix) At(x int, y int) color.Color
  • func (c *RGBLedMatrix) Close() error
  • func (c *RGBLedMatrix) Geometry() (int, int)
  • func (c *RGBLedMatrix) Play(ctx context.Context, startInterval time.Duration, ...) error
  • func (c *RGBLedMatrix) PreLoad(scene *matrix.MatrixScene)
  • func (c *RGBLedMatrix) Render() error
  • func (c *RGBLedMatrix) ReversePreLoad()
  • func (c *RGBLedMatrix) Set(x int, y int, color color.Color)
  • func (c *RGBLedMatrix) SetBrightness(brightness int)
• type RuntimeOptions
• type ScanMode

Variables

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

DefaultConfig default WS281x configuration

var DefaultRuntimeOptions = RuntimeOptions{
	GPIOSlowdown:   0,
	Daemon:         0,
	DropPrivileges: 1,
	DoGPIOInit:     true,
}

DefaultRuntimeOptions default WS281x runtime options

Types

type HardwareConfig

type HardwareConfig struct {
	// Rows the number of rows supported by the display, so 32 or 16.
	Rows int `json:"rows"`
	// Cols the number of columns supported by the display, so 32 or 64 .
	Cols int `json:"cols"`
	// ChainLengthis the number of displays daisy-chained together
	// (output of one connected to input of next).
	ChainLength int `json:"chainLength"`
	// 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 `json:"parallel"`
	// 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 `json:"pwmBits"`

	// The lower bits can be time-dithered for higher refresh rate.
	PWMDitherBits int `json:"pwmDitherBits"`

	// 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 `json:"pwmlsbNanoseconds"` // the DMA channel to use
	// Brightness is the initial brightness of the panel in percent. Valid range
	// is 1..100
	Brightness int `json:"brightness"`
	// ScanMode progressive or interlaced
	ScanMode ScanMode `json:"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 `json:"disableHardwarePulsing"`

	ShowRefreshRate bool   `json:"showRefreshRate"`
	InverseColors   bool   `json:"inverseColors"`
	LedRGBSequence  string `json:"ledRgbSequence"`

	// Name of GPIO mapping used
	HardwareMapping string `json:"hardwareMapping"`

	// Limit refresh rate of LED panel. This will help on a loaded system
	// to keep a constant refresh rate. <= 0 for no limit.
	LimitRefreshRateHz int `json:"limitRefreshRateHz"`

	// Type of multiplexing. 0 = direct, 1 = stripe, 2 = checker,...
	Multiplexing int `json:"multiplexing"`

	// A string describing a sequence of pixel mappers that should be applied
	// to this matrix. A semicolon-separated list of pixel-mappers with optional
	// parameter. See https://github.com/hzeller/rpi-rgb-led-matrix#panel-arrangement
	PixelMapperConfig string `json:"pixelMapperConfig"`

	// PanelType. Defaults to "". See https://github.com/hzeller/rpi-rgb-led-matrix#types-of-displays
	PanelType string `json:"panelType"`

	// RowAddr Type Adressing of rows; in particular panels with only AB address lines might indicate that this is needed.
	// See https://github.com/hzeller/rpi-rgb-led-matrix#types-of-displays for more info
	RowAddrType int `json:"rowAddrType"`
}

HardwareConfig rgb-led-matrix configuration

type RGBLedMatrix

type RGBLedMatrix struct {
	Config         *HardwareConfig
	RuntimeOptions *RuntimeOptions

	sync.Mutex
	// contains filtered or unexported fields
}

RGBLedMatrix matrix representation for ws281x

func NewRGBLedMatrix

func NewRGBLedMatrix(config *HardwareConfig, rtOptions *RuntimeOptions, logger *zap.Logger) (c *RGBLedMatrix, err error)

NewRGBLedMatrix returns a new matrix using the given size and config

func (*RGBLedMatrix) At

func (c *RGBLedMatrix) At(x int, y 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() (int, int)

Geometry returns the width and the height of the matrix

func (*RGBLedMatrix) Play

func (c *RGBLedMatrix) Play(ctx context.Context, startInterval time.Duration, interval <-chan time.Duration) error

func (*RGBLedMatrix) PreLoad

func (c *RGBLedMatrix) PreLoad(scene *matrix.MatrixScene)

func (*RGBLedMatrix) Render

func (c *RGBLedMatrix) Render() error

Render update the display with the data from the LED buffer

func (*RGBLedMatrix) ReversePreLoad

func (c *RGBLedMatrix) ReversePreLoad()

func (*RGBLedMatrix) Set

func (c *RGBLedMatrix) Set(x int, y 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)

type RuntimeOptions

type RuntimeOptions struct {
	// 0 = no slowdown. (Available 0...4)
	GPIOSlowdown int `json:"gpioSlowdown"`

	// Thre are three possible values here
	//   -1 : don't leave choise of becoming daemon to the command line parsing.
	//        If set to -1, the --led-daemon option is not offered.
	//    0 : do not becoma a daemon, run in forgreound (default value)
	//    1 : become a daemon, run in background.
	//
	// If daemon is disabled (= -1), the user has to call
	// RGBMatrix::StartRefresh() manually once the matrix is created, to leave
	// the decision to become a daemon
	// after the call (which requires that no threads have been started yet).
	// In the other cases (off or on), the choice is already made, so the thread
	// is conveniently already started for you.
	// -1 disabled. 0=off, 1=on.
	Daemon int `json:"daemon"`

	// Drop privileges from 'root' to 'daemon' once the hardware is initialized.
	// This is usually a good idea unless you need to stay on elevated privs.
	DropPrivileges int `json:"dropPrivileges"`

	// By default, the gpio is initialized for you, but if you run on a platform
	// not the Raspberry Pi, this will fail. If you don't need to access GPIO
	// e.g. you want to just create a stream output (see content-streamer.h),
	// set this to false.
	DoGPIOInit bool `json:"doGPIOInit"`
}

type ScanMode

type ScanMode int8

const (
	Progressive ScanMode = 0
	Interlaced  ScanMode = 1
)