Adafruit DotStar Arduino Library
Public Member Functions | Static Public Member Functions | List of all members
Adafruit_DotStar Class Reference

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)
 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 
)

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

Parameters
nNumber of DotStars in strand.
oPixel 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.

◆ 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
nNumber of DotStars in strand.
dataArduino pin number for data out.
clockArduino pin number for clock out.
oPixel 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
nPixel index, starting from 0.
c32-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
nPixel index, starting from 0.
rRed brightness, 0 = minimum (off), 255 = maximum.
gGreen brightness, 0 = minimum (off), 255 = maximum.
bBlue 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
c32-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).
firstIndex of first pixel to fill, starting from 0. Must be in-bounds, no clipping is performed. 0 if unspecified.
countNumber 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
bBrightness 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
nNew 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
dataArduino pin number for data out.
clockArduino 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
nIndex 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
xInput 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
xInput 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
rRed brightness, 0 to 255.
gGreen brightness, 0 to 255.
bBlue 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
hueAn 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).
satSaturation, 8-bit value, 0 (min or pure grayscale) to 255 (max or pure hue). Default of 255 if unspecified.
valValue (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
x32-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_hueHue 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.
repsNumber 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.
saturationSaturation (optional), 0-255 = gray to pure hue, default = 255.
brightnessBrightness/value (optional), 0-255 = off to max, default = 255. This is distinct and in combination with any configured global strip brightness.
gammifyIf true (default), apply gamma correction to colors for better appearance.

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