Adafruit NeoPixel Library
Adafruit_NeoPixel.h
Go to the documentation of this file.
1 
36 #ifndef ADAFRUIT_NEOPIXEL_H
37 #define ADAFRUIT_NEOPIXEL_H
38 
39 #ifdef ARDUINO
40 #if (ARDUINO >= 100)
41 #include <Arduino.h>
42 #else
43 #include <WProgram.h>
44 #include <pins_arduino.h>
45 #endif
46 
47 #ifdef USE_TINYUSB // For Serial when selecting TinyUSB
48 #include <Adafruit_TinyUSB.h>
49 #endif
50 
51 #endif
52 
53 #ifdef TARGET_LPC1768
54 #include <Arduino.h>
55 #endif
56 
57 #if defined(ARDUINO_ARCH_RP2040)
58 #include <stdlib.h>
59 #include "hardware/pio.h"
60 #include "hardware/clocks.h"
61 #include "rp2040_pio.h"
62 #endif
63 
64 // The order of primary colors in the NeoPixel data stream can vary among
65 // device types, manufacturers and even different revisions of the same
66 // item. The third parameter to the Adafruit_NeoPixel constructor encodes
67 // the per-pixel byte offsets of the red, green and blue primaries (plus
68 // white, if present) in the data stream -- the following #defines provide
69 // an easier-to-use named version for each permutation. e.g. NEO_GRB
70 // indicates a NeoPixel-compatible device expecting three bytes per pixel,
71 // with the first byte transmitted containing the green value, second
72 // containing red and third containing blue. The in-memory representation
73 // of a chain of NeoPixels is the same as the data-stream order; no
74 // re-ordering of bytes is required when issuing data to the chain.
75 // Most of these values won't exist in real-world devices, but it's done
76 // this way so we're ready for it (also, if using the WS2811 driver IC,
77 // one might have their pixels set up in any weird permutation).
78 
79 // Bits 5,4 of this value are the offset (0-3) from the first byte of a
80 // pixel to the location of the red color byte. Bits 3,2 are the green
81 // offset and 1,0 are the blue offset. If it is an RGBW-type device
82 // (supporting a white primary in addition to R,G,B), bits 7,6 are the
83 // offset to the white byte...otherwise, bits 7,6 are set to the same value
84 // as 5,4 (red) to indicate an RGB (not RGBW) device.
85 // i.e. binary representation:
86 // 0bWWRRGGBB for RGBW devices
87 // 0bRRRRGGBB for RGB
88 
89 // RGB NeoPixel permutations; white and red offsets are always same
90 // Offset: W R G B
91 #define NEO_RGB ((0 << 6) | (0 << 4) | (1 << 2) | (2))
92 #define NEO_RBG ((0 << 6) | (0 << 4) | (2 << 2) | (1))
93 #define NEO_GRB ((1 << 6) | (1 << 4) | (0 << 2) | (2))
94 #define NEO_GBR ((2 << 6) | (2 << 4) | (0 << 2) | (1))
95 #define NEO_BRG ((1 << 6) | (1 << 4) | (2 << 2) | (0))
96 #define NEO_BGR ((2 << 6) | (2 << 4) | (1 << 2) | (0))
97 
98 // RGBW NeoPixel permutations; all 4 offsets are distinct
99 // Offset: W R G B
100 #define NEO_WRGB ((0 << 6) | (1 << 4) | (2 << 2) | (3))
101 #define NEO_WRBG ((0 << 6) | (1 << 4) | (3 << 2) | (2))
102 #define NEO_WGRB ((0 << 6) | (2 << 4) | (1 << 2) | (3))
103 #define NEO_WGBR ((0 << 6) | (3 << 4) | (1 << 2) | (2))
104 #define NEO_WBRG ((0 << 6) | (2 << 4) | (3 << 2) | (1))
105 #define NEO_WBGR ((0 << 6) | (3 << 4) | (2 << 2) | (1))
106 
107 #define NEO_RWGB ((1 << 6) | (0 << 4) | (2 << 2) | (3))
108 #define NEO_RWBG ((1 << 6) | (0 << 4) | (3 << 2) | (2))
109 #define NEO_RGWB ((2 << 6) | (0 << 4) | (1 << 2) | (3))
110 #define NEO_RGBW ((3 << 6) | (0 << 4) | (1 << 2) | (2))
111 #define NEO_RBWG ((2 << 6) | (0 << 4) | (3 << 2) | (1))
112 #define NEO_RBGW ((3 << 6) | (0 << 4) | (2 << 2) | (1))
113 
114 #define NEO_GWRB ((1 << 6) | (2 << 4) | (0 << 2) | (3))
115 #define NEO_GWBR ((1 << 6) | (3 << 4) | (0 << 2) | (2))
116 #define NEO_GRWB ((2 << 6) | (1 << 4) | (0 << 2) | (3))
117 #define NEO_GRBW ((3 << 6) | (1 << 4) | (0 << 2) | (2))
118 #define NEO_GBWR ((2 << 6) | (3 << 4) | (0 << 2) | (1))
119 #define NEO_GBRW ((3 << 6) | (2 << 4) | (0 << 2) | (1))
120 
121 #define NEO_BWRG ((1 << 6) | (2 << 4) | (3 << 2) | (0))
122 #define NEO_BWGR ((1 << 6) | (3 << 4) | (2 << 2) | (0))
123 #define NEO_BRWG ((2 << 6) | (1 << 4) | (3 << 2) | (0))
124 #define NEO_BRGW ((3 << 6) | (1 << 4) | (2 << 2) | (0))
125 #define NEO_BGWR ((2 << 6) | (3 << 4) | (1 << 2) | (0))
126 #define NEO_BGRW ((3 << 6) | (2 << 4) | (1 << 2) | (0))
127 
128 // Add NEO_KHZ400 to the color order value to indicate a 400 KHz device.
129 // All but the earliest v1 NeoPixels expect an 800 KHz data stream, this is
130 // the default if unspecified. Because flash space is very limited on ATtiny
131 // devices (e.g. Trinket, Gemma), v1 NeoPixels aren't handled by default on
132 // those chips, though it can be enabled by removing the ifndef/endif below,
133 // but code will be bigger. Conversely, can disable the NEO_KHZ400 line on
134 // other MCUs to remove v1 support and save a little space.
135 
136 #define NEO_KHZ800 0x0000
137 #ifndef __AVR_ATtiny85__
138 #define NEO_KHZ400 0x0100
139 #endif
140 
141 // If 400 KHz support is enabled, the third parameter to the constructor
142 // requires a 16-bit value (in order to select 400 vs 800 KHz speed).
143 // If only 800 KHz is enabled (as is default on ATtiny), an 8-bit value
144 // is sufficient to encode pixel color order, saving some space.
145 
146 #ifdef NEO_KHZ400
147 typedef uint16_t neoPixelType;
148 #else
149 typedef uint8_t neoPixelType;
150 #endif
151 
152 // These two tables are declared outside the Adafruit_NeoPixel class
153 // because some boards may require oldschool compilers that don't
154 // handle the C++11 constexpr keyword.
155 
156 /* A PROGMEM (flash mem) table containing 8-bit unsigned sine wave (0-255).
157  Copy & paste this snippet into a Python REPL to regenerate:
158 import math
159 for x in range(256):
160  print("{:3},".format(int((math.sin(x/128.0*math.pi)+1.0)*127.5+0.5))),
161  if x&15 == 15: print
162 */
163 static const uint8_t PROGMEM _NeoPixelSineTable[256] = {
164  128, 131, 134, 137, 140, 143, 146, 149, 152, 155, 158, 162, 165, 167, 170,
165  173, 176, 179, 182, 185, 188, 190, 193, 196, 198, 201, 203, 206, 208, 211,
166  213, 215, 218, 220, 222, 224, 226, 228, 230, 232, 234, 235, 237, 238, 240,
167  241, 243, 244, 245, 246, 248, 249, 250, 250, 251, 252, 253, 253, 254, 254,
168  254, 255, 255, 255, 255, 255, 255, 255, 254, 254, 254, 253, 253, 252, 251,
169  250, 250, 249, 248, 246, 245, 244, 243, 241, 240, 238, 237, 235, 234, 232,
170  230, 228, 226, 224, 222, 220, 218, 215, 213, 211, 208, 206, 203, 201, 198,
171  196, 193, 190, 188, 185, 182, 179, 176, 173, 170, 167, 165, 162, 158, 155,
172  152, 149, 146, 143, 140, 137, 134, 131, 128, 124, 121, 118, 115, 112, 109,
173  106, 103, 100, 97, 93, 90, 88, 85, 82, 79, 76, 73, 70, 67, 65,
174  62, 59, 57, 54, 52, 49, 47, 44, 42, 40, 37, 35, 33, 31, 29,
175  27, 25, 23, 21, 20, 18, 17, 15, 14, 12, 11, 10, 9, 7, 6,
176  5, 5, 4, 3, 2, 2, 1, 1, 1, 0, 0, 0, 0, 0, 0,
177  0, 1, 1, 1, 2, 2, 3, 4, 5, 5, 6, 7, 9, 10, 11,
178  12, 14, 15, 17, 18, 20, 21, 23, 25, 27, 29, 31, 33, 35, 37,
179  40, 42, 44, 47, 49, 52, 54, 57, 59, 62, 65, 67, 70, 73, 76,
180  79, 82, 85, 88, 90, 93, 97, 100, 103, 106, 109, 112, 115, 118, 121,
181  124};
182 
183 /* Similar to above, but for an 8-bit gamma-correction table.
184  Copy & paste this snippet into a Python REPL to regenerate:
185 import math
186 gamma=2.6
187 for x in range(256):
188  print("{:3},".format(int(math.pow((x)/255.0,gamma)*255.0+0.5))),
189  if x&15 == 15: print
190 */
191 static const uint8_t PROGMEM _NeoPixelGammaTable[256] = {
192  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
193  0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1,
194  1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3,
195  3, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 5, 6,
196  6, 6, 6, 7, 7, 7, 8, 8, 8, 9, 9, 9, 10, 10, 10,
197  11, 11, 11, 12, 12, 13, 13, 13, 14, 14, 15, 15, 16, 16, 17,
198  17, 18, 18, 19, 19, 20, 20, 21, 21, 22, 22, 23, 24, 24, 25,
199  25, 26, 27, 27, 28, 29, 29, 30, 31, 31, 32, 33, 34, 34, 35,
200  36, 37, 38, 38, 39, 40, 41, 42, 42, 43, 44, 45, 46, 47, 48,
201  49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63,
202  64, 65, 66, 68, 69, 70, 71, 72, 73, 75, 76, 77, 78, 80, 81,
203  82, 84, 85, 86, 88, 89, 90, 92, 93, 94, 96, 97, 99, 100, 102,
204  103, 105, 106, 108, 109, 111, 112, 114, 115, 117, 119, 120, 122, 124, 125,
205  127, 129, 130, 132, 134, 136, 137, 139, 141, 143, 145, 146, 148, 150, 152,
206  154, 156, 158, 160, 162, 164, 166, 168, 170, 172, 174, 176, 178, 180, 182,
207  184, 186, 188, 191, 193, 195, 197, 199, 202, 204, 206, 209, 211, 213, 215,
208  218, 220, 223, 225, 227, 230, 232, 235, 237, 240, 242, 245, 247, 250, 252,
209  255};
210 
216 
217 public:
218  // Constructor: number of LEDs, pin number, LED type
219  Adafruit_NeoPixel(uint16_t n, int16_t pin = 6,
220  neoPixelType type = NEO_GRB + NEO_KHZ800);
221  Adafruit_NeoPixel(void);
223 
224  void begin(void);
225  void show(void);
226  void setPin(int16_t p);
227  void setPixelColor(uint16_t n, uint8_t r, uint8_t g, uint8_t b);
228  void setPixelColor(uint16_t n, uint8_t r, uint8_t g, uint8_t b, uint8_t w);
229  void setPixelColor(uint16_t n, uint32_t c);
230  void fill(uint32_t c = 0, uint16_t first = 0, uint16_t count = 0);
231  void setBrightness(uint8_t);
232  void clear(void);
233  void updateLength(uint16_t n);
234  void updateType(neoPixelType t);
248  bool canShow(void) {
249  // It's normal and possible for endTime to exceed micros() if the
250  // 32-bit clock counter has rolled over (about every 70 minutes).
251  // Since both are uint32_t, a negative delta correctly maps back to
252  // positive space, and it would seem like the subtraction below would
253  // suffice. But a problem arises if code invokes show() very
254  // infrequently...the micros() counter may roll over MULTIPLE times in
255  // that interval, the delta calculation is no longer correct and the
256  // next update may stall for a very long time. The check below resets
257  // the latch counter if a rollover has occurred. This can cause an
258  // extra delay of up to 300 microseconds in the rare case where a
259  // show() call happens precisely around the rollover, but that's
260  // neither likely nor especially harmful, vs. other code that might
261  // stall for 30+ minutes, or having to document and frequently remind
262  // and/or provide tech support explaining an unintuitive need for
263  // show() calls at least once an hour.
264  uint32_t now = micros();
265  if (endTime > now) {
266  endTime = now;
267  }
268  return (now - endTime) >= 300L;
269  }
284  uint8_t *getPixels(void) const { return pixels; };
285  uint8_t getBrightness(void) const;
290  int16_t getPin(void) const { return pin; };
295  uint16_t numPixels(void) const { return numLEDs; }
296  uint32_t getPixelColor(uint16_t n) const;
309  static uint8_t sine8(uint8_t x) {
310  return pgm_read_byte(&_NeoPixelSineTable[x]); // 0-255 in, 0-255 out
311  }
323  static uint8_t gamma8(uint8_t x) {
324  return pgm_read_byte(&_NeoPixelGammaTable[x]); // 0-255 in, 0-255 out
325  }
337  static uint32_t Color(uint8_t r, uint8_t g, uint8_t b) {
338  return ((uint32_t)r << 16) | ((uint32_t)g << 8) | b;
339  }
352  static uint32_t Color(uint8_t r, uint8_t g, uint8_t b, uint8_t w) {
353  return ((uint32_t)w << 24) | ((uint32_t)r << 16) | ((uint32_t)g << 8) | b;
354  }
355  static uint32_t ColorHSV(uint16_t hue, uint8_t sat = 255, uint8_t val = 255);
368  static uint32_t gamma32(uint32_t x);
369 
370  void rainbow(uint16_t first_hue = 0, int8_t reps = 1,
371  uint8_t saturation = 255, uint8_t brightness = 255,
372  bool gammify = true);
373 
374 private:
375 #if defined(ARDUINO_ARCH_RP2040)
376  void rp2040Init(uint8_t pin, bool is800KHz);
377  void rp2040Show(uint8_t pin, uint8_t *pixels, uint32_t numBytes, bool is800KHz);
378 #endif
379 
380 protected:
381 #ifdef NEO_KHZ400 // If 400 KHz NeoPixel support enabled...
382  bool is800KHz;
383 #endif
384  bool begun;
385  uint16_t numLEDs;
386  uint16_t numBytes;
387  int16_t pin;
388  uint8_t brightness;
389  uint8_t *pixels;
390  uint8_t rOffset;
391  uint8_t gOffset;
392  uint8_t bOffset;
393  uint8_t wOffset;
394  uint32_t endTime;
395 #ifdef __AVR__
396  volatile uint8_t *port;
397  uint8_t pinMask;
398 #endif
399 #if defined(ARDUINO_ARCH_STM32) || defined(ARDUINO_ARCH_ARDUINO_CORE_STM32)
400  GPIO_TypeDef *gpioPort;
401  uint32_t gpioPin;
402 #endif
403 #if defined(ARDUINO_ARCH_RP2040)
404  PIO pio = pio0;
405  int sm = 0;
406  bool init = true;
407 #endif
408 };
409 
410 #endif // ADAFRUIT_NEOPIXEL_H
#define NEO_GRB
Transmit as G,R,B.
Definition: Adafruit_NeoPixel.h:93
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.
Definition: Adafruit_NeoPixel.cpp:3165
uint16_t numBytes
Size of &#39;pixels&#39; buffer below.
Definition: Adafruit_NeoPixel.h:386
uint16_t numLEDs
Number of RGB LEDs in strip.
Definition: Adafruit_NeoPixel.h:385
void updateLength(uint16_t n)
Change the length of a previously-declared Adafruit_NeoPixel strip object. Old data is deallocated an...
Definition: Adafruit_NeoPixel.cpp:146
Class that stores state and functions for interacting with Adafruit NeoPixels and compatible devices...
Definition: Adafruit_NeoPixel.h:215
uint8_t gOffset
Index of green byte.
Definition: Adafruit_NeoPixel.h:391
int16_t pin
Output pin number (-1 if not yet set)
Definition: Adafruit_NeoPixel.h:387
int16_t getPin(void) const
Retrieve the pin number used for NeoPixel data output.
Definition: Adafruit_NeoPixel.h:290
uint8_t brightness
Strip brightness 0-255 (stored as +1)
Definition: Adafruit_NeoPixel.h:388
uint16_t neoPixelType
3rd arg to Adafruit_NeoPixel constructor
Definition: Adafruit_NeoPixel.h:147
void show(void)
Transmit pixel data in RAM to NeoPixels.
Definition: Adafruit_NeoPixel.cpp:258
uint32_t endTime
Latch timing reference.
Definition: Adafruit_NeoPixel.h:394
bool is800KHz
true if 800 KHz pixels
Definition: Adafruit_NeoPixel.h:382
void setPixelColor(uint16_t n, uint8_t r, uint8_t g, uint8_t b)
Set a pixel&#39;s color using separate red, green and blue components. If using RGBW pixels, white will be set to 0.
Definition: Adafruit_NeoPixel.cpp:3071
bool begun
true if begin() previously called
Definition: Adafruit_NeoPixel.h:384
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 s...
Definition: Adafruit_NeoPixel.cpp:3045
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...
Definition: Adafruit_NeoPixel.cpp:3431
uint8_t bOffset
Index of blue byte.
Definition: Adafruit_NeoPixel.h:392
uint8_t wOffset
Index of white (==rOffset if no white)
Definition: Adafruit_NeoPixel.h:393
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...
Definition: Adafruit_NeoPixel.h:352
static uint32_t gamma32(uint32_t x)
A gamma-correction function for 32-bit packed RGB or WRGB colors. Makes color transitions appear more...
Definition: Adafruit_NeoPixel.cpp:3398
void clear(void)
Fill the whole NeoPixel strip with 0 / black / off.
Definition: Adafruit_NeoPixel.cpp:3394
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(...
Definition: Adafruit_NeoPixel.cpp:3211
uint8_t * pixels
Holds LED color values (3 or 4 bytes each)
Definition: Adafruit_NeoPixel.h:389
uint32_t getPixelColor(uint16_t n) const
Query the color of a previously-set pixel.
Definition: Adafruit_NeoPixel.cpp:3298
void updateType(neoPixelType t)
Change the pixel format of a previously-declared Adafruit_NeoPixel strip object. If format changes fr...
Definition: Adafruit_NeoPixel.cpp:176
void begin(void)
Configure NeoPixel pin for output.
Definition: Adafruit_NeoPixel.cpp:128
uint8_t * getPixels(void) const
Get a pointer directly to the NeoPixel data buffer in RAM. Pixel data is stored in a device-native fo...
Definition: Adafruit_NeoPixel.h:284
uint16_t numPixels(void) const
Return the number of pixels in an Adafruit_NeoPixel strip object.
Definition: Adafruit_NeoPixel.h:295
uint8_t rOffset
Red index within each 3- or 4-byte pixel.
Definition: Adafruit_NeoPixel.h:390
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.
Definition: Adafruit_NeoPixel.h:337
bool canShow(void)
Check whether a call to show() will start sending data immediately or will &#39;block&#39; for a required int...
Definition: Adafruit_NeoPixel.h:248
void setBrightness(uint8_t)
Adjust output brightness. Does not immediately affect what&#39;s currently displayed on the LEDs...
Definition: Adafruit_NeoPixel.cpp:3349
static uint8_t sine8(uint8_t x)
An 8-bit integer sine wave function, not directly compatible with standard trigonometric units like r...
Definition: Adafruit_NeoPixel.h:309
static uint8_t gamma8(uint8_t x)
An 8-bit gamma-correction function for basic pixel brightness adjustment. Makes color transitions app...
Definition: Adafruit_NeoPixel.h:323
~Adafruit_NeoPixel()
Deallocate Adafruit_NeoPixel object, set data pin back to INPUT.
Definition: Adafruit_NeoPixel.cpp:119
#define NEO_KHZ800
800 KHz data transmission
Definition: Adafruit_NeoPixel.h:136
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().
Definition: Adafruit_NeoPixel.cpp:107
uint8_t getBrightness(void) const
Retrieve the last-set brightness value for the strip.
Definition: Adafruit_NeoPixel.cpp:3389