apa102

package
v0.0.0-...-c768f7d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 23, 2021 License: Apache-2.0 Imports: 8 Imported by: 0

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.

More details

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

Datasheet

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

Example
// 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, spi.Mode0)
if err != nil {
	log.Fatalf("failed to open: %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.Fatalf("failed to draw: %v", err)
}
Output:

Index

Examples

Constants

View Source
const NeutralTemp uint16 = 6500

NeutralTemp is the temperature where the color temperature correction is disabled.

Use this value for Opts.Temperature so that the driver uses the exact color you specified, without temperature correction.

Variables

View Source
var DefaultOpts = Opts{
	NumPixels:        150,
	Intensity:        255,
	Temperature:      5000,
	DisableGlobalPWM: false,
}

DefaultOpts is the recommended default options.

View Source
var PassThruOpts = Opts{
	NumPixels:        150,
	Intensity:        255,
	Temperature:      NeutralTemp,
	DisableGlobalPWM: true,
}

PassThruOpts makes the driver draw RGB pixels exactly as specified.

Use this if you want the APA102 LEDs to behave like normal 8 bits LEDs without the extended range nor any color temperature correction.

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.

Example
// 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()

o := apa102.PassThruOpts
o.NumPixels = 2
dev, err := apa102.New(p, &o, spi.Mode3)
if err != nil {
	log.Fatalf("failed to open: %v", err)
}
if _, err = dev.Write(apa102.ToRGB([]color.NRGBA{{R: 0xFF, G: 0xFF, B: 0xFF}, {R: 0x80, G: 0x80, B: 0x80}})); err != nil {
	log.Fatalf("failed to draw: %v", err)
}
Output:

Types

type Dev

type Dev struct {
	// Intensity set the intensity range.
	//
	// See Opts.Intensity for more information.
	//
	// Takes effect on the next Draw() or Write() call.
	Intensity uint8
	// Temperature is the white adjustment in °Kelvin.
	//
	// See Opts.Temperature for more information.
	//
	// Takes effect on the next Draw() or Write() call.
	Temperature uint16
	// DisableGlobalPWM disables the use of the global 5 bits PWM.
	//
	// See Opts.DisableGlobalPWM for more information.
	//
	// Takes effect on the next Draw() or Write() call.
	DisableGlobalPWM bool
	// 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, spiMode spi.Mode) (*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.

Most devices can use spi.Mode3, but the raspberry pi 3 secondary SPI for example does not support this Mode. You may need to use spi.Mode0 in this and similar cases.

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.
	// Use 255 for full intensity, 0 turns all lights off.
	Intensity uint8
	// Temperature declares the white color to use, specified in Kelvin.  Has no
	// effect when RawColors is true.
	//
	// This driver assumes the LEDs are emitting a 6500K white color. Use
	// NeutralTemp to disable color correction.
	Temperature uint16
	// DisableGlobalPWM disables the global 5 bits PWM and only use the 8 bit
	// color channels, and also disables perceptual mapping.
	//
	// The global PWM runs at 580Hz while the color channel PWMs run at 19.2kHz.
	// Because of the low frequency of the global PWM, it may result in human
	// visible flicker.
	//
	// The driver will by default use a non-linear intensity mapping to match
	// what the human eye perceives. By reducing the dynamic range from 13 bits
	// to 8 bits, this also disables the dynamic perceptual mapping of intensity
	// since there is not enough bits of resolution to do it effectively.
	DisableGlobalPWM bool
}

Opts defines the options for the device.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL