Control WS2812 LEDs with a Raspberry Pi
Colorful Lights
Control a matrix of WS2812 LEDs with the Raspberry Pi.
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).
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].
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.
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
TUXEDO Computers Unveils Linux Laptop Featuring AMD Ryzen CPU
This latest release is the first laptop to include the new CPU from Ryzen and Linux preinstalled.
-
XZ Gets the All-Clear
The back door xz vulnerability has been officially reverted for Fedora 40 and versions 38 and 39 were never affected.
-
Canonical Collaborates with Qualcomm on New Venture
This new joint effort is geared toward bringing Ubuntu and Ubuntu Core to Qualcomm-powered devices.
-
Kodi 21.0 Open-Source Entertainment Hub Released
After a year of development, the award-winning Kodi cross-platform, media center software is now available with many new additions and improvements.
-
Linux Usage Increases in Two Key Areas
If market share is your thing, you'll be happy to know that Linux is on the rise in two areas that, if they keep climbing, could have serious meaning for Linux's future.
-
Vulnerability Discovered in xz Libraries
An urgent alert for Fedora 40 has been posted and users should pay attention.
-
Canonical Bumps LTS Support to 12 years
If you're worried that your Ubuntu LTS release won't be supported long enough to last, Canonical has a surprise for you in the form of 12 years of security coverage.
-
Fedora 40 Beta Released Soon
With the official release of Fedora 40 coming in April, it's almost time to download the beta and see what's new.
-
New Pentesting Distribution to Compete with Kali Linux
SnoopGod is now available for your testing needs
-
Juno Computers Launches Another Linux Laptop
If you're looking for a powerhouse laptop that runs Ubuntu, the Juno Computers Neptune 17 v6 should be on your radar.