SH1106 Go Driver

A Go library for controlling SH1106 OLED displays with text rendering capabilities.

demo.mp4

https://www.waveshare.com/1.3inch-oled-hat.htm

Features

• SH1106 Display Driver: Full support for SH1106 OLED displays via SPI
• Text Rendering: BDF font support with embedded font option
• Joystick Support: Complete joystick/button handling with callbacks
• Easy Integration: Simple API for quick integration
• Examples: Complete examples showing different usage patterns

Installation

go get github.com/danielgatis/go-sh1106

Quick Start

package main

import (
    "log"
    
    "github.com/danielgatis/go-sh1106/pkg/display"
    "github.com/danielgatis/go-sh1106/pkg/text"
    
    "periph.io/x/conn/v3/gpio/gpioreg"
    "periph.io/x/conn/v3/spi/spireg"
    "periph.io/x/host/v3"
)

func main() {
    // Initialize periph.io
    host.Init()
    
    // Open SPI bus
    bus, _ := spireg.Open("")
    
    // Configure GPIO pins
    dc := gpioreg.ByName("GPIO24")
    rst := gpioreg.ByName("GPIO25")
    cs := gpioreg.ByName("GPIO8")
    
    // Create display
    dev, _ := display.NewSH1106SPI(bus, dc, rst, cs, &display.Options{
        Width:  128,
        Height: 64,
    })
    defer dev.Halt()
    
    // Create text renderer with embedded font
    textRenderer, _ := text.NewRendererWithEmbeddedFont(&text.Config{
        Width:     128,
        Height:    64,
        LineCount: 6,
    })
    
    // Set text and display
    textRenderer.SetTexts([]string{
        "Hello World!",
        "SH1106 Display",
        "Go Library",
    })
    
    dev.Draw(textRenderer.Bounds(), textRenderer.Image(), image.Point{})
}

Enable SPI on Raspberry Pi

sudo raspi-config
# Navigate to: Interfacing Options > SPI > Enable

Packages

Display Package (pkg/display)

SH1106 OLED display driver with SPI support.

Text Package (pkg/text)

Text rendering with BDF font support and embedded font option.

// With embedded font (no external file needed)
renderer, _ := text.NewRendererWithEmbeddedFont(&text.Config{
    Width:     128,
    Height:    64,
    LineCount: 6,
})

// Or with custom BDF font file
renderer, _ := text.NewRenderer("path/to/font.bdf", &text.Config{
    Width:     128,
    Height:    64,
    LineCount: 6,
})

Joystick Package (pkg/joystick)

Complete joystick/button event handling with multiple callback support.

import "github.com/danielgatis/go-sh1106/pkg/joystick"

// Create joystick
joy := joystick.NewJoystick(upPin, downPin, leftPin, rightPin, btn1, btn2, btn3)

// Register multiple callbacks (returns remove function)
remove1 := joy.OnClickUp(func() {
    fmt.Println("UP clicked - Callback 1")
})

remove2 := joy.OnClickUp(func() {
    fmt.Println("UP clicked - Callback 2")
})

// Configure
joy.SetHoldDuration(500 * time.Millisecond)
joy.SetPollInterval(50 * time.Millisecond)

// Start polling
joy.Start()
defer joy.Stop()

// Remove specific callback
remove1()

Supported Events:

• OnClick[Button]() - Triggered on button press
• OnHold[Button]() - Triggered when button held (default 500ms)
• OnRelease[Button]() - Triggered on button release

Available Buttons: Up, Down, Left, Right, Button1, Button2, Button3

Examples

Basic Display Example

cd examples/basic
go run main.go "YOUR MESSAGE"

Animation Example

cd examples/animation
go run main.go

Joystick Example

cd examples/joystick
go run main.go

Interactive Menu Example

Complete example combining display, text rendering, and joystick navigation:

cd examples/interactive
go run main.go

This example demonstrates:

• Interactive menu navigation with joystick
• Real-time display updates
• Multiple callback handling
• State management

Building for Raspberry Pi

# Build for Raspberry Pi
GOOS=linux GOARCH=arm go build -o basic examples/basic/main.go

# Copy to Raspberry Pi
scp basic pi@raspberrypi.local:.

License

Copyright (c) 2025-present Daniel Gatis

Licensed under MIT License

Buy me a coffee

Liked some of my work? Buy me a coffee (or more likely a beer)