ws281x

README

go-rpi-ws281x (for easy cross-compilation)

Go bindings for rpi_ws281x, a userspace Raspberry Pi PWM library for WS281X LEDs. Supports any Raspberry and WS2812, SK6812RGB and SK6812RGBW LEDs strips, this includes Unicorn pHAT and NeoPixels.

This fork adds compatibility to the latest version of rpi_ws281x (by linking libm) and adjusts the install instructions to assume that cross-compilation is the default (as opposed to directly compiling on a Raspberry Pi).

Installation

The recommended way to install go-rpi-ws281x (on Debian) is by cross-compiling the original rpi_ws281x library (using scons and the appropriate gcc cross-compiler) and copying the header and library files into the correct multiarch locations:

apt install scons gcc-aarch64-linux-gnu
git clone https://github.com/jgarff/rpi_ws281x
cd rpi_ws281x

scons V=yes TOOLCHAIN=aarch64-linux-gnu

cp ws2811.h /usr/aarch64-linux-gnu/include/ws2811.h
cp rpihw.h /usr/aarch64-linux-gnu/include/rpihw.h
cp pwm.h /usr/aarch64-linux-gnu/include/pwm.h
cp libws2811.a /usr/aarch64-linux-gnu/lib/libws2811.a

Examples

// create a new canvas with the given width and height, and the config, in this
// case the configuration is for a Unicorn pHAT (8x4 pixels matrix) with the
// default configuration
c, _ := ws281x.NewCanvas(8, 4, &ws281x.DefaultConfig)


// initialize the canvas and the matrix
c.Initialize()

// since ws281x implements image.Image any function like draw.Draw from the std
// library may be used with it.
// 
// now we copy a white image into the ws281x.Canvas, this turn on all the leds
// to white
draw.Draw(c, c.Bounds(), image.NewUniform(color.White), image.ZP, draw.Over)

// render and sleep to see the leds on
c.Render()
time.Sleep(time.Second * 5)

// don't forget close the canvas, if not you leds may remain on
c.Close()

License

MIT, see LICENSE

Documentation

Index

• Variables
• type Canvas
  • func NewCanvas(w, h int, config *HardwareConfig) (*Canvas, error)
  • 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) Initialize() error
  • func (c *Canvas) Render() error
  • func (c *Canvas) Set(x, y int, color color.Color)
• type HardwareConfig
• type Matrix
  • func NewWS281x(size int, config *HardwareConfig) (Matrix, error)
• type StripType
• type WS281x
  • func (c *WS281x) At(position int) color.Color
  • func (c *WS281x) Close() error
  • func (c *WS281x) Initialize() error
  • func (c *WS281x) Render() error
  • func (c *WS281x) Set(position int, color color.Color)

Variables

var DefaultConfig = HardwareConfig{
	Pin:        18,
	Frequency:  800000,
	DMA:        10,
	Brightness: 30,
	StripType:  StripGRB,
}

DefaultConfig default WS281x configuration

Types

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(w, h int, config *HardwareConfig) (*Canvas, error)

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) Initialize

func (c *Canvas) Initialize() error

Initialize initialize the matrix and the canvas

func (*Canvas) Render

func (c *Canvas) Render() 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 {
	Pin        int       // GPIO Pin with PWM alternate function, 0 if unused
	Frequency  int       // the frequency of the display signal in hertz, can go as low as 400000
	DMA        int       // the DMA channel to use
	Invert     bool      // specifying if the signal line should be inverted
	Channel    int       // PWM channel to us
	Brightness int       // brightness value between 0 and 255
	StripType  StripType // strip color layout
}

HardwareConfig WS281x configuration

type Matrix

type Matrix interface {
	Initialize() error
	At(position int) color.Color
	Set(position int, c color.Color)
	Render() error
	Close() error
}

func NewWS281x

func NewWS281x(size int, config *HardwareConfig) (Matrix, error)

NewWS281x returns a new matrix using the given size and config

type StripType

type StripType int

StripType layout

const (
	// 4 color R, G, B and W ordering
	StripRGBW StripType = 0x18100800
	StripRBGW StripType = 0x18100008
	StripGRBW StripType = 0x18081000
	StripGBRW StripType = 0x18080010
	StripBRGW StripType = 0x18001008
	StripBGRW StripType = 0x18000810

	// 3 color R, G and B ordering
	StripRGB StripType = 0x00100800
	StripRBG StripType = 0x00100008
	StripGRB StripType = 0x00081000
	StripGBR StripType = 0x00080010
	StripBRG StripType = 0x00001008
	StripBGR StripType = 0x00000810
)

type WS281x

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

WS281x matrix representation for ws281x

func (*WS281x) At

func (c *WS281x) 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 (*WS281x) Close

func (c *WS281x) Close() error

Close finalizes the ws281x interface

func (*WS281x) Initialize

func (c *WS281x) Initialize() error

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

func (*WS281x) Render

func (c *WS281x) Render() error

Render update the display with the data from the LED buffer

func (*WS281x) Set

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

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