buttonshim

README

Button SHIM Go library

Provides a Go implementation for interfacing with Pimoroni's Button SHIM. The top-level library provides a lot of the same functionality as the reference Python library, including:

• Handle press/release events for the buttons
• Update the color of the RGB LED.

Overview

Installation

First, clone the project into your Go path:

go get github.com/tomnz/button-shim-go

The library depends on the periph.io framework for low level device communication. You can install this manually with go get, or (preferred) use dep:

go get -u github.com/golang/dep/cmd/dep
cd $GOPATH/src/github.com/tomnz/button-shim-go
dep ensure

Usage

First, initialize a periph.io I2C bus, and instantiate the device with it:

package main

import (
    "github.com/tomnz/button-shim-go"
    "periph.io/x/periph/conn/i2c/i2creg"
    "periph.io/x/periph/host"
)

func main() {
    // TODO: Handle errors
    _, _ := host.Init()
    bus, _ := i2creg.Open("1")
    shim, _ := buttonshim.New(bus)
}

The library implements button press and release handlers using channels. For example:

aPress := shim.ButtonPressChan(buttonshim.ButtonA)
bPress := shim.ButtonPressChan(buttonshim.ButtonB)
aRelease := shim.ButtonReleaseChan(buttonshim.ButtonA)
go func() {
    for {
        select {
        case <-aPress:
            fmt.Println("Button A pressed!")
        case <-bPress:
            fmt.Println("Button B pressed!")
        case holdDuration := <-aRelease:
            fmt.Printf("Button A held for %s!", holdDuration)
        }
    }
}()

The color and brightness of the pixel can also be changed:

shim.SetColor(255, 0, 0)
shim.SetBrightness(127)

Please refer to the godocs for full API reference.

Contributing

Contributions welcome! Please refer to the contributing guide.

Documentation

Index

• Variables
• type Button
  • func (b Button) String() string
• type Driver
  • func New(bus i2c.Bus, opts ...Option) (*Driver, error)
  • func NewWithConn(periphConn conn.Conn, opts ...Option) (*Driver, error)
  • func (d *Driver) ButtonPressChan(button Button) <-chan struct{}
  • func (d *Driver) ButtonReleaseChan(button Button) <-chan time.Duration
  • func (d *Driver) Halt() error
  • func (d *Driver) SetBrightness(brightness byte)
  • func (d *Driver) SetColor(r, g, b byte)
• type Option
  • func WithButtonPollInterval(interval time.Duration) Option
  • func WithGamma(gamma []byte) Option

Variables

var (
	// Buttons lists all of the available buttons in order. If you don't want to hardcode the number
	// of buttons in your application, you can use len(buttonshim.Buttons) instead.
	Buttons = []Button{
		ButtonA,
		ButtonB,
		ButtonC,
		ButtonD,
		ButtonE,
	}
)

Types

type Button

type Button byte

Button represents a button.

const (
	// ButtonA represents button A.
	ButtonA Button = iota
	// ButtonB represents button B.
	ButtonB
	// ButtonC represents button C.
	ButtonC
	// ButtonD represents button D.
	ButtonD
	// ButtonE represents button E.
	ButtonE
)

func (Button) String

func (b Button) String() string

String returns the letter corresponding to the button.

type Driver

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

Driver is the primary struct for interacting with the Button SHIM device.

func New

func New(bus i2c.Bus, opts ...Option) (*Driver, error)

New returns a new Button SHIM hardware driver. The driver encapsulates a set of buttons and a single RGB LED, handling interaction with the actual device. Connects to the device on the given I2C bus at its standard address.

func NewWithConn

func NewWithConn(periphConn conn.Conn, opts ...Option) (*Driver, error)

NewWithConn returns a new Button SHIM hardware driver, using the given periph.io conn.Conn object. Typically New should be used instead, but this may be useful for testing using mocks, or a custom I2C connection with a different address than the default.

func (*Driver) ButtonPressChan

func (d *Driver) ButtonPressChan(button Button) <-chan struct{}

ButtonPressChan returns a new receive channel that can be used to handle press events for a specific button. The actual message carries no payload - use it as a signalling mechanism only. For example:

pressA := shim.ButtonPressChan(buttonshim.ButtonA)
pressB := shim.ButtonPressChan(buttonshim.ButtonB)
go func() {
	for {
		select {
		case <-pressA:
			fmt.Println("Button A pressed!")
		case <-pressB:
			fmt.Println("Button B pressed!")
		}
	}
}()

func (*Driver) ButtonReleaseChan

func (d *Driver) ButtonReleaseChan(button Button) <-chan time.Duration

ButtonReleaseChan returns a new receive channel that can be used to handle release events for a specific button. The actual message indicates the final duration that the button was observed as being pressed for. The accuracy of this value is limited by the poll rate.

func (*Driver) Halt

func (d *Driver) Halt() error

Halt implements devices.Device.

func (*Driver) SetBrightness

func (d *Driver) SetBrightness(brightness byte)

SetBrightness sets the brightness of the pixel.

func (*Driver) SetColor

func (d *Driver) SetColor(r, g, b byte)

SetColor sets the RGB pixel to the given color.

type Option

type Option func(*options)

Option allows specifying behavior for the driver.

func WithButtonPollInterval

func WithButtonPollInterval(interval time.Duration) Option

WithButtonPollInterval allows modifying the button poll interval. A longer interval will use fewer system resources, but risks not registering a fast button press. Default 50ms.

func WithGamma

func WithGamma(gamma []byte) Option

WithGamma allows overriding the gamma curve for the LED. Must include 256 level mappings.