Jacob Bramley / PixelArray Featured

Control an array or chain of NeoPixel-compatible RGB LEDs. "NeoPixel" is Adafruit's name for WS2812- and WS2811-based addressable RGB LEDs. This library should work with any WS2811- or WS2812-based devices. Both the 400kHz and 800kHz protocols are supported. Most example code uses bit-banging to generate the timed signal precisely. This library uses an SPI peripheral instead. The main advantage of this is that the chip can service interrupts and the like without disrupting the signal (as long as the interrupts don't take _too_ long). The main disadvantage is that it requires the use of an SPI peripheral.

Dependencies:   BurstSPI

Dependents:   mbed_ws2812b easyNeo WS2811_Solidarite blip_rainbow ... more

Embed: (wiki syntax)

« Back to documentation index

PixelArray Class Reference
Public Member Functions

PixelArray Class Reference

Control an array or chain of NeoPixel-compatible RGB LEDs. More...

#include <neopixel.h>

Public Member Functions

 PixelArray (PinName out, ByteOrder byte_order=BYTE_ORDER_GRB, Protocol protocol=PROTOCOL_800KHZ)
 Initialize a PixelArray.
void update (Pixel buffer[], uint32_t length)
 Update the pixel display from a buffer.
void update (PixelGenerator generator, uint32_t length, uintptr_t extra)
 Update a pixel chain using the callback to generate the value for each pixel.

Detailed Description

Control an array or chain of NeoPixel-compatible RGB LEDs.

"NeoPixel" is Adafruit's name for WS2812- and WS2811-based addressable RGB LEDs. This library should work with any WS2811- or WS2812-based devices, as long as they support the fast-mode (800kHz) interface.

Most example code uses bit-banging to generate the timed signal precisely. This library uses an SPI peripheral instead. The main advantage of this is that the chip can service interrupts and the like without disrupting the signal (as long as the interrupts don't take _too_ long). The main disadvantage is that it requires the use of an SPI peripheral.

Note:
SPI peripherals will tend to leave the output pin ('MOSI') floating after a packet is sent. This will confuse the connected pixels, which expect the line to be driven low when idle. One way to fix this is to add a 10k resistor between 'MOSI' and ground so that it drops to '0' when not driven. Another method is to enable the on-chip pull-down resistor on the output pin. However, the mbed API only exposes this function through the DigitalIn and DigitalInOut classes. If you want to use the on-chip pull-down, you'll have to temporarily connect a DigitalIn peripheral _before_ creating instantiating the PixelArray.
 // Sample generator: Cycle through each colour combination, increasing the
 // brightness each time. `extra` is used as an iteration counter.
 void generate(neopixel::Pixel * out, uint32_t index, uintptr_t extra) {
   uint32_t brightness = (index + extra) >> 3;
   out->red   = ((index + extra) & 0x1) ? brightness : 0;
   out->green = ((index + extra) & 0x2) ? brightness : 0;
   out->blue  = ((index + extra) & 0x4) ? brightness : 0;
 }

 int main() {
   // Create a temporary DigitalIn so we can configure the pull-down resistor.
   // (The mbed API doesn't provide any other way to do this.)
   // An alternative is to connect an external pull-down resistor.
   DigitalIn(p5, PullDown);

   // The pixel array control class.
   neopixel::PixelArray array(p5);

   uint32_t offset = 0;
   while (1) {
     array.update(generate, 100, offset++);
     wait_ms(250);
   }
 }

Definition at line 95 of file neopixel.h.

Constructor & Destructor Documentation

PixelArray ( PinName  out,
ByteOrder  byte_order = BYTE_ORDER_GRB,
Protocol  protocol = PROTOCOL_800KHZ 
)

Initialize a PixelArray.

Parameters:
outOutput (SPI MOSI) pin.
byte_orderThe order in which to transmit colour channels.

Definition at line 8 of file neopixel.cpp.

Member Function Documentation

void update ( Pixel  buffer[],
uint32_t  length 
)

Update the pixel display from a buffer.

This update method is good in the following situations:

  • You want to make incremental changes to a fixed frame pattern.
  • The frame is hard (or impossible) to generate procedurally.
  • The frame requires a lot of time to generate.
Parameters:
bufferPixel data to be written.
lengthThe number of pixels to write.

buffer[0] is written to the pixel nearest the mbed. buffer[length-1] is written to the pixel furthest from the mbed.

Definition at line 108 of file neopixel.cpp.

void update ( PixelGenerator  generator,
uint32_t  length,
uintptr_t  extra 
)

Update a pixel chain using the callback to generate the value for each pixel.

This update method is good in the following situations:

  • You have a lot of pixels to drive and don't have enough RAM to buffer them all.
  • You want to display a frame pattern that can be generated procedurally generated without intensive processing.
Parameters:
generatorA callback which is called to generate a value for each pixel on demand. This function must be fairly fast: if it takes more than about 8-9us, the interface will reset and the display will be corrupted. The exact time limits will vary between WS281x variants. As a rough guide, an LPC1768 at 96MHz can (conservatively) execute about 750 instructions in that time.
lengthThe number of pixels to write.
extraAn arbitrary value to pass into the generator function. For example, this is a good way to pass an animation time index to the generator function.

Definition at line 117 of file neopixel.cpp.

Generated on Tue Jul 12 2022 16:16:27 by  doxygen 1.7.2