A Go library for controlling iPixel Color LED displays via Bluetooth Low Energy (BLE).
go-ipxl provides a clean, idiomatic Go interface for communicating with iPixel Color devices. The library handles BLE connectivity, device discovery, image processing, and data transmission protocols required to control LED matrix displays.
- BLE Connectivity: Seamless Bluetooth Low Energy connection management
- Device Information: Query device specifications, firmware versions, and screen dimensions
- Image Display: Send images directly to LED matrices with automatic scaling and color conversion
- Format Support: Built-in support for PNG and JPEG image formats
- DIY Modes: Switch between different display modes including DIY functionality
- Low-Level Control: Direct LED control and raw data transmission capabilities
- Robust Protocol: Implements chunked data transmission with CRC verification
go get github.com/yyewolf/go-ipxlpackage main
import (
"context"
"log"
"time"
"github.com/yyewolf/go-ipxl"
)
func main() {
// Create a new display instance
display := ipxl.NewDisplay("AA:BB:CC:DD:EE:FF")
// Connect to the device
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := display.Connect(ctx); err != nil {
log.Fatal("Failed to connect:", err)
}
defer display.Disconnect()
// Get device information
info, err := display.GetDeviceInfo(ctx)
if err != nil {
log.Fatal("Failed to get device info:", err)
}
log.Printf("Device: %dx%d matrix, MCU: %s, WiFi: %s",
info.Width, info.Height, info.MCUVersion, info.WiFiVersion)
// Load and send an image
processor := ipxl.NewBitmapProcessor(info.Width, info.Height)
img, err := processor.LoadImageFromFile("image.png")
if err != nil {
log.Fatal("Failed to load image:", err)
}
if err := display.SendImage(ctx, img); err != nil {
log.Fatal("Failed to send image:", err)
}
}The main interface for interacting with iPixel devices:
type Display interface {
Connect(ctx context.Context) error
Disconnect() error
GetScreenSize(ctx context.Context) (width, height int, err error)
GetDeviceInfo(ctx context.Context) (*DeviceInfo, error)
SetLED(on bool) error
SendImage(ctx context.Context, image image.Image) error
SwitchToDiyFunMode(mode int) error
}Query device specifications and capabilities:
type DeviceInfo struct {
DeviceType byte // Device type identifier
MCUVersion string // Microcontroller firmware version
WiFiVersion string // WiFi/BLE module version
Width int // LED matrix width
Height int // LED matrix height
HasWifi bool // WiFi capability flag
PasswordFlag byte // Password requirement status
}Convert and process images for LED display:
// Create a bitmap processor for your display dimensions
processor := ipxl.NewBitmapProcessor(64, 64)
// Load from file
img, err := processor.LoadImageFromFile("path/to/image.png")
// Convert to RGB data
rgbData := processor.ImageToRGB(img)- PNG
- JPEG
- Any format supported by Go's
imagepackage
Images are automatically resized and color-converted to match the target LED matrix dimensions.
The library handles BLE connection lifecycle automatically:
- Device scanning and discovery
- Characteristic enumeration
- Connection timeout handling
- Automatic cleanup on disconnect
Images are transmitted using a chunked protocol with:
- 12KB chunk size for optimal BLE throughput
- CRC32 verification for data integrity
- Sequential transmission with proper packet ordering
- Support for various data types (images, videos, text, etc.)
All operations return descriptive errors for proper error handling:
if err := display.Connect(ctx); err != nil {
switch {
case errors.Is(err, context.DeadlineExceeded):
log.Println("Connection timeout")
case strings.Contains(err.Error(), "characteristic not found"):
log.Println("Device not compatible")
default:
log.Printf("Connection failed: %v", err)
}
}- Go 1.21+
- Bluetooth Low Energy support
- Platform support via TinyGo Bluetooth
The library uses TinyGo's bluetooth package, which supports:
- Linux (BlueZ)
- macOS (Core Bluetooth)
- Windows (WinRT)
Contributions are welcome! Please feel free to submit pull requests, report bugs, or suggest features.
Based on the iPixel protocol implementation and inspired by the original Android SDK.