NeoPixelBus object API

Construction and Template Arguments

The constructor will require the declaration of several template arguments that specialize the class to the sketch writer's needs. These class types are provided for the author and there is no need to implement them.

NeoPixelBus<T_COLOR_FEATURE, T_METHOD>(...)

T_COLOR_FEATURE - the specialization class for the color feature.
T_METHOD - the specialization class for the method.

NeoPixelBus<T_COLOR_FEATURE, T_METHOD>(uint16_t countPixels, uint8_t pin)

This will define the object with the given Feature and Method, and construct it to handle the countPixels on the given pin.

countPixels - The number of pixels on the physical bus. This is limited primarily by memory to contain a buffer for them.

pin - The output pin to use. Note that some platforms and Methods restrict the Pin and thus this constructor should not be used on them. On Esp8266 use the constructor that omits the pin.

NeoPixelBus<T_COLOR_FEATURE, T_METHOD>(uint16_t countPixels, uint8_t pin, NeoBusChannel channel)

This will define the object with the given Feature and Method, and construct it to handle the countPixels on the given pin. Further, it takes the Methods multiplex channel to use for this instance. Not all methods support the channel feature.

countPixels - The number of pixels on the physical bus. This is limited primarily by memory to contain a buffer for them.

pin - The output pin to use. Note that some platforms and Methods restrict the Pin and thus this constructor should not be used on them. On Esp8266 use the constructor that omits the pin.

channel - The channel number defined by the enum NeoBusChannel to use.

NeoPixelBus<T_COLOR_FEATURE, T_METHOD>(uint16_t countPixels)

This will define the object with the given Feature and Method, and construct it to handle the countPixels using a hardware defined pin.
For Esp8266 this is the constructor to use.
For DotStar using SPI this is the constructor to use.

countPixels - The number of pixels on the physical bus. This is limited primarily by memory to contain a buffer for them. Some Methods (ex. NeoEsp8266Dma800KbpsMethod) require more buffer than others and you should refer to their documentation.

NeoPixelBus<T_COLOR_FEATURE, T_METHOD>(uint16_t countPixels, uint8_t pinClock, uint8_t pinData)

This will define the object with the given Feature and Method, and construct it to handle the countPixels on the given clock and data pins. This is used with DotStars only.

countPixels - The number of pixels on the physical bus. This is limited primarily by memory to contain a buffer for them.

pinClock - The clock output pin to use.

pinData - The data output pin to use.

Methods

void Begin()

This will initialize the NeoPixelBus and prepare it for use. Call this first within Setup().

void Begin(int8_t sck, int8_t miso, int8_t mosi, int8_t ss)

This will initialize the NeoPixelBus and prepare it for use. Call this first within Setup().
This is used with DotStars only using the DotStartSpiMethod only. Defining the pins here due to the SPI also needing the pins on its begin.

sck - The clock output pin to use.

miso - required by SPI, but not directly used

mosi - The data output pin to use.

ss - required by SPI, but not directly used

void Show(bool maintainBufferConsistency = true)

This will try to send the pixel information to the physical pixels. If there has been no change since the last time it was called, nothing will be sent.
Due to the hardware protocol, if you call this quickly after the last time it was called, it may wait up to 50us extra.
Based upon the Method used, sometimes this may take some time before it returns depending on the number of pixels or it may return almost immediately. If the method defined for the bus uses hardware, it will return quickly and send the data asynchronously. Otherwise, 300 pixel strip can take 9ms to send the data. The more pixels, the longer it takes, the less pixels, the quicker it can send them.

maintainBufferConsistency - (defaults to true) Some methods are asynchronous and will return quickly before the pixel data is completely sent. Due to this, some of these methods will internally use two buffers that they will swap between, one for sending and one for editing. By default, it will copy the contents between the buffers to maintain consistency between them. If you always overwrite the buffers and never call GetPixelColor(), then you can gain some performance by passing false for this argument.
CAUTION: If you call Show(false), You should consider calling Show(true) once after calling Begin() so that both internal buffers start with a consistent cleared state, as Show(false) expects that you overwrite every pixel on every update.

bool CanShow()

This will return true if enough time has passed since the last time Show() was called. This also means that calling Show() will not cause any undue waiting. If the method for the defined bus is hardware that sends asynchronously, then call CanShow() will let you know if it has finished sending the data from the last Show().
Normally, you really shouldn't worry about this as either you have enough other things in your sketch to process, or you have so little you don't care if Show() waits.

bool IsDirty()

This will return true if SetPixelColor() was called since the last time Show() was called. It will also return true if the Dirty() method was called.

void Dirty()

This will force the internal state to think that SetPixelColor() was called. This is handy if you modify the pixel buffer directly using the Pixels() method below.

void ResetDirty()

This will force the internal state to think that Show() has happened and there is nothing new to send.

uint8_t* Pixels()

This will return a pointer to the internal buffer of pixels. See PixelsSize() and PixelSize() to understand how large this buffer is and how its laid out. If you modify the buffer contents, you will need to let the NeoPixelBus know this by calling the Dirty() method otherwise Show() will not update the pixels.
CAUTION: The pointer returned should not be cached or retained between calls of Show(). The value may change after calling Show()

size_t PixelsSize()

This will return the number of bytes of the internal buffer that calling Pixels() returns.

size_t PixelSize()

This will return the number of bytes that a single pixel requires, as defined by the Feature given when the NeoPixelBus object was created.

uint16_t PixelCount()

This will return the number pixels the NeoPixelBus manages. This value was passed in to the NeoPixelBus object when it was created.

void SetPixelColor(uint16_t indexPixel, ColorObject color)

This will set the color for the given pixel.

indexPixel - the pixel number

color - a color object to use, RgbColor, HslColor, and HsbColor will all work and if the NeoPixelBus object was created with the NeoRgbwFeature the RgbwColor will also work.

ColorObject GetPixelColor(uint16_t indexPixel)

This will return the color for the given pixel.

indexPixel - the pixel number

<return>, a color object, RgbColor or RgbwColor.

void ClearTo(ColorObject color)

This will clear all pixels to the given color.

color - a color object to use, RgbColor, HslColor, and HsbColor will all work and if the NeoPixelBus object was created with the NeoRgbwFeature the RgbwColor will also work.

void ClearTo(ColorObject color, uint16_t first, uint16_t last)

This will clear all pixels from first to last to the given color.

color - a color object to use, RgbColor, HslColor, and HsbColor will all work and if the NeoPixelBus object was created with the NeoRgbwFeature the RgbwColor will also work.

first - the index to the first pixel to start clearing

last - the index to the last pixel that will be cleared

void RotateLeft(uint16_t rotationCount)

This will rotate all the pixels by the given number of pixels. The pixels on the left will wrap around to the right side.

rotationCount - the number of pixels to rotate left.

void RotateLeft(uint16_t rotationCount, uint16_t first, uint16_t last)

This will rotate all the pixels in the given range by the given number of pixels. The pixels on the left will wrap around to the right side.

rotationCount - the number of pixels to rotate left.

first - the first pixel to include in the rotation.

last - the last pixel to include in the rotation.

void ShiftLeft(uint16_t shiftCount)

This will shift all the pixels by the given number of pixels. The first shiftCount pixels on right will be left alone.

shiftCount - the number of pixels to shift left.

void ShiftLeft(uint16_t shiftCount, uint16_t first, uint16_t last)

This will shift all the pixels in the given range by the given number of pixels. The first shiftCount pixels on right will be left alone.

shiftCount - the number of pixels to shift left.

first - the first pixel to include in the shift.

last - the last pixel to include in the shift.

void RotateRight(uint16_t rotationCount)

This will rotate all the pixels by the given number of pixels. The pixels on the right will wrap around to the left side.