From e72fea9616305e11b78f42b021285784a3c4ad60 Mon Sep 17 00:00:00 2001 From: Dave Cheney Date: Wed, 11 Nov 2026 21:49:43 +1100 Subject: [PATCH] st7567: add driver for ST7567 and AiP31567 LCD controllers This adds a 4-line SPI driver for the ST7567 and the compatible AiP31567, which are used in low cost 128x64 monochrome LCD modules such as the WeAct Studio 1.37 inch Matrix LCD module. Tested on that module with an ESP32-S3 devkit. Rotation0 and Rotation180 both fill all 128 columns, and inverse display works. The default contrast sets V0 to about 8.75 V, close to the 8.8 V in the panel drawing. --- examples/st7567/main.go | 57 ++++++++ examples/st7567/pins_esp32s3.go | 15 ++ smoketest.sh | 1 + st7567/registers.go | 31 ++++ st7567/st7567.go | 247 ++++++++++++++++++++++++++++++++ 5 files changed, 351 insertions(+) create mode 100644 examples/st7567/main.go create mode 100644 examples/st7567/pins_esp32s3.go create mode 100644 st7567/registers.go create mode 100644 st7567/st7567.go diff --git a/examples/st7567/main.go b/examples/st7567/main.go new file mode 100644 index 000000000..62739cb55 --- /dev/null +++ b/examples/st7567/main.go @@ -0,0 +1,57 @@ +// Draws a border, a cross and a block in the top left corner on an ST7567 LCD, +// such as the WeAct Studio 1.37 inch Matrix LCD module. +package main + +import ( + "image/color" + "machine" + "time" + + "tinygo.org/x/drivers/st7567" +) + +func main() { + for _, p := range []machine.Pin{blPin, rstPin, dcPin, csPin} { + p.Configure(machine.PinConfig{Mode: machine.PinOutput}) + } + blPin.High() + + machine.SPI0.Configure(machine.SPIConfig{ + Frequency: 8 * machine.MHz, + SCK: sckPin, + SDO: sdoPin, + SDI: machine.NoPin, + }) + + display := st7567.New(machine.SPI0, csPin, dcPin, rstPin) + if err := display.Configure(st7567.Config{}); err != nil { + for { + println("st7567:", err.Error()) + time.Sleep(time.Second) + } + } + + on := color.RGBA{R: 255, G: 255, B: 255, A: 255} + w, h := display.Size() + for x := int16(0); x < w; x++ { + display.SetPixel(x, 0, on) + display.SetPixel(x, h-1, on) + } + for y := int16(0); y < h; y++ { + display.SetPixel(0, y, on) + display.SetPixel(w-1, y, on) + display.SetPixel(y*w/h, y, on) + display.SetPixel(w-1-y*w/h, y, on) + } + for y := int16(2); y < 12; y++ { + for x := int16(2); x < 22; x++ { + display.SetPixel(x, y, on) + } + } + display.Display() + + for inverted := false; ; inverted = !inverted { + display.SetInverted(inverted) + time.Sleep(2 * time.Second) + } +} diff --git a/examples/st7567/pins_esp32s3.go b/examples/st7567/pins_esp32s3.go new file mode 100644 index 000000000..c820d9762 --- /dev/null +++ b/examples/st7567/pins_esp32s3.go @@ -0,0 +1,15 @@ +//go:build esp32s3 + +package main + +import "machine" + +// Pins for an ESP32-S3 devkit with the WeAct module on GPIO9 to GPIO14. +const ( + blPin = machine.GPIO9 + rstPin = machine.GPIO10 + dcPin = machine.GPIO11 + csPin = machine.GPIO12 + sckPin = machine.GPIO13 + sdoPin = machine.GPIO14 +) diff --git a/smoketest.sh b/smoketest.sh index b9a5636ba..c2b858a49 100755 --- a/smoketest.sh +++ b/smoketest.sh @@ -164,6 +164,7 @@ tinygo build -size short -o ./build/test.hex -target=microbit ./examples/ndir/ma tinygo build -size short -o ./build/test.hex -target=arduino-nano33 ./examples/ndir/main_ndir.go tinygo build -size short -o ./build/test.uf2 -target=pico ./examples/mpu9150/main.go tinygo build -size short -o ./build/test.hex -target=macropad-rp2040 ./examples/sh1106/macropad_spi +tinygo build -size short -o ./build/test.bin -target=esp32s3-generic ./examples/st7567/ tinygo build -size short -o ./build/test.hex -target=macropad-rp2040 ./examples/encoders/quadrature-interrupt tinygo build -size short -o ./build/test.uf2 -target=pico ./examples/mcp9808/main.go tinygo build -size short -o ./build/test.uf2 -target=pico ./examples/tmc2209/main.go diff --git a/st7567/registers.go b/st7567/registers.go new file mode 100644 index 000000000..2268d0f31 --- /dev/null +++ b/st7567/registers.go @@ -0,0 +1,31 @@ +package st7567 + +// Commands from the ST7567 datasheet V1.5, table "Instruction Table". +const ( + cmdDisplayOff = 0xAE + cmdDisplayOn = 0xAF + cmdStartLine = 0x40 + cmdPageAddress = 0xB0 + cmdColumnHigh = 0x10 + cmdColumnLow = 0x00 + cmdSEGNormal = 0xA0 + cmdSEGReverse = 0xA1 + cmdInverseOff = 0xA6 + cmdInverseOn = 0xA7 + cmdAllPixelOff = 0xA4 + cmdBias9 = 0xA2 + cmdBias7 = 0xA3 + cmdReset = 0xE2 + cmdCOMNormal = 0xC0 + cmdCOMReverse = 0xC8 + cmdPowerControl = 0x28 + cmdRegulation = 0x20 + cmdSetEV = 0x81 + powerBoosterOn = 0x04 + powerRegulatorOn = 0x02 + powerFollowerOn = 0x01 + defaultRegulation = 4 // 5.0 + defaultContrast = 36 // V0 = 5.0 * (99 + 36) / 162 * 2.1 = 8.75V + maxContrast = 63 + maxColumns = 132 +) diff --git a/st7567/st7567.go b/st7567/st7567.go new file mode 100644 index 000000000..236657034 --- /dev/null +++ b/st7567/st7567.go @@ -0,0 +1,247 @@ +// Package st7567 implements a driver for the ST7567 and AiP31567 monochrome LCD +// controllers over 4-line SPI. +// +// Datasheet: https://github.com/WeActStudio/WeActStudio.MatrixLCDModule/blob/master/Doc/ST_7567_V1_5.pdf +package st7567 // import "tinygo.org/x/drivers/st7567" + +import ( + "errors" + "image/color" + "time" + + "tinygo.org/x/drivers" + "tinygo.org/x/drivers/internal/pin" +) + +var ( + errUnsupportedRotation = errors.New("st7567: rotation must be Rotation0 or Rotation180") + errOutOfRange = errors.New("st7567: out of range") +) + +// Config is the configuration for the display. +type Config struct { + // Width and Height of the panel in pixels. The default is 128x64. + Width int16 + Height int16 + + // Rotation is Rotation0 or Rotation180. Rotation0 is upright on the WeAct + // Studio 1.37 inch module. + Rotation drivers.Rotation + + // RegulationRatio selects the V0 regulator ratio, 1 to 7 for 3.5 to 6.5. + // Zero selects the default, 4 for 5.0. + RegulationRatio uint8 + + // Contrast is the electronic volume, 1 to 63. Zero selects the default. + Contrast uint8 +} + +// Device is an ST7567 display connected over SPI. +type Device struct { + bus drivers.SPI + cs pin.OutputFunc + dc pin.OutputFunc + rst pin.OutputFunc + width int16 + height int16 + rotation drivers.Rotation + buffer []byte + cmd [2]byte +} + +// New returns a new ST7567 driver. The SPI bus and the pins must already be +// configured, with all pins as outputs. +func New(bus drivers.SPI, csPin, dcPin, resetPin pin.Output) *Device { + return &Device{ + bus: bus, + cs: csPin.Set, + dc: dcPin.Set, + rst: resetPin.Set, + } +} + +// Configure resets and initializes the display, then clears it. +func (d *Device) Configure(cfg Config) error { + d.width = cfg.Width + if d.width == 0 { + d.width = 128 + } + d.height = cfg.Height + if d.height == 0 { + d.height = 64 + } + if d.width > maxColumns || d.height > 64 || d.height%8 != 0 { + return errOutOfRange + } + regulation := cfg.RegulationRatio + if regulation == 0 { + regulation = defaultRegulation + } + contrast := cfg.Contrast + if contrast == 0 { + contrast = defaultContrast + } + if regulation > 7 || contrast > maxContrast { + return errOutOfRange + } + d.buffer = make([]byte, int(d.width)*int(d.height)/8) + + d.cs.High() + d.rst.Low() + time.Sleep(10 * time.Microsecond) + d.rst.High() + time.Sleep(10 * time.Microsecond) + + // Power control must follow the reset within 5ms, see "Initializing with + // the Built-in Power Supply Circuits" in the datasheet. + d.command(cmdBias9) + if err := d.SetRotation(cfg.Rotation); err != nil { + return err + } + d.command(cmdRegulation | regulation) + d.command2(cmdSetEV, contrast) + d.command(cmdPowerControl | powerBoosterOn | powerRegulatorOn | powerFollowerOn) + d.command(cmdStartLine) + d.command(cmdAllPixelOff) + d.command(cmdInverseOff) + + if err := d.Display(); err != nil { + return err + } + d.command(cmdDisplayOn) + return nil +} + +// SetRotation sets Rotation0 or Rotation180. Call Display to redraw. +func (d *Device) SetRotation(rotation drivers.Rotation) error { + switch rotation { + case drivers.Rotation0: + d.command(cmdSEGReverse) + d.command(cmdCOMNormal) + case drivers.Rotation180: + d.command(cmdSEGNormal) + d.command(cmdCOMReverse) + default: + return errUnsupportedRotation + } + d.rotation = rotation + return nil +} + +// Rotation returns the current rotation. +func (d *Device) Rotation() drivers.Rotation { + return d.rotation +} + +// SetContrast sets the electronic volume, 0 to 63. +func (d *Device) SetContrast(contrast uint8) { + if contrast > maxContrast { + contrast = maxContrast + } + d.command2(cmdSetEV, contrast) +} + +// SetInverted inverts all pixels on the display without changing the buffer. +func (d *Device) SetInverted(inverted bool) { + if inverted { + d.command(cmdInverseOn) + } else { + d.command(cmdInverseOff) + } +} + +// Sleep turns the display off when sleep is true and on again when false. +func (d *Device) Sleep(sleep bool) error { + if sleep { + d.command(cmdDisplayOff) + } else { + d.command(cmdDisplayOn) + } + return nil +} + +// Size returns the display size in pixels. +func (d *Device) Size() (x, y int16) { + return d.width, d.height +} + +// GetBuffer returns the buffer. Each byte holds 8 vertical pixels with the top +// pixel in bit 0, and each page of 8 rows is Width bytes. +func (d *Device) GetBuffer() []byte { + return d.buffer +} + +// ClearBuffer clears the buffer. +func (d *Device) ClearBuffer() { + clear(d.buffer) +} + +// ClearDisplay clears the buffer and the display. +func (d *Device) ClearDisplay() error { + d.ClearBuffer() + return d.Display() +} + +// SetPixel sets a pixel in the buffer. Any colour other than black turns the +// pixel on. +func (d *Device) SetPixel(x, y int16, c color.RGBA) { + if x < 0 || x >= d.width || y < 0 || y >= d.height { + return + } + i := int(x) + int(y/8)*int(d.width) + if c.R != 0 || c.G != 0 || c.B != 0 { + d.buffer[i] |= 1 << uint(y%8) + } else { + d.buffer[i] &^= 1 << uint(y%8) + } +} + +// GetPixel reports whether a pixel in the buffer is on. +func (d *Device) GetPixel(x, y int16) bool { + if x < 0 || x >= d.width || y < 0 || y >= d.height { + return false + } + return d.buffer[int(x)+int(y/8)*int(d.width)]&(1<>4) + d.command(cmdColumnLow | offset&0x0F) + if err := d.data(d.buffer[page*w : (page+1)*w]); err != nil { + return err + } + } + return nil +} + +func (d *Device) command(c uint8) error { + d.cmd[0] = c + return d.write(d.cmd[:1], false) +} + +func (d *Device) command2(c, v uint8) error { + d.cmd[0] = c + d.cmd[1] = v + return d.write(d.cmd[:2], false) +} + +func (d *Device) data(b []byte) error { + return d.write(b, true) +} + +func (d *Device) write(b []byte, isData bool) error { + d.dc(isData) + d.cs.Low() + err := d.bus.Tx(b, nil) + d.cs.High() + return err +}