Light weight library to control WS2811/WS2812/WS2812B based LEDS and LED Strings on 8-Bit AVR and ARM microcontrollers. The new version 2 of this library supports a simplified interface and arbitrary CPU clock. V2.1 finally adds Arduino support.
See the library in action on a LPC810
New: Experimental companion library for the APA102 LED
This is a small Ansi-C library to control WS2811/WS2812 based RGB Leds and strings. Only the 800kHz high-speed mode is supported. This library uses a bit-banging approach with cycle optimized assembler innerloops. Some advantages of this approach compared to other solutions are:
- Compatible to all AVR MCUs since it does not rely on special periphery.
- The code timing is automatically adjusted to the CPU clock at compile time.
- A CPU clock speed of 8 MHz and up is recommended, but even 4 MHz may work under some circumstances.
- Much smaller program code: Size optimized assembler without unrolled loops (<50 bytes in most cases)
- Supports standard AVR, reduced core AVR (Attiny 4/5/9/10/20/40) and XMEGA (untested) without special case handling.
- Experimental Cortex-M0 ARM support.
The timing values used in the library were adjusted to work on all devices. Look here and here for details.
- Add "light_ws2812.c", "light_ws2812.h" and "ws2812_config.h" to your project.
- Update "ws2812_config.h" according to your I/O pin.
- Make sure F_CPU is correctly defined in your makefile or the project. (For AtmelStudio: Project->Properties->Toolchain->AVR/GNU C Compiler->Symbols. Add symbol F_CPU=xxxxx)
- Call "ws2812_setleds" with a pointer to the LED array and the number LEDs.
- Alternatively you can use "ws2812_setleds_pin" to control up to 8 LED strips on the same Port.
Examples are provided in the Examples folder. You can build them with the supplied makefile.
- If you have Arduino 1.0.5 or newer, simply import the zipfile from light_ws2812_arduino with sketch->import library.
- Please refer to these instruction for older versions.
- To see how you can use it, have a look at the examples.
- Make sure the Pin you use to address the LEDs really exists! If not, the sketch won't compile or doesn't run correctly on your Arduino.
- Add "light_ws2812.cpp", "WS2812.cpp" and "WS2812.h" from the Arduino folder to your project.
- Refer to the header WS2812.h to determine how to use the class.
- Ports and LED-Count are handled dynamically, so you can add as many LED-Strips as you got free outpupt ports!
Please note that incorrect timing is rarely the source of problems. If you want to save some time, go through the items below before altering the library.
- Did you pass the correct array size in the function call?
- Is the pin configuration correct?
- Is anything else connected to the output pin you are using? Some development boards have LEDs connected to various pins.
- Did you choose the correct CPU frequency setting? Did you initialize the clock correctly?
- This is often a problem with insufficient current sourcing capability.
- Are you using a bypass capacitor for each LEDs as indicated in the datasheet? Not using a bypass capacitor will lead to erroneous behaviour.
- You may have to add an additional electrolytic capacitor at the input of your LED strip if you use long power supply lines.
- Is your power supply able to supply the required current-level? If set to white at maximum brightness, each LED will draw 60mA. A single USB-Port is barely able to supply 10 LEDs.
- The LEDs only display white: This can happen if the actual clock frequency of your MCU is lower than that given in F_CPU to the code.
- v2.0b 2014/01/19
- Initial release of V2 lib with new interface and architecture.
- v2.1 2014/03/08
- Added Arduino and C++ support courtesy of Matthias Riegler (@xvzf)
- v2.2 2014/11/30
- Improved Ardunio version with variable color order, courtesy of Windell Oskay (@oskay)
- Fixed a bug where the other bits of the port were trashed in Arduino version.
You can find the old V1 here: https://github.com/cpldcpu/light_ws2812/tree/v1.0
Device | 4 MHz | 8 MHz | 9.6 MHz | 12 MHz | 16 MHz | 20 Mhz |
---|---|---|---|---|---|---|
ATtiny 85 (Standard Core ) | X | X | X | |||
ATtiny 13 (Standard Core) | X | |||||
ATmega 8 (Standard Core) | X | X | ||||
ATtiny 10 (Reduced Core) | X | X | ||||
ATmega 168 (Standard Core) | X | X | ||||
ATmega 32u4 (Standard Core) | X | X |
Device | 4 MHz | 8 MHz | 9.6 MHz | 12 MHz | 16 MHz | 20 Mhz |
---|---|---|---|---|---|---|
Arduino Uno | X | |||||
Arduino Mega 2560 | X |
Device | 12 MHz | 20 MHz | 30 MHz |
---|---|---|---|
LPC810 (Cortex M0+) | X | X | x |
Please find updates on https://github.com/cpldcpu/light_ws2812
bug reports etc: cpldcpu@gmail.com