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, int16_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 (int16_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...

bool	canShow (void)
	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...

void	rainbow (uint16_t first_hue=0, int8_t reps=1, uint8_t saturation=255, uint8_t brightness=255, bool gammify=true)
	Fill NeoPixel 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	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...

static neoPixelType	str2order (const char *v)
	Convert pixel color order from string (e.g. "BGR") to NeoPixel color order constant (e.g. NEO_BGR). This may be helpful for code that initializes from text configuration rather than compile-time constants. More...

Protected Attributes
bool	is800KHz
	true if 800 KHz pixels

bool	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,
		int16_t	p = `6`,
		neoPixelType	t = `NEO_GRB + NEO_KHZ800`
	)

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

Parameters

n	Number of NeoPixels in strand.
p	Arduino pin number which will drive the NeoPixel data in.
t	Pixel 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 ( int16_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

p	Arduino 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

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.

◆ 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

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.
w	White 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

n	Pixel index, starting from 0.
c	32-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

c	32-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).
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_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

b	Brightness 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

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

t	Pixel 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()

bool Adafruit_NeoPixel::canShow ( void )

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

n	Index 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

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

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

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.

◆ 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

r	Red brightness, 0 to 255.
g	Green brightness, 0 to 255.
b	Blue brightness, 0 to 255.
w	White 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

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

x	32-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.

◆ rainbow()

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

Fill NeoPixel 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.

◆ str2order()

neoPixelType Adafruit_NeoPixel::str2order ( const char * v )

static

Convert pixel color order from string (e.g. "BGR") to NeoPixel color order constant (e.g. NEO_BGR). This may be helpful for code that initializes from text configuration rather than compile-time constants.

Parameters

v	Input string. Should be reasonably sanitized (a 3- or 4- character NUL-terminated string) or undefined behavior may result (output is still a valid NeoPixel order constant, but might not present as expected). Garbage in, garbage out.

Returns: One of the NeoPixel color order constants (e.g. NEO_BGR). NEO_KHZ400 or NEO_KHZ800 bits are not included, nor needed (all NeoPixels actually support 800 KHz it's been found, and this is the default state if no KHZ bits set).

Note: This function is declared static in the class so it can be called without a NeoPixel object (since it's not likely been declared in the code yet). Use Adafruit_NeoPixel::str2order().

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

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Adafruit_NeoPixel() [1/2]

◆ Adafruit_NeoPixel() [2/2]

Member Function Documentation

◆ show()

◆ setPin()

◆ setPixelColor() [1/3]

◆ setPixelColor() [2/3]

◆ setPixelColor() [3/3]

◆ fill()

◆ setBrightness()

◆ updateLength()

◆ updateType()

◆ canShow()

◆ getPixels()

◆ getBrightness()

◆ getPin()

◆ numPixels()

◆ getPixelColor()

◆ sine8()

◆ gamma8()

◆ Color() [1/2]

◆ Color() [2/2]

◆ ColorHSV()

◆ gamma32()

◆ rainbow()

◆ str2order()