andreteixeira1998 / blinkt

A Golang library for the Pimoroni Blinkt!

blinkt

This library is a fork of Alex Ellis' blinkt_go that I was intending to port to my gpiod library, but ended up going off on a bit of a tangent and also using it as a testbed for comparing various GPIO implementations, and incorporating a merge/port of Alex's blinkt_go_examples.

Quick Start

import "github.com/warthog618/blinkt"

// create a blinkt to control the display
bl := blinkt.New()

// set the display brightness
bl.SetBrightness(23)

// write to pixels
bl.SetPixel(0, r, g, b)
...
bl.SetPixel(7, r, g, b)

// show the pixels on the display
bl.Show()

// clear the display
bl.Clear()
bl.Show()

// finish with the display
bl.Close()

Usage

The following is a short summary of the Blinkt API.

New

Create a new Blinkt object using *New":

bl := blinkt.New()

Close

If you no longer need to use the display, or your application is exiting, you should close the display:

bl.Close()

SetClearOnExit

By default the display is cleared when closed. This can be changed with the SetClearOnExit method:

bl.SetClearOnExit(false)

Whole Display

The following methods act on all pixels in the display.

Note that nothing is actually written to the physical display until Show is called.

SetAll

Set the colour of all pixels at once using SetAll:

bl.SetAll(r, g, b)

Setting the colour does not alter the brightness, which is independent.

SetBrightness

Set the brightness of all pixels at once using SetBrightness:

bl.SetBrightness(42)

The brightness value is a percent, so 0-100. By default the display brightness is set to 50.

Clear

Turn off all pixels using the Clear method:

bl.Clear()

Show

Update the display with the current pixel states using Show:

bl.Show()

The other methoss only update the pixels in memory - the Show command commits that state to the display.

The Show method performs the update in a separate goroutine using a snapshot of the pixel state, so the main goroutine can immediately begin updating the pixel state while the snapshot is being written to the display.

The Show method will block if the background goroutine is still updating the display with the previous Show.

Individual Pixels

The following methods apply to an individual pixel.

The pixel parameter which identifies the pixel, and is denoted by p in these snippets, is in the range 0-7.

ClearPixel

Turn off the pixel using the ClearPixel method:

bl.ClearPixel(p)

SetPixel

Set the colour of the pixel using SetPixel:

bl.SetPixel(p, r, g, b)

Setting the colour does not alter the brightness, which is independent.

SetPixelBrightness

Set the brightness of the pixel using SetPixelBrightness:

bl.SetPixelBrightness(68)

Goroutine Safety

The Blinkt is not safe to call from multiple goroutines, with the exception of the Close method, which is made goroutine safe so it can be called from signal handlers, e.g. when the application is closing down.

Backends

The library provides a selection of backends to drive the GPIO, with the selection being performed by a build tag. e.g.

go build -tags blinkt_wiringpi

will build an application using the WiringPi backend.

The default backend is my gpiod library, which makes use of the official Linux GPIO interface.

Backend	Build tag	Interface
gpiod	none (default)	Linux GPIO character device (/dev/gpiochip0) uAPI
gpio	blinkt_gpio	Raspberry Pi /dev/gpiomem direct access to the BCM hardware
wiringpi	blinkt_wiringpi	WiringPi cgo wrapper
sysfs	blinkt_sysfs	deprecated GPIO SYSFS interface

Examples

The examples directory contains a collection of examples that demonstrate the library and display.

These were originally ported from Alex's blinkt_go_examples which are themselves largely ports of some of the Pimoroni examples.

I've ported a few more of those, such as the binary clocks and rainbow.

Benchmarks

These are the results from a Raspberry Pi Zero W running Linux v5.10 and built with go1.15.6:

$ go test -test.bench=.*
goos: linux
goarch: arm
pkg: github.com/warthog618/blinkt
BenchmarkShow 	     106	  10547923 ns/op
PASS
ok  	github.com/warthog618/blinkt	1.683s

A summary of the results for each of the backends:

Backend	ns/op	Shows/sec
gpiod	10547923	94
gpio	102205	9784
wiringpi	3435945	291
sysfs	66638981	15

For comparison the Python/WiringPi implementation can perform around 9 shows/sec on the same platform.

My recommendation is to use the gpiod backend unless you have a serious need for speed or very low CPU utilization (and aren't concerned about conflicting with other BCM drivers), in which case the gpio library is a clear winner.

I could only recommend the Python interface for very low bandwidth applications.