Class that stores state and functions for interacting with Adafruit DotStars and compatible devices. More...

#include <Adafruit_DotStar.h>

Public Member Functions
	Adafruit_DotStar (uint16_t n, uint8_t o=DOTSTAR_BRG, SPIClass *spi=&SPI)
	DotStar constructor for hardware SPI. Must be connected to MOSI, SCK pins. More...

	Adafruit_DotStar (uint16_t n, uint8_t d, uint8_t c, uint8_t o=DOTSTAR_BRG)
	DotStar constructor for 'soft' (bitbang) SPI. Any two pins can be used. More...

	~Adafruit_DotStar (void)
	Deallocate Adafruit_DotStar object, set data and clock pins back to INPUT.

void	begin (void)
	Initialize Adafruit_DotStar object – sets data and clock pins to outputs and initializes hardware SPI if necessary.

void	show (void)
	Transmit pixel data in RAM to DotStars.

void	setPixelColor (uint16_t n, uint32_t c)
	Set a pixel's color using a 32-bit 'packed' RGB value. More...

void	setPixelColor (uint16_t n, uint8_t r, uint8_t g, uint8_t b)
	Set a pixel's color using separate red, green and blue components. More...

void	fill (uint32_t c=0, uint16_t first=0, uint16_t count=0)
	Fill all or part of the DotStar strip with a color. More...

void	setBrightness (uint8_t)
	Adjust output brightness. Does not immediately affect what's currently displayed on the LEDs. The next call to show() will refresh the LEDs at this level. More...

void	clear ()
	Fill the whole DotStar strip with 0 / black / off.

void	updateLength (uint16_t n)
	Change the length of a previously-declared Adafruit_DotStar strip object. Old data is deallocated and new data is cleared. Pin numbers and pixel format are unchanged. More...

void	updatePins (void)
	Switch over to hardware SPI. DotStars must be connected to MOSI, SCK pins. Data in pixel buffer is unaffected and can continue to be used.

void	updatePins (uint8_t d, uint8_t c)
	Switch over to 'soft' (bitbang) SPI. DotStars can be connected to any two pins. Data in pixel buffer is unaffected and can continue to be used. More...

uint8_t *	getPixels (void) const
	Get a pointer directly to the DotStar data buffer in RAM. Pixel data is stored in a device-native format (a la the DOTSTAR_* constants) and is not translated here. Applications that access this buffer will need to be aware of the specific data format and handle colors appropriately. More...

uint8_t	getBrightness (void) const
	Retrieve the last-set brightness value for the strip. More...

uint16_t	numPixels (void) const
	Return the number of pixels in an Adafruit_DotStar strip object. More...

uint32_t	getPixelColor (uint16_t n) const
	Query the color of a previously-set pixel. More...

void	rainbow (uint16_t first_hue=0, int8_t reps=1, uint8_t saturation=255, uint8_t brightness=255, boolean gammify=true)
	Fill DotStar strip with one or more cycles of hues. Everyone loves the rainbow swirl so much, now it's canon! More...

Static Public Member Functions
static uint8_t	sine8 (uint8_t x)
	An 8-bit integer sine wave function, not directly compatible with standard trigonometric units like radians or degrees. More...

static uint8_t	gamma8 (uint8_t x)
	An 8-bit gamma-correction function for basic pixel brightness adjustment. Makes color transitions appear more perceptially correct. More...

static uint32_t	Color (uint8_t r, uint8_t g, uint8_t b)
	Convert separate red, green and blue values into a single "packed" 32-bit RGB color. More...

static uint32_t	ColorHSV (uint16_t hue, uint8_t sat=255, uint8_t val=255)
	Convert hue, saturation and value into a packed 32-bit RGB color that can be passed to setPixelColor() or other RGB-compatible functions. More...

static uint32_t	gamma32 (uint32_t x)
	A gamma-correction function for 32-bit packed RGB colors. Makes color transitions appear more perceptially correct. More...

Detailed Description

Class that stores state and functions for interacting with Adafruit DotStars and compatible devices.

Constructor & Destructor Documentation

◆ Adafruit_DotStar() [1/2]

Adafruit_DotStar::Adafruit_DotStar	(	uint16_t	n,
		uint8_t	o = `DOTSTAR_BRG`,
		SPIClass *	spi = `&SPI`
	)

DotStar constructor for hardware SPI. Must be connected to MOSI, SCK pins.

Parameters

n	Number of DotStars in strand.
o	Pixel type – one of the DOTSTAR_* constants defined in Adafruit_DotStar.h, for example DOTSTAR_BRG for DotStars expecting color bytes expressed in blue, red, green order per pixel. Default if unspecified is DOTSTAR_BRG.
spi	Pointer to hardware SPIClass object (default is primary SPI device 'SPI' if defined, else MUST pass in device).

Returns: Adafruit_DotStar object. Call the begin() function before use.

◆ Adafruit_DotStar() [2/2]

