rpi-ws281x 4.2.0

Background:

The BCM2835 in the Raspberry Pi has both a PWM and a PCM module that are well suited to driving individually controllable WS281X LEDs. Using the DMA, PWM or PCM FIFO, and serial mode in the PWM, it’s possible to control almost any number of WS281X LEDs in a chain connected to the appropriate output pin. For SPI the Raspbian spidev driver is used (/dev/spidev0.0). This library and test program set the clock rate to 3X the desired output frequency and creates a bit pattern in RAM from an array of colors where each bit is represented by 3 bits as follows.

Bit 1 - 1 1 0
Bit 0 - 1 0 0

GPIO Usage:

The GPIOs that can be used are limited by the hardware of the Pi and will vary based on the method used to drive them (PWM, PCM or SPI). Beware that the GPIO numbers are not the same as the physical pin numbers on the header.

PWM:

PWM0, which can be set to use GPIOs 12, 18, 40, and 52.
Only 12 (pin 32) and 18 (pin 12) are available on the B+/2B/3B

PWM1 which can be set to use GPIOs 13, 19, 41, 45 and 53.
Only 13 is available on the B+/2B/PiZero/3B, on pin 33

PCM:

PCM_DOUT, which can be set to use GPIOs 21 and 31.
Only 21 is available on the B+/2B/PiZero/3B, on pin 40.

SPI:

SPI0-MOSI is available on GPIOs 10 and 38.
Only GPIO 10 is available on all models.
See also note for RPi 3 below.

Power and voltage requirements

WS281X LEDs are generally driven at 5V. Depending on your actual LED model and data line length you might be able to successfully drive the data input with 3.3V. However in the general case you probably want to use a level shifter to convert from the Raspberry Pi GPIO/PWM to 5V.

It is also possible to run the LEDs from a 3.3V - 3.6V power source, and connect the GPIO directly at a cost of brightness, but this isn’t recommended.

The test program is designed to drive a 8x8 grid of LEDs e.g.from Adafruit (http://www.adafruit.com/products/1487) or Pimoroni (https://shop.pimoroni.com/products/unicorn-hat). Please see the Adafruit and Pimoroni websites for more information.

Know what you’re doing with the hardware and electricity. I take no reponsibility for damage, harm, or mistakes.

Important warning about DMA channels

You must make sure that the DMA channel you choose to use for the LEDs is not already in use by the operating system.

For example, using DMA channel 5 will cause filesystem corruption on the Raspberry Pi 3 Model B. See: https://github.com/jgarff/rpi_ws281x/issues/224

The default DMA channel (10) should be safe for the Raspberry Pi 3 Model B, but this may change in future software releases.

Limitations:

blacklist snd_bcm2835

hdmi_force_hotplug=1
hdmi_force_edid_audio=1

spidev.bufsiz=32768

core_freq=250

Comparison PWM/PCM/SPI

Both PWM and PCM use DMA transfer to output the control signal for the LEDs. The max size of a DMA transfer is 65536 bytes. Since each LED needs 12 bytes (4 colors, 8 symbols per color, 3 bits per symbol) this means you can control approximately 5400 LEDs for a single strand in PCM and 2700 LEDs per string for PWM (Only PWM can control 2 independent strings simultaneously) SPI uses the SPI device driver in the kernel. For transfers larger than 96 bytes the kernel driver also uses DMA. Of course there are practical limits on power and signal quality. These will be more constraining in practice than the theoretical limits above.

When controlling a LED string of 240 LEDs the CPU load on the original Pi 2 (BCM2836) are: PWM 5% PCM 5% SPI 1%

4.2.0

• New: Added support for Raspberry Pi 4

4.1.0

• New: Added support for the Pi 3A+

• Fix: Bugfix for ARM64 support

4.0.0

• Warning: Removed “neopixel” module from this library, use “rpi_ws281x” instead, see #8

3.1.0

• New: Exposed all contents of ws for easy access to strip_type constants

• Fix: Matched functionality of upstream legacy library by supporting strip_type

• Note: Default strip type is WS2811_STRIP_GRB

3.0.7

• New: Added support for Pi 3B+