Arduino library · LEDs

NeoPixelBus: WS2812 strips with features, methods and colors

NeoPixelBus by Michael Miller (Makuna) is the strip library many ESP8266 and ESP32 projects use, chosen for its hardware methods that send the signal with DMA, RMT or I2S instead of tying up the CPU. A strip is declared as a template with two parts: the feature, which is the color order and pixel size (NeoGrbFeature for a WS2812B, NeoGrbwFeature for an SK6812 RGBW), and the method, which is how the bits get onto the wire.

Open the example in the editor See the calls

Built in on Mokxi: #include <NeoPixelBus.h> and it builds, with nothing to install. Free, and no account needed.

What NeoPixelBus by Makuna does

Colors are objects rather than packed numbers. RgbColor holds red, green and blue; HslColor and HsbColor convert from hue, which makes rainbows and fades easy; RgbColor::LinearBlend mixes two colors. The method names are capitalized, Begin(), SetPixelColor(), Show(), which trips up people coming from Adafruit_NeoPixel. NeoPixelAnimator adds timed animations with easing curves without any delay() in loop().

In Mokxi every one-wire method, whatever chip it is named for, sends the same timed 800 kHz signal, so sketches written with NeoWs2812xMethod or Neo800KbpsMethod both light the ws2812 part on the AVR boards, the ESP32 family and the Pico. The two-wire methods for DotStar, LPD8806 and WS2801 clock their frames out on the pins, but no part reads them.

Library Manager name	NeoPixelBus by Makuna
Author	Michael C. Miller
Include	`#include <NeoPixelBus.h>` `#include <NeoPixelAnimator.h>` `#include <NeoPixelBusLg.h>` `#include <NeoPixelSegmentBus.h>`
Boards	Arduino Uno, Arduino Nano, Arduino Mega 2560, Arduino Leonardo, SparkFun Pro Micro, Arduino Micro, Arduino Pro Mini 3.3 V, ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, Raspberry Pi Pico, Raspberry Pi Pico W, Arduino Nano RP2040 Connect, Seeed XIAO RP2040, Waveshare RP2040-Zero, Arduino Uno R4, Arduino Uno R4 WiFi
In the simulator	Simulated: it runs against the part the way it does on the bench.
Parts it drives	Addressable RGB LEDs

Install it

It builds on Arduino Uno, Arduino Nano, Arduino Mega 2560, Arduino Leonardo, SparkFun Pro Micro, Arduino Micro, Arduino Pro Mini 3.3 V, ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, Raspberry Pi Pico, Raspberry Pi Pico W, Arduino Nano RP2040 Connect, Seeed XIAO RP2040, Waveshare RP2040-Zero, Arduino Uno R4, Arduino Uno R4 WiFi.

In Mokxi it is built in: #include <NeoPixelBus.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "NeoPixelBus by Makuna" by Michael C. Miller from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add NeoPixelBus by Makuna to lib_deps in PlatformIO. Mokxi follows the calls of release 2.8.4, so a sketch written here builds there too.

What to know in the simulator: Every one-wire method, whatever platform it is named for, is the same timed 800 kHz bit-bang, not inverted, on the boards where Adafruit_NeoPixel runs. The DotStar, HD108, LPD8806, LPD6803, P9813 and WS2801 methods clock their frames out on the pins, but no Mokxi part reads them.

The calls you will use

In the order a sketch meets them.

`NeoPixelBus<NeoGrbFeature, Neo800KbpsMethod> strip(8, 6)`

Eight WS2812 LEDs in GRB order on pin 6. On an ESP32 NeoWs2812xMethod is the usual method; the feature stays the same.

`strip.Begin()`

Sets the output up and clears the buffer. Capital B: begin() does not exist here.

`RgbColor red(128, 0, 0)`

A color object. RgbColor black(0) sets all three channels at once.

`HslColor hslBlue(RgbColor(0, 0, 128))`

The same color as hue, saturation and lightness. Build one from HslColor(hue, 1.0f, 0.5f) with hue from 0.0 to 1.0 for a rainbow.

`strip.SetPixelColor(0, red)`

Puts a color in the buffer for one LED. It takes RgbColor, HslColor or HsbColor and converts as needed.

`strip.ClearTo(black)`

Fills the whole buffer with one color, faster than a loop of SetPixelColor() calls.

`strip.Show()`

Sends the buffer to the strip. Nothing lights until it runs.

`RgbColor back = strip.GetPixelColor(2)`

Reads a color back from the buffer, with .R, .G and .B members.

`RgbColor::LinearBlend(red, black, 0.5f)`

The color part of the way between two others, 0.0 for the first and 1.0 for the second. The basis of smooth fades.

Example: Colors on a strip with NeoPixelBus

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3

#include <NeoPixelBus.h>

const uint16_t PixelCount = 8;
const uint8_t PixelPin = 6;
#define colorSaturation 128

NeoPixelBus<NeoGrbFeature, Neo800KbpsMethod> strip(PixelCount, PixelPin);

RgbColor red(colorSaturation, 0, 0);
RgbColor green(0, colorSaturation, 0);
HslColor hslBlue(RgbColor(0, 0, colorSaturation));
RgbColor black(0);

void setup() {
  Serial.begin(9600);
  strip.Begin();
  strip.ClearTo(black);
  strip.SetPixelColor(0, red);
  strip.SetPixelColor(1, green);
  strip.SetPixelColor(2, hslBlue);
  strip.Show();
  RgbColor back = strip.GetPixelColor(2);
  Serial.print("pixel 2 blue ");
  Serial.println(back.B);
}

void loop() {}

Wiring

Arduino Uno R3 6 to Addressable RGB LEDs DIN
Arduino Uno R3 5V to Addressable RGB LEDs VDD
Arduino Uno R3 GND to Addressable RGB LEDs VSS

Open it in the editor, wired and ready to run

Common errors and how to fix them

`'class NeoPixelBus<...>' has no member named 'begin'`

NeoPixelBus capitalizes its methods. Write Begin(), Show(), SetPixelColor() and ClearTo(); the lowercase names are Adafruit_NeoPixel’s and FastLED’s.

`Red and green are swapped on the strip`

The feature does not match the LEDs. WS2812B strips are GRB, so use NeoGrbFeature; NeoRgbFeature is for the rarer strips that take red first.

`The first LED flickers or shows the wrong color on an ESP32`

A bit-bang method is being disturbed by WiFi interrupts. On real hardware use NeoWs2812xMethod or an RMT method so the hardware times the bits. In Mokxi every method is timed the same way.

Questions and answers

Why choose NeoPixelBus over Adafruit_NeoPixel or FastLED?

Its ESP8266 and ESP32 methods send the data with hardware, which keeps WiFi happy, and its color classes and animator are built in. For an Uno, Adafruit_NeoPixel is simpler.

Keep going

Learn

Parts

Addressable RGB LEDs

More leds libraries

Every built-in library · Open the editor

Try NeoPixelBus by Makuna without installing anything

Open the example, change the sketch, and keep your version in a free account.

Start building free

Open the editor