README
¶
Scroll pHAT HD Go library
Provides a Go implementation for interfacing with Pimoroni's Scroll pHAT HD. The top-level library provides a lot of the same functionality as the reference Python library, including:
- An internal display buffer that automatically expands as needed.
- Scrolling.
- Flipping.
- Tiling.
Coming soon:
- Text rendering.
- Graph rendering.
Overview
There are two primary ways that the library allows you to interact with the device:
Display wraps the Driver (or any other struct providing appropriate functionality), and extends it with the higher level capabilities described above, such as an auto-expanding internal buffer, scrolling, flipping, etc. In most cases, the Display offers a safer and more fully-featured way to interact with the device.
Driver abstracts the low-level I2C hardware device, and handles all communication. This does include some basic drawing functionality such as SetPixel, SetBrightness, and support for rotation. It's possible to use the Driver directly in your projects - this can be particularly useful in performance-critical situations where you want to incur minimum overhead in memory usage and copying.
Projects
Some example projects that take advantage of this library:
Installation
First, clone the project into your GOPATH:
go get github.com/tomnz/scroll-phat-hd-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/scroll-phat-hd-go
dep ensure
Usage
First, initialize a periph.io I2C bus, and instantiate the display with it:
package main
import (
"github.com/tomnz/scroll-phat-hd-go"
"periph.io/x/periph/conn/i2c/i2creg"
"periph.io/x/periph/host"
)
func main() {
// TODO: Handle errors
_, _ := host.Init()
bus, _ := i2creg.Open("1")
display, _ := scrollphathd.New(bus)
}
Now, you can use display to interact with the hardware. For example:
display.SetBrightness(127)
display.Fill(0, 0, 5, 5, 255)
display.Show()
Please refer to the godocs for full API reference.
Contributing
Contributions welcome! Please refer to the contributing guide.
Documentation
¶
Overview ¶
Package scrollphathd provides a helper library for interacting with a Pimoroni Scroll pHAT HD device:
https://shop.pimoroni.com/products/scroll-phat-hd
The library depends on the periph.io framework for low level device communication. There are two primary ways that the library allows you to interact with the device:
Display wraps the Driver (or any other struct providing appropriate functionality), and extends it with higher level capabilities, such as an auto-expanding internal buffer, scrolling, flipping, etc. In most cases, the Display offers a safer and more fully-featured way to interact with the device.
Driver abstracts the low level I2C hardware device, and handles all communication. This does include some basic drawing functionality such as SetPixel, SetBrightness, and supports rotation. It's possible to use the Driver directly in your projects. This can be particularly useful in performance-critical situations where you want to incur minimum overhead.
Index ¶
- type Device
- type Display
- func (d *Display) Clear()
- func (d *Display) ClearRect(x, y, width, height int)
- func (d *Display) Fill(x, y, width, height int, val byte)
- func (d *Display) Scroll(deltaX, deltaY int)
- func (d *Display) ScrollTo(scrollX, scrollY int)
- func (d *Display) SetBrightness(brightness byte)
- func (d *Display) SetFlip(flipX, flipY bool)
- func (d *Display) SetPixel(x, y int, val byte)
- func (d *Display) Show()
- type DisplayOption
- type Driver
- func (s *Driver) Clear() error
- func (s *Driver) Halt() error
- func (s *Driver) Height() int
- func (s *Driver) SetBrightness(brightness byte)
- func (s *Driver) SetBuffer(buffer [][]byte)
- func (s *Driver) SetPixel(x, y int, val byte) error
- func (s *Driver) SetPixels(pixels [][]byte) error
- func (s *Driver) Show() error
- func (s *Driver) Width() int
- type DriverOption
- type Rotation
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Device ¶
type Device interface {
SetBuffer(buffer [][]byte)
SetBrightness(brightness byte)
Show() error
Width() int
Height() int
}
Device is an abstraction that defines the capabilities that the display requires from its actual device (hardware or otherwise).
type Display ¶
type Display struct {
// contains filtered or unexported fields
}
Display is the primary struct for interacting with the Scroll pHAT HD device.
func New ¶
func New(bus i2c.Bus, opts ...DisplayOption) (*Display, error)
New instantiates a new Scroll pHAT HD display, the supplied options. This method requires an I2C bus to be supplied, which will be used to connect to the actual hardware device. For example:
import (
"github.com/tomnz/scroll-phat-hd-go"
"periph.io/x/periph/conn/i2c/i2creg"
"periph.io/x/periph/host"
)
_, _ := host.Init()
bus, _ := i2creg.Open("1")
display, _ := scrollphathd.New(bus)
func NewWithDevice ¶
func NewWithDevice(device Device, opts ...DisplayOption) *Display
NewWithDevice instantiates a new Scroll pHAT HD display, using the supplied device and options. For using the standard I2C hardware device, you likely want to just use New instead. This constructor is useful for passing a non-standard device implementation, such as a mock or terminal emulator. You can also override some of the options for the standard driver by declaring it first, then passing it to this constructor.
func (*Display) ClearRect ¶
ClearRect clears the given rectangle. Results must be explicitly pushed to the device with Show.
func (*Display) Fill ¶
Fill fills the given rectable with the given value. Results must be explicitly pushed to the device with Show.
func (*Display) ScrollTo ¶
ScrollTo configures the top left coordinate to use from the buffer for display.
func (*Display) SetBrightness ¶
SetBrightness configures the display's brightness. 0 is off, 255 is maximum brightness.
type DisplayOption ¶
type DisplayOption func(*displayOptions)
DisplayOption allows specifying behavior for the display.
func WithTiling ¶
func WithTiling(tile bool) DisplayOption
WithTiling specifies whether the buffer should tile when scrolling (default true).
type Driver ¶
type Driver struct {
// contains filtered or unexported fields
}
Driver handles low level communication with a Scroll pHAT HD hardware device. It can be used directly if you do not have need for some of the higher-level features of the Display object.
func NewDriver ¶
func NewDriver(bus i2c.Bus, opts ...DriverOption) (*Driver, error)
NewDriver returns a new Scroll pHAT HD hardware driver. This implements the Device interface, and can be used by Display. Connects to the device on the given I2C bus at its standard address.
func NewDriverWithConn ¶
func NewDriverWithConn(periphConn conn.Conn, opts ...DriverOption) (*Driver, error)
NewDriverWithConn returns a new Scroll pHAT HD hardware driver, using the given periph.io conn.Conn object. Typically NewDriver 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) SetBrightness ¶
SetBrightness sets the brightness of the device. This is applied to all pixels on Show. 0 is off, 255 is maximum brightness.
func (*Driver) SetBuffer ¶
SetBuffer allows setting all of the pixels at once by swapping out the internal buffer. This does NOT copy any of the data. This is exposed for performance reasons, but caution should be exercised! If the buffer is later updated externally, the contents of the internal buffer will also change! The dimensions of the incoming buffer are also not checked. When the final values are written to the device via Show, the internal buffer is copied, so this may increase safety some. Note that the array should be indexed in row, col order.
func (*Driver) SetPixels ¶
SetPixels copies all of the given pixels at once to the internal buffer. Dimensions of the incoming buffer are checked to ensure they match the width and height of the device. Note that the array should be indexed in row, col order.
type DriverOption ¶
type DriverOption func(*driverOptions)
DriverOption allows specifying behavior for the driver.
func WithGamma ¶
func WithGamma(gamma []byte) DriverOption
WithGamma allows overriding the gamma curve for the driver. Must include 256 level mappings.
func WithRotation ¶
func WithRotation(rotation Rotation) DriverOption
WithRotation applies rotation to the internal buffer before pushing pixels to the device. Note that this can alter the final width/height of the device. If you need to dynamically check these values, use the Width and Height functions.
type Rotation ¶
type Rotation uint16
Rotation specifies a rotation amount.
const ( // Rotation0 specifies no display rotation. Rotation0 Rotation = 0 // Rotation90 specifies 90 degree display rotation. Rotation90 Rotation = 90 // Rotation180 specifies 180 degree display rotation. Rotation180 Rotation = 180 // Rotation270 specifies 270 degree display rotation. Rotation270 Rotation = 270 )
Source Files