apa102

Documentation

Overview

Package apa102 drives a strip of APA102 LEDs connected on a SPI port.

These devices are interesting because they have 2 PWMs: one global of 5 bits of resolution and one per channel of 8 bits of resolution. This means that the dynamic range is of 13 bits.

This driver handles color intensity and temperature correction and uses the full near 8000:1 dynamic range as supported by the device.

Datasheet

https://cpldcpu.files.wordpress.com/2014/08/apa-102c-super-led-specifications-2014-en.pdf

Example

package main

import (
	"image"
	"image/color"
	"log"

	"periph.io/x/periph/conn/spi/spireg"
	"periph.io/x/periph/devices/apa102"
	"periph.io/x/periph/host"
)

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

	// Use spireg SPI port registry to find the first available SPI bus.
	p, err := spireg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer p.Close()

	// Opens a 300 lights strip at 50% intensity with color temperature at
	// 3500°Kelvin.
	o := apa102.DefaultOpts
	o.NumPixels = 300
	o.Intensity = 127
	o.Temperature = 3500
	dev, err := apa102.New(p, &o)
	if err != nil {
		log.Fatalf("failed to open apa102: %v", err)
	}
	img := image.NewNRGBA(image.Rect(0, 0, dev.Bounds().Dy(), 1))
	for x := 0; x < img.Rect.Max.X; x++ {
		img.SetNRGBA(x, 0, color.NRGBA{uint8(x), uint8(255 - x), 0, 255})
	}
	if err := dev.Draw(dev.Bounds(), img, image.Point{}); err != nil {
		log.Fatal(err)
	}
}

Index

• Variables
• func ToRGB(p []color.NRGBA) []byte
• type Dev
  • func New(p spi.Port, o *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) String() string
  • func (d *Dev) Write(pixels []byte) (int, error)
• type Opts

Examples

• Package

Variables

var DefaultOpts = Opts{
	NumPixels:   150,
	Intensity:   255,
	Temperature: 5000,
}

DefaultOpts is the recommended default options.

Functions

func ToRGB

func ToRGB(p []color.NRGBA) []byte

ToRGB converts a slice of color.NRGBA to a byte stream of RGB pixels.

Ignores alpha.

Types

type Dev

type Dev struct {
	// Intensity set the intensity between 0 (off) and 255 (full brightness).
	//
	// It can be changed, it will take effect on the next Draw() or Write() call.
	Intensity uint8
	// Temperature is the white adjustment in °Kelvin.
	//
	// It can be changed, it will take effect on the next Draw() or Write() call.
	Temperature uint16
	// contains filtered or unexported fields
}

Dev represents a strip of APA-102 LEDs as a strip connected over a SPI port. It accepts a stream of raw RGB pixels and converts it to the full dynamic range as supported by APA102 protocol (nearly 8000:1 contrast ratio).

Includes intensity and temperature correction.

func New

func New(p spi.Port, o *Opts) (*Dev, error)

New returns a strip that communicates over SPI to APA102 LEDs.

The SPI port speed should be high, at least in the Mhz range, as there's 32 bits sent per LED, creating a staggered effect. See https://cpldcpu.wordpress.com/2014/11/30/understanding-the-apa102-superled/

As per APA102-C spec, the chip's max refresh rate is 400hz. https://en.wikipedia.org/wiki/Flicker_fusion_threshold is a recommended reading.

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. There's no surprise, it is color.NRGBAModel.

func (*Dev) Draw

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

Draw implements display.Drawer.

Using something else than image.NRGBA is 10x slower. When using image.NRGBA, the alpha channel is ignored.

func (*Dev) Halt

func (d *Dev) Halt() error

Halt turns off all the lights.

func (*Dev) String

func (d *Dev) String() string

func (*Dev) Write

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

Write accepts a stream of raw RGB pixels and sends it as APA102 encoded stream.

type Opts

type Opts struct {
	// NumPixels is the number of pixels to control. If too short, the following
	// pixels will be corrupted. If too long, the pixels will be drawn
	// unnecessarily but not visible issue will occur.
	NumPixels int
	// Intensity is the maximum intensity level to use, on a logarithmic scale.
	// This is useful to safely limit current draw.
	Intensity uint8
	// Temperature declares the white color to use, specified in Kelvin.
	//
	// This driver assumes the LEDs are emitting a 6500K white color.
	Temperature uint16
}

Opts defines the options for the device.