You are probably familiar with the large colored LED strips in many shop windows. Often these light strips use WS2812 RGB LEDs. Ready-made controllers are available, but they usually have a very limited feature set. In this article, I show you how to control a matrix of WS2812 LEDs with the Raspberry Pi.

Power Games

The WS2812 is a programmable RGB LED that is driven by a small controller that has a data byte for each of the three basic colors (red, green, and blue). This arrangement makes it possible to display more than 16 million colors with one LED. Each LED has four connections: two for the 5V power supply and two (DI, data in, and DO, data out) for asynchronous serial data transmission.

The output of one LED can be connected to the input of the next, which theoretically allows any number of WS2812 units to be connected in series. However, at some point, it takes so much time to write the values into the LEDs that they start to flicker. With 1,024 LEDs in series, it is just about possible to supply all the LEDs with data 30 times per second so that no visible flickering occurs.

The signal for driving the LEDs is constructed so that every single data bit is encoded in a complete period of the signal. The pulse/pause time of the signal indicates whether you are looking at a logical 1 or a logical 0. This method is well suited because a continuously changing signal is less susceptible to interference. Synchronization occurs when a single data bit is transmitted in a period of 1.25µs. Resetting an LED requires a low signal on the data line for at least 50ms.

As you can see, generating a signal for the WS2812 is not easy. The program must be written in a machine-oriented programming language like C. Moreover, very precise timing behavior must be maintained. Fortunately, you can use a library that takes care of generating the correct signal.

Because I plan to use a Raspberry Pi to control the matrix, another minor obstacle is the operating voltage and the signal level of the WS2812 diodes, which need 5V. The Raspberry Pi provides that operating voltage, but the signal levels it generates reach a maximum of 3.3V. If you look up the corresponding values in the WS2812 data sheet [1], you will find that the LEDs only detect signals from 3.6V upward without error, which makes an additional semiconductor necessary to raise the signal level. On the Internet you can find many examples by hackers that have done without this additional semiconductor. It might work, but it might not. The 74HC125 quad buffer/line driver used in this project costs just 25 cents – well-invested money for assured signal levels.

The library has a setting for the brightness of the WS2812 LEDs. This value should be set as low as possible, because a single LED draws up to 12mA of current at full brightness. For a typical strip with 64 diodes multiplied by 64, this results in a total current of almost 800mA for the Raspberry Pi to provide. This amount of current would overload many power supplies. Also, you should not send that much current through a ribbon cable. If you need the full brightness of the LEDs or want to work with more than 64 LEDs, you have to supply them with sufficient power from a separate 5V power supply.

Hardware Structure

When setting up the hardware, you have only one point to consider: If you generate the signal with a PWM generator, you need root privileges to execute the program. If you use the SPI interface, the program will run with user rights. You should avoid being the root user as often as possible.

Using the SPI interface (BCM pin 10, header pin 19) to generate the LED signals is a sensible option: Connect Raspberry Pi header pin 19 to the input of the 74HC125 and its output to the input of the WS2812 LED matrix [2].

The SMD version of the 74HC125 [3], which you solder on a prefabricated board [4], ensures you do not use too much space. To distribute the current that flows through the ribbon cable, use both Pi 5V connectors and two ground lines (Figure 1).

Figure 1: The circuit diagram for controlling the signal level to the WS2812 LED matrix. The pin numbers correspond to the physical header pins.

To protect the LED matrix and the 74HC125, I 3D-printed a case made of transparent filament for the assembly (Figure 2). The case contains simple stress relief to prevent the thin wires coming off the PCB and the LED matrix. The 3D printer STL and SCAD files can be found on the Linux Magazine FTP site [5].

Figure 2: A 3D-printed housing protects the electronics.

Preparing the Raspberry Pi

On the Raspberry Pi, you need to use a current image of the Raspberry Pi OS and desktop [6]. Moreover, the installation of the WS2812 driver requires some additional tools and libraries [5]:

$ sudo apt update
$ sudo apt upgrade
$ sudo apt install openjdk-10-jdk scons build-essential libpcre3 libpcre3-dev swig

To control the LEDs over the SPI interface, you have to activate them with raspi-config in menu item 5 Interfacing Options | P4 SPI.

To save energy, the Raspberry Pi models from the third generation onward lower the CPU frequency, which also changes the frequency of the SPI clock generator. Data transfer to the WS2812 LEDs will not function properly until you set the SPI generator to a fixed frequency by adding the line

core_freq=250

to the end of the config.txt file.

If you want to drive more than 64 LEDs, the SPI buffer might be too small. The buffer size is defined by adding

spidev.bufsiz=65536

to the single-line /boot/cmdline.txt file. To apply the changes, restart the Raspberry Pi.