ws2811

README

rpi-ws281x-go

Summary

Go (golang) binding for the rpi_ws281x userspace Raspberry Pi library for controlling WS281X LEDs by Jeremy Garff (https://github.com/jgarff/rpi_ws281x). The goal for this library is to offer all the features of the C library and to make is as efficiently as possible.

Installing

This module is a wrapper around the rpi_ws281x C library and you need to have this C library installed on your machine before installing this module.

Compiling directly on the Raspberry Pi

This is not the recommended way, but if you want to compile everything on the Raspbery Pi itself, start by building the pi_ws281x C library according to the documentation, copy the *.a files to /usr/local/lib and the *.h files to /usr/local/include.

Then you can compile the go code as usual.

Cross compiling

The recommended way for building software for embedded systems is to use cross compilation. Cross compilation is very easy in go... unless you use cgo. And because this module is a wrapper around a C library, we have to use cgo and the cross compilation is not so easy.

The solution proposed here uses a docker container to cross-compile the go code and should work on GNU/Linux, macos and Windows.

First check that you have a recent version of docker desktop. Run the following command:

docker buildx  ls

You should see something like this :

NAME/NODE DRIVER/ENDPOINT STATUS  PLATFORMS
default * docker
  default default         running linux/amd64, linux/arm64, ..., linux/arm/v7, linux/arm/v6

If you see linux/arm/v6 and linux/arm/v7 you can cross-compile for arm 32 bits. If you see linux/arm64 you can compile code for arm 64 bits.

Now you need to build a docker image with the required toolchain and libraries:

docker buildx build --platform linux/arm/v7 --tag ws2811-builder --file docker/app-builder/Dockerfile .

You can replace linux/arm/v7 by linux/arm64 if you want to build for arm64.

You can now use this Docker image to build your app. For example, you can build the "swiss" example using this command:

> cd examples/swiss
> APP="swiss"
> docker run --rm -v "$PWD":/usr/src/$APP --platform linux/arm/v7 \
  -w /usr/src/$APP ws2811-builder:latest go build -o "$APP-armv7" -v

On GNU/Linux or macos, you can check the built binary with the file command:

> file swiss-armv7

swiss-armv7: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV),
  dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0,
  Go BuildID=..., BuildID[sha1]=..., not stripped```

As you can see, the resulting binary is an executable file for the ARM processor.

Note that the example will use the rpi-ws2811x-go module from the github repository. If you want to use the module from the Docker image, you can add the following line to the go.mod file of the example:

replace github.com/rpi-ws281x/rpi-ws281x-go => /go/src/rpi-ws281x-go/

Using the module

In order to use this module, you have to understand the options of the underlying C library. Read documentation of the C library for more information.

The mapping of these options from go to C should be obvious. The documentation of this module and particularly the section about the channel options provide further information.

Testing

This library is tested using the following hardware setup:

In this circuit, the 4050 is a driver that converts the 3.3V of the Raspberry Pi to the 5V needed by the ws2811 chip. The LED matrix is connected by an external power supply that provides the required current.

Here is the result of the "Swiss" example:

Special Thanks

• Thank you to Jeremy Garff for writing and maintaining the C library.
• Thank you to all contributors (alphabetically):
  • Alexandr Pavlyuk
  • Allen Flickinger
  • Ben Watkins
  • Chris C.
  • Elie Grenon
  • Herman
  • Ivaylo Stoyanov
  • Stephen Onnen

Projects using this module

• Rainbow and Random demo

Documentation

Index

• Constants
• Variables
• func StatusDesc(code int) string
• type ChannelOption
• type HwDesc
  • func HwDetect() HwDesc
• type Option
• type WS2811
  • func MakeWS2811(opt *Option) (*WS2811, error)
  • func (ws2811 *WS2811) Fini()
  • func (ws2811 *WS2811) Init() error
  • func (ws2811 *WS2811) Leds(channel int) []uint32
  • func (ws2811 *WS2811) Render() error
  • func (ws2811 *WS2811) SetBrightness(channel int, brightness int)
  • func (ws2811 *WS2811) SetLedsSync(channel int, leds []uint32) error
  • func (ws2811 *WS2811) Wait() error

Constants

const (
	// DefaultDmaNum is the default DMA number.
	DefaultDmaNum = 10
	// RpiPwmChannels is the number of PWM leds in the Raspberry Pi
	RpiPwmChannels = 2
	// TargetFreq is the target frequency. It is usually 800kHz (800000), and an go as low as 400000
	TargetFreq = 800000
	// DefaultGpioPin is the default pin on the Raspberry Pi where the signal will be available. Note
	// that it is the BCM (Broadcom Pin Number) and the "Pin" 18 is actually the physical pin 12 of the
	// Raspberry Pi.
	DefaultGpioPin = 18
	// DefaultLedCount is the default number of LEDs on the stripe.
	DefaultLedCount = 16
	// DefaultBrightness is the default maximum brightness of the LEDs. The brightness value can be between 0 and 255.
	// If the brightness is too low, the LEDs remain dark. If the brightness is too high, the system needs too much
	// current.
	DefaultBrightness = 64 // Safe value between 0 and 255.
)

const (
	// HwVerTypeUnknown represents unknown hardware
	HwVerTypeUnknown = 0
	// HwVerTypePi1 represents the Raspberry Pi 1
	HwVerTypePi1 = 1
	// HwVerTypePi2 represents the Raspberry Pi 2
	HwVerTypePi2 = 2
)

const (
	// SK6812StripRGBW is the RGBW Mode
	SK6812StripRGBW = 0x18100800
	// SK6812StripRBGW is the StripRBGW Mode
	SK6812StripRBGW = 0x18100008
	// SK6812StripGRBW is the StripGRBW Mode
	SK6812StripGRBW = 0x18081000
	// SK6812StrioGBRW is the StrioGBRW Mode
	SK6812StrioGBRW = 0x18080010
	// SK6812StrioBRGW is the StrioBRGW Mode
	SK6812StrioBRGW = 0x18001008
	// SK6812StripBGRW is the StripBGRW Mode
	SK6812StripBGRW = 0x18000810
	// SK6812ShiftWMask is the Shift White Mask
	SK6812ShiftWMask = 0xf0000000
)

4 color R, G, B and W ordering

const (
	// WS2811StripRGB is the RGB Mode
	WS2811StripRGB = 0x100800
	// WS2811StripRBG is the RBG Mode
	WS2811StripRBG = 0x100008
	// WS2811StripGRB is the GRB Mode
	WS2811StripGRB = 0x081000
	// WS2811StripGBR is the GBR Mode
	WS2811StripGBR = 0x080010
	// WS2811StripBRG is the BRG Mode
	WS2811StripBRG = 0x001008
	// WS2811StripBGR is the BGR Mode
	WS2811StripBGR = 0x000810
)

3 color R, G and B ordering

const (
	// WS2812Strip is the WS2812 Mode
	WS2812Strip = WS2811StripGRB
	// SK6812Strip is the SK6812 Mode
	SK6812Strip = WS2811StripGRB
	// SK6812WStrip is the SK6812W Mode
	SK6812WStrip = SK6812StripGRBW
)

Predefined fixed LED types

Variables

var DefaultOptions = Option{
	Frequency: TargetFreq,
	DmaNum:    DefaultDmaNum,
	Channels: []ChannelOption{
		{
			GpioPin:    DefaultGpioPin,
			LedCount:   DefaultLedCount,
			Brightness: DefaultBrightness,
			StripeType: WS2812Strip,
			Invert:     false,
			Gamma:      gamma8,
		},
	},
}

DefaultOptions defines sensible default options for MakeWS2811 nolint: gochecknoglobals

var StateDesc = map[int]string{
	0:   "Success",
	-1:  "Generic failure",
	-2:  "Out of memory",
	-3:  "Hardware revision is not supported",
	-4:  "Memory lock failed",
	-5:  "mmap() failed",
	-6:  "Unable to map registers into userspace",
	-7:  "Unable to initialize GPIO",
	-8:  "Unable to initialize PWM",
	-9:  "Failed to create mailbox device",
	-10: "DMA error",
	-11: "Selected GPIO not possible",
	-12: "Unable to initialize PCM",
	-13: "Unable to initialize SPI",
	-14: "SPI transfer error",
}

StateDesc is a map from a return state to its string description. nolint: gochecknoglobals

Functions

func StatusDesc

func StatusDesc(code int) string

StatusDesc returns the description of a status code

Types

type ChannelOption

type ChannelOption struct {
	// GpioPin is the GPIO Pin with PWM alternate function, 0 if unused
	GpioPin int
	// Invert inverts output signal
	Invert bool
	// LedCount is the number of LEDs, 0 if channel is unused
	LedCount int
	// StripeType is the strip color layout -- one of WS2811StripXXX constants
	StripeType int
	// Brightness is the maximum brightness of the LEDs. Value between 0 and 255
	Brightness int
	// WShift is the white shift value
	WShift int
	// RShift is the red shift value
	RShift int
	// GShift is the green shift value
	GShift int
	// BShift is blue shift value
	BShift int
	// Gamma is the gamma correction table
	Gamma []byte
}

ChannelOption is the list of channel options

type HwDesc

type HwDesc struct {
	Type          uint32
	Version       uint32
	PeriphBase    uint32
	VideocoreBase uint32
	Desc          string
}

HwDesc is the Hardware Description

func HwDetect

func HwDetect() HwDesc

HwDetect gives information about the hardware

type Option

type Option struct {
	// RenderWaitTime is the time in µs before the next render can run
	RenderWaitTime int
	// Frequency is the required output frequency
	Frequency int
	// DmaNum is the number of a DMA _not_ already in use
	DmaNum int
	// Channels are channel options
	Channels []ChannelOption
}

Option is the list of device options

type WS2811

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

WS2811 represent the ws2811 device

func MakeWS2811

func MakeWS2811(opt *Option) (*WS2811, error)

MakeWS2811 create an instance of WS2811.

func (*WS2811) Fini

func (ws2811 *WS2811) Fini()

Fini shuts down the device and frees memory.

func (*WS2811) Init

func (ws2811 *WS2811) Init() error

Init initialize the device. It should be called only once before any other method.

func (*WS2811) Leds

func (ws2811 *WS2811) Leds(channel int) []uint32

Leds returns the LEDs array of a given channel

func (*WS2811) Render

func (ws2811 *WS2811) Render() error

Render sends a complete frame to the LED Matrix

func (*WS2811) SetBrightness

func (ws2811 *WS2811) SetBrightness(channel int, brightness int)

SetBrightness changes the brightness of a given channel. Value between 0 and 255

func (*WS2811) SetLedsSync

func (ws2811 *WS2811) SetLedsSync(channel int, leds []uint32) error

SetLedsSync wait for the frame to finish and replace all the LEDs

func (*WS2811) Wait

func (ws2811 *WS2811) Wait() error

Wait waits for render to finish. The time needed for render is given by: time = 1/frequency * 8 * 3 * LedCount + 0.05 (8 is the color depth and 3 is the number of colors (LEDs) per pixel). See https://cdn-shop.adafruit.com/datasheets/WS2811.pdf for more details.