Adafruit_NeoPixel.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361
  1. /*!
  2. * @file Adafruit_NeoPixel.h
  3. *
  4. * This is part of Adafruit's NeoPixel library for the Arduino platform,
  5. * allowing a broad range of microcontroller boards (most AVR boards,
  6. * many ARM devices, ESP8266 and ESP32, among others) to control Adafruit
  7. * NeoPixels, FLORA RGB Smart Pixels and compatible devices -- WS2811,
  8. * WS2812, WS2812B, SK6812, etc.
  9. *
  10. * Adafruit invests time and resources providing this open source code,
  11. * please support Adafruit and open-source hardware by purchasing products
  12. * from Adafruit!
  13. *
  14. * Written by Phil "Paint Your Dragon" Burgess for Adafruit Industries,
  15. * with contributions by PJRC, Michael Miller and other members of the
  16. * open source community.
  17. *
  18. * This file is part of the Adafruit_NeoPixel library.
  19. *
  20. * Adafruit_NeoPixel is free software: you can redistribute it and/or
  21. * modify it under the terms of the GNU Lesser General Public License as
  22. * published by the Free Software Foundation, either version 3 of the
  23. * License, or (at your option) any later version.
  24. *
  25. * Adafruit_NeoPixel is distributed in the hope that it will be useful,
  26. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  27. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  28. * GNU Lesser General Public License for more details.
  29. *
  30. * You should have received a copy of the GNU Lesser General Public
  31. * License along with NeoPixel. If not, see
  32. * <http://www.gnu.org/licenses/>.
  33. *
  34. */
  35. #ifndef ADAFRUIT_NEOPIXEL_H
  36. #define ADAFRUIT_NEOPIXEL_H
  37. #ifdef ARDUINO
  38. #if (ARDUINO >= 100)
  39. #include <Arduino.h>
  40. #else
  41. #include <WProgram.h>
  42. #include <pins_arduino.h>
  43. #endif
  44. #endif
  45. #ifdef TARGET_LPC1768
  46. #include <Arduino.h>
  47. #endif
  48. // The order of primary colors in the NeoPixel data stream can vary among
  49. // device types, manufacturers and even different revisions of the same
  50. // item. The third parameter to the Adafruit_NeoPixel constructor encodes
  51. // the per-pixel byte offsets of the red, green and blue primaries (plus
  52. // white, if present) in the data stream -- the following #defines provide
  53. // an easier-to-use named version for each permutation. e.g. NEO_GRB
  54. // indicates a NeoPixel-compatible device expecting three bytes per pixel,
  55. // with the first byte transmitted containing the green value, second
  56. // containing red and third containing blue. The in-memory representation
  57. // of a chain of NeoPixels is the same as the data-stream order; no
  58. // re-ordering of bytes is required when issuing data to the chain.
  59. // Most of these values won't exist in real-world devices, but it's done
  60. // this way so we're ready for it (also, if using the WS2811 driver IC,
  61. // one might have their pixels set up in any weird permutation).
  62. // Bits 5,4 of this value are the offset (0-3) from the first byte of a
  63. // pixel to the location of the red color byte. Bits 3,2 are the green
  64. // offset and 1,0 are the blue offset. If it is an RGBW-type device
  65. // (supporting a white primary in addition to R,G,B), bits 7,6 are the
  66. // offset to the white byte...otherwise, bits 7,6 are set to the same value
  67. // as 5,4 (red) to indicate an RGB (not RGBW) device.
  68. // i.e. binary representation:
  69. // 0bWWRRGGBB for RGBW devices
  70. // 0bRRRRGGBB for RGB
  71. // RGB NeoPixel permutations; white and red offsets are always same
  72. // Offset: W R G B
  73. #define NEO_RGB ((0<<6) | (0<<4) | (1<<2) | (2)) ///< Transmit as R,G,B
  74. #define NEO_RBG ((0<<6) | (0<<4) | (2<<2) | (1)) ///< Transmit as R,B,G
  75. #define NEO_GRB ((1<<6) | (1<<4) | (0<<2) | (2)) ///< Transmit as G,R,B
  76. #define NEO_GBR ((2<<6) | (2<<4) | (0<<2) | (1)) ///< Transmit as G,B,R
  77. #define NEO_BRG ((1<<6) | (1<<4) | (2<<2) | (0)) ///< Transmit as B,R,G
  78. #define NEO_BGR ((2<<6) | (2<<4) | (1<<2) | (0)) ///< Transmit as B,G,R
  79. // RGBW NeoPixel permutations; all 4 offsets are distinct
  80. // Offset: W R G B
  81. #define NEO_WRGB ((0<<6) | (1<<4) | (2<<2) | (3)) ///< Transmit as W,R,G,B
  82. #define NEO_WRBG ((0<<6) | (1<<4) | (3<<2) | (2)) ///< Transmit as W,R,B,G
  83. #define NEO_WGRB ((0<<6) | (2<<4) | (1<<2) | (3)) ///< Transmit as W,G,R,B
  84. #define NEO_WGBR ((0<<6) | (3<<4) | (1<<2) | (2)) ///< Transmit as W,G,B,R
  85. #define NEO_WBRG ((0<<6) | (2<<4) | (3<<2) | (1)) ///< Transmit as W,B,R,G
  86. #define NEO_WBGR ((0<<6) | (3<<4) | (2<<2) | (1)) ///< Transmit as W,B,G,R
  87. #define NEO_RWGB ((1<<6) | (0<<4) | (2<<2) | (3)) ///< Transmit as R,W,G,B
  88. #define NEO_RWBG ((1<<6) | (0<<4) | (3<<2) | (2)) ///< Transmit as R,W,B,G
  89. #define NEO_RGWB ((2<<6) | (0<<4) | (1<<2) | (3)) ///< Transmit as R,G,W,B
  90. #define NEO_RGBW ((3<<6) | (0<<4) | (1<<2) | (2)) ///< Transmit as R,G,B,W
  91. #define NEO_RBWG ((2<<6) | (0<<4) | (3<<2) | (1)) ///< Transmit as R,B,W,G
  92. #define NEO_RBGW ((3<<6) | (0<<4) | (2<<2) | (1)) ///< Transmit as R,B,G,W
  93. #define NEO_GWRB ((1<<6) | (2<<4) | (0<<2) | (3)) ///< Transmit as G,W,R,B
  94. #define NEO_GWBR ((1<<6) | (3<<4) | (0<<2) | (2)) ///< Transmit as G,W,B,R
  95. #define NEO_GRWB ((2<<6) | (1<<4) | (0<<2) | (3)) ///< Transmit as G,R,W,B
  96. #define NEO_GRBW ((3<<6) | (1<<4) | (0<<2) | (2)) ///< Transmit as G,R,B,W
  97. #define NEO_GBWR ((2<<6) | (3<<4) | (0<<2) | (1)) ///< Transmit as G,B,W,R
  98. #define NEO_GBRW ((3<<6) | (2<<4) | (0<<2) | (1)) ///< Transmit as G,B,R,W
  99. #define NEO_BWRG ((1<<6) | (2<<4) | (3<<2) | (0)) ///< Transmit as B,W,R,G
  100. #define NEO_BWGR ((1<<6) | (3<<4) | (2<<2) | (0)) ///< Transmit as B,W,G,R
  101. #define NEO_BRWG ((2<<6) | (1<<4) | (3<<2) | (0)) ///< Transmit as B,R,W,G
  102. #define NEO_BRGW ((3<<6) | (1<<4) | (2<<2) | (0)) ///< Transmit as B,R,G,W
  103. #define NEO_BGWR ((2<<6) | (3<<4) | (1<<2) | (0)) ///< Transmit as B,G,W,R
  104. #define NEO_BGRW ((3<<6) | (2<<4) | (1<<2) | (0)) ///< Transmit as B,G,R,W
  105. // Add NEO_KHZ400 to the color order value to indicate a 400 KHz device.
  106. // All but the earliest v1 NeoPixels expect an 800 KHz data stream, this is
  107. // the default if unspecified. Because flash space is very limited on ATtiny
  108. // devices (e.g. Trinket, Gemma), v1 NeoPixels aren't handled by default on
  109. // those chips, though it can be enabled by removing the ifndef/endif below,
  110. // but code will be bigger. Conversely, can disable the NEO_KHZ400 line on
  111. // other MCUs to remove v1 support and save a little space.
  112. #define NEO_KHZ800 0x0000 ///< 800 KHz data transmission
  113. #ifndef __AVR_ATtiny85__
  114. #define NEO_KHZ400 0x0100 ///< 400 KHz data transmission
  115. #endif
  116. // If 400 KHz support is enabled, the third parameter to the constructor
  117. // requires a 16-bit value (in order to select 400 vs 800 KHz speed).
  118. // If only 800 KHz is enabled (as is default on ATtiny), an 8-bit value
  119. // is sufficient to encode pixel color order, saving some space.
  120. #ifdef NEO_KHZ400
  121. typedef uint16_t neoPixelType; ///< 3rd arg to Adafruit_NeoPixel constructor
  122. #else
  123. typedef uint8_t neoPixelType; ///< 3rd arg to Adafruit_NeoPixel constructor
  124. #endif
  125. // These two tables are declared outside the Adafruit_NeoPixel class
  126. // because some boards may require oldschool compilers that don't
  127. // handle the C++11 constexpr keyword.
  128. /* A PROGMEM (flash mem) table containing 8-bit unsigned sine wave (0-255).
  129. Copy & paste this snippet into a Python REPL to regenerate:
  130. import math
  131. for x in range(256):
  132. print("{:3},".format(int((math.sin(x/128.0*math.pi)+1.0)*127.5+0.5))),
  133. if x&15 == 15: print
  134. */
  135. static const uint8_t PROGMEM _NeoPixelSineTable[256] = {
  136. 128,131,134,137,140,143,146,149,152,155,158,162,165,167,170,173,
  137. 176,179,182,185,188,190,193,196,198,201,203,206,208,211,213,215,
  138. 218,220,222,224,226,228,230,232,234,235,237,238,240,241,243,244,
  139. 245,246,248,249,250,250,251,252,253,253,254,254,254,255,255,255,
  140. 255,255,255,255,254,254,254,253,253,252,251,250,250,249,248,246,
  141. 245,244,243,241,240,238,237,235,234,232,230,228,226,224,222,220,
  142. 218,215,213,211,208,206,203,201,198,196,193,190,188,185,182,179,
  143. 176,173,170,167,165,162,158,155,152,149,146,143,140,137,134,131,
  144. 128,124,121,118,115,112,109,106,103,100, 97, 93, 90, 88, 85, 82,
  145. 79, 76, 73, 70, 67, 65, 62, 59, 57, 54, 52, 49, 47, 44, 42, 40,
  146. 37, 35, 33, 31, 29, 27, 25, 23, 21, 20, 18, 17, 15, 14, 12, 11,
  147. 10, 9, 7, 6, 5, 5, 4, 3, 2, 2, 1, 1, 1, 0, 0, 0,
  148. 0, 0, 0, 0, 1, 1, 1, 2, 2, 3, 4, 5, 5, 6, 7, 9,
  149. 10, 11, 12, 14, 15, 17, 18, 20, 21, 23, 25, 27, 29, 31, 33, 35,
  150. 37, 40, 42, 44, 47, 49, 52, 54, 57, 59, 62, 65, 67, 70, 73, 76,
  151. 79, 82, 85, 88, 90, 93, 97,100,103,106,109,112,115,118,121,124};
  152. /* Similar to above, but for an 8-bit gamma-correction table.
  153. Copy & paste this snippet into a Python REPL to regenerate:
  154. import math
  155. gamma=2.6
  156. for x in range(256):
  157. print("{:3},".format(int(math.pow((x)/255.0,gamma)*255.0+0.5))),
  158. if x&15 == 15: print
  159. */
  160. static const uint8_t PROGMEM _NeoPixelGammaTable[256] = {
  161. 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
  162. 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
  163. 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3,
  164. 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 5, 6, 6, 6, 6, 7,
  165. 7, 7, 8, 8, 8, 9, 9, 9, 10, 10, 10, 11, 11, 11, 12, 12,
  166. 13, 13, 13, 14, 14, 15, 15, 16, 16, 17, 17, 18, 18, 19, 19, 20,
  167. 20, 21, 21, 22, 22, 23, 24, 24, 25, 25, 26, 27, 27, 28, 29, 29,
  168. 30, 31, 31, 32, 33, 34, 34, 35, 36, 37, 38, 38, 39, 40, 41, 42,
  169. 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57,
  170. 58, 59, 60, 61, 62, 63, 64, 65, 66, 68, 69, 70, 71, 72, 73, 75,
  171. 76, 77, 78, 80, 81, 82, 84, 85, 86, 88, 89, 90, 92, 93, 94, 96,
  172. 97, 99,100,102,103,105,106,108,109,111,112,114,115,117,119,120,
  173. 122,124,125,127,129,130,132,134,136,137,139,141,143,145,146,148,
  174. 150,152,154,156,158,160,162,164,166,168,170,172,174,176,178,180,
  175. 182,184,186,188,191,193,195,197,199,202,204,206,209,211,213,215,
  176. 218,220,223,225,227,230,232,235,237,240,242,245,247,250,252,255};
  177. /*!
  178. @brief Class that stores state and functions for interacting with
  179. Adafruit NeoPixels and compatible devices.
  180. */
  181. class Adafruit_NeoPixel {
  182. public:
  183. // Constructor: number of LEDs, pin number, LED type
  184. Adafruit_NeoPixel(uint16_t n, uint16_t pin=6,
  185. neoPixelType type=NEO_GRB + NEO_KHZ800);
  186. Adafruit_NeoPixel(void);
  187. ~Adafruit_NeoPixel();
  188. void begin(void);
  189. void show(void);
  190. void setPin(uint16_t p);
  191. void setPixelColor(uint16_t n, uint8_t r, uint8_t g, uint8_t b);
  192. void setPixelColor(uint16_t n, uint8_t r, uint8_t g, uint8_t b,
  193. uint8_t w);
  194. void setPixelColor(uint16_t n, uint32_t c);
  195. void fill(uint32_t c=0, uint16_t first=0, uint16_t count=0);
  196. void setBrightness(uint8_t);
  197. void clear(void);
  198. void updateLength(uint16_t n);
  199. void updateType(neoPixelType t);
  200. /*!
  201. @brief Check whether a call to show() will start sending data
  202. immediately or will 'block' for a required interval. NeoPixels
  203. require a short quiet time (about 300 microseconds) after the
  204. last bit is received before the data 'latches' and new data can
  205. start being received. Usually one's sketch is implicitly using
  206. this time to generate a new frame of animation...but if it
  207. finishes very quickly, this function could be used to see if
  208. there's some idle time available for some low-priority
  209. concurrent task.
  210. @return 1 or true if show() will start sending immediately, 0 or false
  211. if show() would block (meaning some idle time is available).
  212. */
  213. bool canShow(void) const { return (micros()-endTime) >= 300L; }
  214. /*!
  215. @brief Get a pointer directly to the NeoPixel data buffer in RAM.
  216. Pixel data is stored in a device-native format (a la the NEO_*
  217. constants) and is not translated here. Applications that access
  218. this buffer will need to be aware of the specific data format
  219. and handle colors appropriately.
  220. @return Pointer to NeoPixel buffer (uint8_t* array).
  221. @note This is for high-performance applications where calling
  222. setPixelColor() on every single pixel would be too slow (e.g.
  223. POV or light-painting projects). There is no bounds checking
  224. on the array, creating tremendous potential for mayhem if one
  225. writes past the ends of the buffer. Great power, great
  226. responsibility and all that.
  227. */
  228. uint8_t *getPixels(void) const { return pixels; };
  229. uint8_t getBrightness(void) const;
  230. /*!
  231. @brief Retrieve the pin number used for NeoPixel data output.
  232. @return Arduino pin number (-1 if not set).
  233. */
  234. int16_t getPin(void) const { return pin; };
  235. /*!
  236. @brief Return the number of pixels in an Adafruit_NeoPixel strip object.
  237. @return Pixel count (0 if not set).
  238. */
  239. uint16_t numPixels(void) const { return numLEDs; }
  240. uint32_t getPixelColor(uint16_t n) const;
  241. /*!
  242. @brief An 8-bit integer sine wave function, not directly compatible
  243. with standard trigonometric units like radians or degrees.
  244. @param x Input angle, 0-255; 256 would loop back to zero, completing
  245. the circle (equivalent to 360 degrees or 2 pi radians).
  246. One can therefore use an unsigned 8-bit variable and simply
  247. add or subtract, allowing it to overflow/underflow and it
  248. still does the expected contiguous thing.
  249. @return Sine result, 0 to 255, or -128 to +127 if type-converted to
  250. a signed int8_t, but you'll most likely want unsigned as this
  251. output is often used for pixel brightness in animation effects.
  252. */
  253. static uint8_t sine8(uint8_t x) {
  254. return pgm_read_byte(&_NeoPixelSineTable[x]); // 0-255 in, 0-255 out
  255. }
  256. /*!
  257. @brief An 8-bit gamma-correction function for basic pixel brightness
  258. adjustment. Makes color transitions appear more perceptially
  259. correct.
  260. @param x Input brightness, 0 (minimum or off/black) to 255 (maximum).
  261. @return Gamma-adjusted brightness, can then be passed to one of the
  262. setPixelColor() functions. This uses a fixed gamma correction
  263. exponent of 2.6, which seems reasonably okay for average
  264. NeoPixels in average tasks. If you need finer control you'll
  265. need to provide your own gamma-correction function instead.
  266. */
  267. static uint8_t gamma8(uint8_t x) {
  268. return pgm_read_byte(&_NeoPixelGammaTable[x]); // 0-255 in, 0-255 out
  269. }
  270. /*!
  271. @brief Convert separate red, green and blue values into a single
  272. "packed" 32-bit RGB color.
  273. @param r Red brightness, 0 to 255.
  274. @param g Green brightness, 0 to 255.
  275. @param b Blue brightness, 0 to 255.
  276. @return 32-bit packed RGB value, which can then be assigned to a
  277. variable for later use or passed to the setPixelColor()
  278. function. Packed RGB format is predictable, regardless of
  279. LED strand color order.
  280. */
  281. static uint32_t Color(uint8_t r, uint8_t g, uint8_t b) {
  282. return ((uint32_t)r << 16) | ((uint32_t)g << 8) | b;
  283. }
  284. /*!
  285. @brief Convert separate red, green, blue and white values into a
  286. single "packed" 32-bit WRGB color.
  287. @param r Red brightness, 0 to 255.
  288. @param g Green brightness, 0 to 255.
  289. @param b Blue brightness, 0 to 255.
  290. @param w White brightness, 0 to 255.
  291. @return 32-bit packed WRGB value, which can then be assigned to a
  292. variable for later use or passed to the setPixelColor()
  293. function. Packed WRGB format is predictable, regardless of
  294. LED strand color order.
  295. */
  296. static uint32_t Color(uint8_t r, uint8_t g, uint8_t b, uint8_t w) {
  297. return ((uint32_t)w << 24) | ((uint32_t)r << 16) | ((uint32_t)g << 8) | b;
  298. }
  299. static uint32_t ColorHSV(uint16_t hue, uint8_t sat=255, uint8_t val=255);
  300. /*!
  301. @brief A gamma-correction function for 32-bit packed RGB or WRGB
  302. colors. Makes color transitions appear more perceptially
  303. correct.
  304. @param x 32-bit packed RGB or WRGB color.
  305. @return Gamma-adjusted packed color, can then be passed in one of the
  306. setPixelColor() functions. Like gamma8(), this uses a fixed
  307. gamma correction exponent of 2.6, which seems reasonably okay
  308. for average NeoPixels in average tasks. If you need finer
  309. control you'll need to provide your own gamma-correction
  310. function instead.
  311. */
  312. static uint32_t gamma32(uint32_t x);
  313. protected:
  314. #ifdef NEO_KHZ400 // If 400 KHz NeoPixel support enabled...
  315. bool is800KHz; ///< true if 800 KHz pixels
  316. #endif
  317. bool begun; ///< true if begin() previously called
  318. uint16_t numLEDs; ///< Number of RGB LEDs in strip
  319. uint16_t numBytes; ///< Size of 'pixels' buffer below
  320. int16_t pin; ///< Output pin number (-1 if not yet set)
  321. uint8_t brightness; ///< Strip brightness 0-255 (stored as +1)
  322. uint8_t *pixels; ///< Holds LED color values (3 or 4 bytes each)
  323. uint8_t rOffset; ///< Red index within each 3- or 4-byte pixel
  324. uint8_t gOffset; ///< Index of green byte
  325. uint8_t bOffset; ///< Index of blue byte
  326. uint8_t wOffset; ///< Index of white (==rOffset if no white)
  327. uint32_t endTime; ///< Latch timing reference
  328. #ifdef __AVR__
  329. volatile uint8_t *port; ///< Output PORT register
  330. uint8_t pinMask; ///< Output PORT bitmask
  331. #endif
  332. #if defined(ARDUINO_ARCH_STM32) || defined(ARDUINO_ARCH_ARDUINO_CORE_STM32)
  333. GPIO_TypeDef *gpioPort; ///< Output GPIO PORT
  334. uint32_t gpioPin; ///< Output GPIO PIN
  335. #endif
  336. };
  337. #endif // ADAFRUIT_NEOPIXEL_H