ssd1306

Documentation

Overview

Package ssd1306 controls a 128x64 monochrome OLED display via a SSD1306 controller.

The driver does differential updates: it only sends modified pixels for the smallest rectangle, to economize bus bandwidth. This is especially important when using I²C as the bus default speed (often 100kHz) is slow enough to saturate the bus at less than 10 frames per second.

The SSD1306 is a write-only device. It can be driven on either I²C or SPI with 4 wires. Changing between protocol is likely done through resistor soldering, for boards that support both.

Some boards expose a RES / Reset pin. If present, it must be normally be High. When set to Low (Ground), it enables the reset circuitry. It can be used externally to this driver, if used, the driver must be reinstantiated.

More details

See https://periph.io/device/ssd1306/ for more details about the device.

Datasheets

Product page: http://www.solomon-systech.com/en/product/display-ic/oled-driver-controller/ssd1306/

https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf

"DM-OLED096-624": https://drive.google.com/file/d/0B5lkVYnewKTGaEVENlYwbDkxSGM/view

"ssd1306": https://drive.google.com/file/d/0B5lkVYnewKTGYzhyWWp0clBMR1E/view

Example

package main

import (
	"image"
	"log"

	"periph.io/x/periph/conn/i2c/i2creg"
	"periph.io/x/periph/devices/ssd1306"
	"periph.io/x/periph/devices/ssd1306/image1bit"
	"periph.io/x/periph/host"
)

func main() {
	// Make sure periph is initialized.
	if _, err := host.Init(); err != nil {
		log.Fatal(err)
	}

	// Use i2creg I²C bus registry to find the first available I²C bus.
	b, err := i2creg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer b.Close()

	dev, err := ssd1306.NewI2C(b, &ssd1306.DefaultOpts)
	if err != nil {
		log.Fatalf("failed to initialize ssd1306: %v", err)
	}

	// Draw on it.
	img := image1bit.NewVerticalLSB(dev.Bounds())
	// Note: this code is commented out so periph does not depend on:
	//    "golang.org/x/image/font"
	//    "golang.org/x/image/font/basicfont"
	//    "golang.org/x/image/math/fixed"
	//
	// f := basicfont.Face7x13
	// drawer := font.Drawer{
	// 	Dst:  img,
	// 	Src:  &image.Uniform{image1bit.On},
	// 	Face: f,
	// 	Dot:  fixed.P(0, img.Bounds().Dy()-1-f.Descent),
	// }
	// drawer.DrawString("Hello from periph!")
	if err := dev.Draw(dev.Bounds(), img, image.Point{}); err != nil {
		log.Fatal(err)
	}
}

Index

• Variables
• type Dev
  • func NewI2C(i i2c.Bus, opts *Opts) (*Dev, error)
  • func NewSPI(p spi.Port, dc gpio.PinOut, opts *Opts) (*Dev, error)
  • func (d *Dev) Bounds() image.Rectangle
  • func (d *Dev) ColorModel() color.Model
  • func (d *Dev) Draw(r image.Rectangle, src image.Image, sp image.Point) error
  • func (d *Dev) Halt() error
  • func (d *Dev) Invert(blackOnWhite bool) error
  • func (d *Dev) Scroll(o Orientation, rate FrameRate, startLine, endLine int) error
  • func (d *Dev) SetContrast(level byte) error
  • func (d *Dev) StopScroll() error
  • func (d *Dev) String() string
  • func (d *Dev) Write(pixels []byte) (int, error)
• type FrameRate
• type Opts
• type Orientation

Examples

• Package

Variables

var DefaultOpts = Opts{
	W:             128,
	H:             64,
	Rotated:       false,
	Sequential:    false,
	SwapTopBottom: false,
}

DefaultOpts is the recommended default options.

Types

type Dev

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

Dev is an open handle to the display controller.

func NewI2C

func NewI2C(i i2c.Bus, opts *Opts) (*Dev, error)