Adafruit_DotStar::Adafruit_DotStar	(	uint16_t	n,
		uint8_t	data,
		uint8_t	clock,
		uint8_t	o = `DOTSTAR_BRG`
	)

DotStar constructor for 'soft' (bitbang) SPI. Any two pins can be used.

Parameters

n	Number of DotStars in strand.
data	Arduino pin number for data out.
clock	Arduino pin number for clock out.
o	Pixel type – one of the DOTSTAR_* constants defined in Adafruit_DotStar.h, for example DOTSTAR_BRG for DotStars expecting color bytes expressed in blue, red, green order per pixel. Default if unspecified is DOTSTAR_BRG.

Returns: Adafruit_DotStar object. Call the begin() function before use.

Member Function Documentation

◆ setPixelColor() [1/2]

void Adafruit_DotStar::setPixelColor	(	uint16_t	n,
		uint32_t	c
	)

Set a pixel's color using a 32-bit 'packed' RGB value.

Parameters

n	Pixel index, starting from 0.
c	32-bit color value. Most significant byte is 0, second is red, then green, and least significant byte is blue. e.g. 0x00RRGGBB

◆ setPixelColor() [2/2]

void Adafruit_DotStar::setPixelColor	(	uint16_t	n,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

Set a pixel's color using separate red, green and blue components.

Parameters

n	Pixel index, starting from 0.
r	Red brightness, 0 = minimum (off), 255 = maximum.
g	Green brightness, 0 = minimum (off), 255 = maximum.
b	Blue brightness, 0 = minimum (off), 255 = maximum.

◆ fill()

void Adafruit_DotStar::fill	(	uint32_t	c = `0`,
		uint16_t	first = `0`,
		uint16_t	count = `0`
	)

Fill all or part of the DotStar strip with a color.

Parameters

c	32-bit color value. Most significant byte is 0, second is red, then green, and least significant byte is blue. e.g. 0x00RRGGBB. If all arguments are unspecified, this will be 0 (off).
first	Index of first pixel to fill, starting from 0. Must be in-bounds, no clipping is performed. 0 if unspecified.
count	Number of pixels to fill, as a positive value. Passing 0 or leaving unspecified will fill to end of strip.

◆ setBrightness()

void Adafruit_DotStar::setBrightness ( uint8_t b )

Adjust output brightness. Does not immediately affect what's currently displayed on the LEDs. The next call to show() will refresh the LEDs at this level.

Parameters

b	Brightness setting, 0=minimum (off), 255=brightest.

Note: For various reasons I think brightness is better handled in one's sketch, but it's here for parity with the NeoPixel library. Good news is that brightness setting in this library is 'non destructive' – it's applied as color data is being issued to the strip, not during setPixelColor(), and also means that getPixelColor() returns the exact value originally stored.

◆ updateLength()

void Adafruit_DotStar::updateLength ( uint16_t n )

Change the length of a previously-declared Adafruit_DotStar strip object. Old data is deallocated and new data is cleared. Pin numbers and pixel format are unchanged.

Parameters

n	New length of strip, in pixels.

Note: This function is deprecated, here only for old projects that may still be calling it. New projects should instead use the 'new' keyword.

◆ updatePins()

void Adafruit_DotStar::updatePins	(	uint8_t	data,
		uint8_t	clock
	)

Switch over to 'soft' (bitbang) SPI. DotStars can be connected to any two pins. Data in pixel buffer is unaffected and can continue to be used.

Parameters

data	Arduino pin number for data out.
clock	Arduino pin number for clock out.

◆ getPixels()

uint8_t* Adafruit_DotStar::getPixels ( void ) const

inline

Get a pointer directly to the DotStar data buffer in RAM. Pixel data is stored in a device-native format (a la the DOTSTAR_* constants) and is not translated here. Applications that access this buffer will need to be aware of the specific data format and handle colors appropriately.

Returns: Pointer to DotStar buffer (uint8_t* array).

Note: This is for high-performance applications where calling setPixelColor() on every single pixel would be too slow (e.g. POV or light-painting projects). There is no bounds checking on the array, creating tremendous potential for mayhem if one writes past the ends of the buffer. Great power, great responsibility and all that.

◆ getBrightness()

uint8_t Adafruit_DotStar::getBrightness ( void ) const

Retrieve the last-set brightness value for the strip.

Returns: Brightness value: 0 = minimum (off), 255 = maximum.

◆ numPixels()

uint16_t Adafruit_DotStar::numPixels ( void ) const

inline

Return the number of pixels in an Adafruit_DotStar strip object.

Returns: Pixel count (0 if not set).

◆ getPixelColor()

uint32_t Adafruit_DotStar::getPixelColor ( uint16_t n ) const

Query the color of a previously-set pixel.

Parameters

n	Index of pixel to read (0 = first).

Returns: 'Packed' 32-bit RGB value. Most significant byte is 0, second is is red, then green, and least significant byte is blue.

◆ sine8()

static uint8_t Adafruit_DotStar::sine8 ( uint8_t x )

inlinestatic

An 8-bit integer sine wave function, not directly compatible with standard trigonometric units like radians or degrees.

Parameters

x	Input angle, 0-255; 256 would loop back to zero, completing the circle (equivalent to 360 degrees or 2 pi radians). One can therefore use an unsigned 8-bit variable and simply add or subtract, allowing it to overflow/underflow and it still does the expected contiguous thing.

Returns: Sine result, 0 to 255, or -128 to +127 if type-converted to a signed int8_t, but you'll most likely want unsigned as this output is often used for pixel brightness in animation effects.

◆ gamma8()

static uint8_t Adafruit_DotStar::gamma8 ( uint8_t x )

inlinestatic

An 8-bit gamma-correction function for basic pixel brightness adjustment. Makes color transitions appear more perceptially correct.

Parameters

x	Input brightness, 0 (minimum or off/black) to 255 (maximum).

Returns: Gamma-adjusted brightness, can then be passed to one of the setPixelColor() functions. This uses a fixed gamma correction exponent of 2.6, which seems reasonably okay for average DotStars in average tasks. If you need finer control you'll need to provide your own gamma-correction function instead.

◆ Color()

static uint32_t Adafruit_DotStar::Color	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

inlinestatic

Convert separate red, green and blue values into a single "packed" 32-bit RGB color.

Parameters

r	Red brightness, 0 to 255.
g	Green brightness, 0 to 255.
b	Blue brightness, 0 to 255.

Returns: 32-bit packed RGB value, which can then be assigned to a variable for later use or passed to the setPixelColor() function. Packed RGB format is predictable, regardless of LED strand color order.

◆ ColorHSV()

uint32_t Adafruit_DotStar::ColorHSV	(	uint16_t	hue,
		uint8_t	sat = `255`,
		uint8_t	val = `255`
	)

static

Convert hue, saturation and value into a packed 32-bit RGB color that can be passed to setPixelColor() or other RGB-compatible functions.

Parameters

hue	An unsigned 16-bit value, 0 to 65535, representing one full loop of the color wheel, which allows 16-bit hues to "roll over" while still doing the expected thing (and allowing more precision than the wheel() function that was common to prior DotStar and NeoPixel examples).
sat	Saturation, 8-bit value, 0 (min or pure grayscale) to 255 (max or pure hue). Default of 255 if unspecified.
val	Value (brightness), 8-bit value, 0 (min / black / off) to 255 (max or full brightness). Default of 255 if unspecified.

Returns: Packed 32-bit RGB color. Result is linearly but not perceptually correct, so you may want to pass the result through the gamma32() function (or your own gamma-correction operation) else colors may appear washed out. This is not done automatically by this function because coders may desire a more refined gamma- correction function than the simplified one-size-fits-all operation of gamma32(). Diffusing the LEDs also really seems to help when using low-saturation colors.

◆ gamma32()

uint32_t Adafruit_DotStar::gamma32 ( uint32_t x )

static

A gamma-correction function for 32-bit packed RGB colors. Makes color transitions appear more perceptially correct.

Parameters

x	32-bit packed RGB color.

Returns: Gamma-adjusted packed color, can then be passed in one of the setPixelColor() functions. Like gamma8(), this uses a fixed gamma correction exponent of 2.6, which seems reasonably okay for average DotStars in average tasks. If you need finer control you'll need to provide your own gamma-correction function instead.

◆ rainbow()

void Adafruit_DotStar::rainbow	(	uint16_t	first_hue = `0`,
		int8_t	reps = `1`,
		uint8_t	saturation = `255`,
		uint8_t	brightness = `255`,
		boolean	gammify = `true`
	)

Fill DotStar strip with one or more cycles of hues. Everyone loves the rainbow swirl so much, now it's canon!

Parameters

first_hue	Hue of first pixel, 0-65535, representing one full cycle of the color wheel. Each subsequent pixel will be offset to complete one or more cycles over the length of the strip.
reps	Number of cycles of the color wheel over the length of the strip. Default is 1. Negative values can be used to reverse the hue order.
saturation	Saturation (optional), 0-255 = gray to pure hue, default = 255.
brightness	Brightness/value (optional), 0-255 = off to max, default = 255. This is distinct and in combination with any configured global strip brightness.
gammify	If true (default), apply gamma correction to colors for better appearance.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Adafruit_DotStar() [1/2]

◆ Adafruit_DotStar() [2/2]

Member Function Documentation

◆ setPixelColor() [1/2]

◆ setPixelColor() [2/2]

◆ fill()

◆ setBrightness()

◆ updateLength()

◆ updatePins()

◆ getPixels()

◆ getBrightness()

◆ numPixels()

◆ getPixelColor()

◆ sine8()

◆ gamma8()

◆ Color()

◆ ColorHSV()

◆ gamma32()

◆ rainbow()