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

#include <Adafruit_CPlay_NeoPixel.h>

Public Member Functions
	Adafruit_CPlay_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_CPlay_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_CPlay_NeoPixel ()
	Deallocate Adafruit_CPlay_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_CPlay_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_CPlay_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_CPlay_NeoPixel() [1/2]

Adafruit_CPlay_NeoPixel::Adafruit_CPlay_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.

Arduino Library for driving Adafruit NeoPixel addressable LEDs, FLORA RGB Smart Pixels and compatible devicess – WS2811, WS2812, WS2812B, SK6812, etc.

This is the documentation for Adafruit's NeoPixel library for the Arduino platform, allowing a broad range of microcontroller boards (most AVR boards, many ARM devices, ESP8266 and ESP32, among others) to control Adafruit NeoPixels, FLORA RGB Smart Pixels and compatible devices – WS2811, WS2812, WS2812B, SK6812, etc.

Adafruit invests time and resources providing this open source code, please support Adafruit and open-source hardware by purchasing products from Adafruit!

Written by Phil "Paint Your Dragon" Burgess for Adafruit Industries, with contributions by PJRC, Michael Miller and other members of the open source community. This file is part of the Adafruit_NeoPixel library.

Adafruit_NeoPixel is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Adafruit_NeoPixel is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with NeoPixel. If not, see http://www.gnu.org/licenses/.

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

◆ Adafruit_CPlay_NeoPixel() [2/2]

Adafruit_CPlay_NeoPixel::Adafruit_CPlay_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().

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

p	Arduino pin number (-1 = no pin).

◆ setPixelColor() [1/3]

void Adafruit_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_NeoPixel::updateLength ( uint16_t n )

Change the length of a previously-declared Adafruit_CPlay_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_CPlay_NeoPixel::updateType ( neoPixelType t )

Change the pixel format of a previously-declared Adafruit_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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_CPlay_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.

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

utility/Adafruit_CPlay_NeoPixel.h
utility/Adafruit_CPlay_NeoPixel.cpp

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Adafruit_CPlay_NeoPixel() [1/2]

◆ Adafruit_CPlay_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()