Adafruit NeoPixel
Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
Adafruit_NeoPixel Class Reference

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

#include <Adafruit_NeoPixel.h>

Public Member Functions

 Adafruit_NeoPixel (uint16_t n, uint16_t pin=6, neoPixelType type=NEO_GRB+NEO_KHZ800)
 NeoPixel constructor when length, pin and pixel type are known at compile-time. More...
 
 Adafruit_NeoPixel (void)
 "Empty" NeoPixel constructor when length, pin and/or pixel type are not known at compile-time, and must be initialized later with updateType(), updateLength() and setPin(). More...
 
 ~Adafruit_NeoPixel ()
 Deallocate Adafruit_NeoPixel object, set data pin back to INPUT.
 
void begin (void)
 Configure NeoPixel pin for output.
 
void show (void)
 Transmit pixel data in RAM to NeoPixels. More...
 
void setPin (uint16_t p)
 Set/change the NeoPixel output pin number. Previous pin, if any, is set to INPUT and the new pin is set to OUTPUT. 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. If using RGBW pixels, white will be set to 0. More...
 
void setPixelColor (uint16_t n, uint8_t r, uint8_t g, uint8_t b, uint8_t w)
 Set a pixel's color using separate red, green, blue and white components (for RGBW NeoPixels only). More...
 
void setPixelColor (uint16_t n, uint32_t c)
 Set a pixel's color using a 32-bit 'packed' RGB or RGBW value. More...
 
void fill (uint32_t c=0, uint16_t first=0, uint16_t count=0)
 Fill all or part of the NeoPixel 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 (void)
 Fill the whole NeoPixel strip with 0 / black / off.
 
void updateLength (uint16_t n)
 Change the length of a previously-declared Adafruit_NeoPixel strip object. Old data is deallocated and new data is cleared. Pin number and pixel format are unchanged. More...
 
void updateType (neoPixelType t)
 Change the pixel format of a previously-declared Adafruit_NeoPixel strip object. If format changes from one of the RGB variants to an RGBW variant (or RGBW to RGB), the old data will be deallocated and new data is cleared. Otherwise, the old data will remain in RAM and is not reordered to the new format, so it's advisable to follow up with clear(). More...
 
boolean canShow (void) const
 Check whether a call to show() will start sending data immediately or will 'block' for a required interval. NeoPixels require a short quiet time (about 300 microseconds) after the last bit is received before the data 'latches' and new data can start being received. Usually one's sketch is implicitly using this time to generate a new frame of animation...but if it finishes very quickly, this function could be used to see if there's some idle time available for some low-priority concurrent task. More...
 