NewI2C returns a Dev object that communicates over I²C to a SSD1306 display controller.

func NewSPI

func NewSPI(p spi.Port, dc gpio.PinOut, opts *Opts) (*Dev, error)

NewSPI returns a Dev object that communicates over SPI to a SSD1306 display controller.

The SSD1306 can operate at up to 3.3Mhz, which is much higher than I²C. This permits higher refresh rates.

Wiring

Connect SDA to SPI_MOSI, SCK to SPI_CLK, CS to SPI_CS.

In 3-wire SPI mode, pass nil for 'dc'. In 4-wire SPI mode, pass a GPIO pin to use.

The RES (reset) pin can be used outside of this driver but is not supported natively. In case of external reset via the RES pin, this device drive must be reinstantiated.

func (*Dev) Bounds

func (d *Dev) Bounds() image.Rectangle

Bounds implements display.Drawer. Min is guaranteed to be {0, 0}.

func (*Dev) ColorModel

func (d *Dev) ColorModel() color.Model

ColorModel implements display.Drawer.

It is a one bit color model, as implemented by image1bit.Bit.

func (*Dev) Draw

func (d *Dev) Draw(r image.Rectangle, src image.Image, sp image.Point) error

Draw implements display.Drawer.

It draws synchronously, once this function returns, the display is updated. It means that on slow bus (I²C), it may be preferable to defer Draw() calls to a background goroutine.

func (*Dev) Halt

func (d *Dev) Halt() error

Halt turns off the display.

Sending any other command afterward reenables the display.

func (*Dev) Invert

func (d *Dev) Invert(blackOnWhite bool) error

Invert the display (black on white vs white on black).

func (*Dev) Scroll

func (d *Dev) Scroll(o Orientation, rate FrameRate, startLine, endLine int) error

Scroll scrolls an horizontal band.

Only one scrolling operation can happen at a time.

Both startLine and endLine must be multiples of 8.

Use -1 for endLine to extend to the bottom of the display.

func (*Dev) SetContrast

func (d *Dev) SetContrast(level byte) error

SetContrast changes the screen contrast.

Note: values other than 0xff do not seem useful...

func (*Dev) StopScroll

func (d *Dev) StopScroll() error

StopScroll stops any scrolling previously set and resets the screen.

func (*Dev) String

func (d *Dev) String() string

func (*Dev) Write

func (d *Dev) Write(pixels []byte) (int, error)

Write writes a buffer of pixels to the display.

The format is unsual as each byte represent 8 vertical pixels at a time. The format is horizontal bands of 8 pixels high.

This function accepts the content of image1bit.VerticalLSB.Pix.

type FrameRate

type FrameRate byte

FrameRate determines scrolling speed.

const (
	FrameRate2   FrameRate = 7
	FrameRate3   FrameRate = 4
	FrameRate4   FrameRate = 5
	FrameRate5   FrameRate = 0
	FrameRate25  FrameRate = 6
	FrameRate64  FrameRate = 1
	FrameRate128 FrameRate = 2
	FrameRate256 FrameRate = 3
)

Possible frame rates. The value determines the number of refreshes between movement. The lower value, the higher speed.

type Opts

type Opts struct {
	W int
	H int
	// Rotated determines if the display is rotated by 180°.
	Rotated bool
	// Sequential corresponds to the Sequential/Alternative COM pin configuration
	// in the OLED panel hardware. Try toggling this if half the rows appear to be
	// missing on your display.
	Sequential bool
	// SwapTopBottom corresponds to the Left/Right remap COM pin configuration in
	// the OLED panel hardware. Try toggling this if the top and bottom halves of
	// your display are swapped.
	SwapTopBottom bool
}

Opts defines the options for the device.

type Orientation

type Orientation byte

Orientation is used for scrolling.

const (
	Left    Orientation = 0x27
	Right   Orientation = 0x26
	UpRight Orientation = 0x29
	UpLeft  Orientation = 0x2A
)

Possible orientations for scrolling.