uint8_t * getPixels (void) const
 Get a pointer directly to the NeoPixel data buffer in RAM. Pixel data is stored in a device-native format (a la the NEO_* 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...
 
int16_t getPin (void) const
 Retrieve the pin number used for NeoPixel data output. More...
 
uint16_t numPixels (void) const
 Return the number of pixels in an Adafruit_NeoPixel strip object. More...
 
uint32_t getPixelColor (uint16_t n) const
 Query the color of a previously-set pixel. 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 Color (uint8_t r, uint8_t g, uint8_t b, uint8_t w)
 Convert separate red, green, blue and white values into a single "packed" 32-bit WRGB 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 or WRGB colors. Makes color transitions appear more perceptially correct. More...
 

Protected Attributes

boolean is800KHz
 true if 800 KHz pixels
 
boolean begun
 true if begin() previously called
 
uint16_t numLEDs
 Number of RGB LEDs in strip.
 
uint16_t numBytes
 Size of 'pixels' buffer below.
 
int16_t pin
 Output pin number (-1 if not yet set)
 
uint8_t brightness
 Strip brightness 0-255 (stored as +1)
 
uint8_t * pixels
 Holds LED color values (3 or 4 bytes each)
 
uint8_t rOffset
 Red index within each 3- or 4-byte pixel.
 
uint8_t gOffset
 Index of green byte.
 
uint8_t bOffset
 Index of blue byte.
 
uint8_t wOffset
 Index of white (==rOffset if no white)
 
uint32_t endTime
 Latch timing reference.
 

Detailed Description

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

Constructor & Destructor Documentation

◆ Adafruit_NeoPixel() [1/2]

Adafruit_NeoPixel::Adafruit_NeoPixel ( uint16_t  n,
uint16_t  p = 6,
neoPixelType  t = NEO_GRB + NEO_KHZ800 
)

NeoPixel constructor when length, pin and pixel type are known at compile-time.

Parameters
nNumber of NeoPixels in strand.
pArduino pin number which will drive the NeoPixel data in.
tPixel type – add together NEO_* constants defined in Adafruit_NeoPixel.h, for example NEO_GRB+NEO_KHZ800 for NeoPixels expecting an 800 KHz (vs 400 KHz) data stream with color bytes expressed in green, red, blue order per pixel.
Returns
Adafruit_NeoPixel object. Call the begin() function before use.

◆ Adafruit_NeoPixel() [2/2]

Adafruit_NeoPixel::Adafruit_NeoPixel ( void  )

"Empty" NeoPixel constructor when length, pin and/or pixel type are not known at compile-time, and must be initialized later with updateType(), updateLength() and setPin().

Returns
Adafruit_NeoPixel object. Call the begin() function before use.
Note
This function is deprecated, here only for old projects that may still be calling it. New projects should instead use the 'new' keyword with the first constructor syntax (length, pin, type).

Member Function Documentation

◆ show()

void Adafruit_NeoPixel::show ( void  )

Transmit pixel data in RAM to NeoPixels.

Note
On most architectures, interrupts are temporarily disabled in order to achieve the correct NeoPixel signal timing. This means that the Arduino millis() and micros() functions, which require interrupts, will lose small intervals of time whenever this function is called (about 30 microseconds per RGB pixel, 40 for RGBW pixels). There's no easy fix for this, but a few specialized alternative or companion libraries exist that use very device-specific peripherals to work around it.

◆ setPin()

void Adafruit_NeoPixel::setPin ( uint16_t  p)

Set/change the NeoPixel output pin number. Previous pin, if any, is set to INPUT and the new pin is set to OUTPUT.

Parameters
pArduino pin number (-1 = no pin).

◆ setPixelColor() [1/3]

void Adafruit_NeoPixel::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. If using RGBW pixels, white will be set to 0.

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.

◆ setPixelColor() [2/3]

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

Set a pixel's color using separate red, green, blue and white components (for RGBW NeoPixels only).

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.
wWhite brightness, 0 = minimum (off), 255 = maximum, ignored if using RGB pixels.

◆ setPixelColor() [3/3]

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

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

Parameters
nPixel index, starting from 0.
c32-bit color value. Most significant byte is white (for RGBW pixels) or ignored (for RGB pixels), next is red, then green, and least significant byte is blue.

◆ fill()

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

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

Parameters
c32-bit color value. Most significant byte is white (for RGBW pixels) or ignored (for RGB pixels), next is red, then green, and least significant byte is blue. 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_NeoPixel::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
This was intended for one-time use in one's setup() function, not as an animation effect in itself. Because of the way this library "pre-multiplies" LED colors in RAM, changing the brightness is often a "lossy" operation – what you write to pixels isn't necessary the same as what you'll read back. Repeated brightness changes using this function exacerbate the problem. Smart programs therefore treat the strip as a write-only resource, maintaining their own state to render each frame of an animation, not relying on read-modify-write.

◆ updateLength()

void Adafruit_NeoPixel::updateLength ( uint16_t  n)

Change the length of a previously-declared Adafruit_NeoPixel strip object. Old data is deallocated and new data is cleared. Pin number 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 with the first constructor syntax (length, pin, type).

◆ updateType()

void Adafruit_NeoPixel::updateType ( neoPixelType  t)

Change the pixel format of a previously-declared Adafruit_NeoPixel strip object. If format changes from one of the RGB variants to an RGBW variant (or RGBW to RGB), the old data will be deallocated and new data is cleared. Otherwise, the old data will remain in RAM and is not reordered to the new format, so it's advisable to follow up with clear().

Parameters
tPixel type – add together NEO_* constants defined in Adafruit_NeoPixel.h, for example NEO_GRB+NEO_KHZ800 for NeoPixels expecting an 800 KHz (vs 400 KHz) data stream with color bytes expressed in green, red, blue order per pixel.
Note
This function is deprecated, here only for old projects that may still be calling it. New projects should instead use the 'new' keyword with the first constructor syntax (length, pin, type).

◆ canShow()

boolean Adafruit_NeoPixel::canShow ( void  ) const
inline

Check whether a call to show() will start sending data immediately or will 'block' for a required interval. NeoPixels require a short quiet time (about 300 microseconds) after the last bit is received before the data 'latches' and new data can start being received. Usually one's sketch is implicitly using this time to generate a new frame of animation...but if it finishes very quickly, this function could be used to see if there's some idle time available for some low-priority concurrent task.

Returns
1 or true if show() will start sending immediately, 0 or false if show() would block (meaning some idle time is available).

◆ getPixels()

uint8_t* Adafruit_NeoPixel::getPixels ( void  ) const
inline

Get a pointer directly to the NeoPixel data buffer in RAM. Pixel data is stored in a device-native format (a la the NEO_* 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 NeoPixel 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_NeoPixel::getBrightness ( void  ) const

Retrieve the last-set brightness value for the strip.

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

◆ getPin()

int16_t Adafruit_NeoPixel::getPin ( void  ) const
inline

Retrieve the pin number used for NeoPixel data output.

Returns
Arduino pin number (-1 if not set).

◆ numPixels()

uint16_t Adafruit_NeoPixel::numPixels ( void  ) const
inline

Return the number of pixels in an Adafruit_NeoPixel strip object.

Returns
Pixel count (0 if not set).

◆ getPixelColor()

uint32_t Adafruit_NeoPixel::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 or WRGB value. Most significant byte is white (for RGBW pixels) or 0 (for RGB pixels), next is red, then green, and least significant byte is blue.
Note
If the strip brightness has been changed from the default value of 255, the color read from a pixel may not exactly match what was previously written with one of the setPixelColor() functions. This gets more pronounced at lower brightness levels.

◆ sine8()

static uint8_t Adafruit_NeoPixel::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_NeoPixel::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 NeoPixels in average tasks. If you need finer control you'll need to provide your own gamma-correction function instead.

◆ Color() [1/2]

static uint32_t Adafruit_NeoPixel::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.

◆ Color() [2/2]

static uint32_t Adafruit_NeoPixel::Color ( uint8_t  r,
uint8_t  g,
uint8_t  b,
uint8_t  w 
)
inlinestatic

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

Parameters
rRed brightness, 0 to 255.
gGreen brightness, 0 to 255.
bBlue brightness, 0 to 255.
wWhite brightness, 0 to 255.
Returns
32-bit packed WRGB value, which can then be assigned to a variable for later use or passed to the setPixelColor() function. Packed WRGB format is predictable, regardless of LED strand color order.

◆ ColorHSV()

uint32_t Adafruit_NeoPixel::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 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 with the most significant byte set to 0 – the white element of WRGB pixels is NOT utilized. 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_NeoPixel::gamma32 ( uint32_t  x)
static

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

Parameters
x32-bit packed RGB or WRGB 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 NeoPixels in average tasks. If you need finer control you'll need to provide your own gamma-correction function instead.

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