Kernel program for driving ws2811 LEDs on a Raspberry Pi

In this aritcle I will describe a kernel program that can be loaded on a Raspberry Pi to control ws2811 addressable LEDs. Unlike other programs that can be used to drive these LEDs on a Raspberry Pi, this program can drive multiple strings in parallel. This allows the user to break up long strings of LEDs into sections to allow them to be updated faster. The kernel program uses the Raspberry Pi's secondary memory interface (SMI) and direct memory access (DMA) hardware to drive the LEDs.

User-space programs can interact with the kernel program through the /dev/ws281x file. User-space programs must first use ioctl calls to configure the size and number of LED strings connected to the Raspberry Pi. Then, they can write the LED pixel data directly to the /dev/ws281x file. Finally, the user can either manually update the LEDs with an ioctl call, or configure the kernel program to automatically update after a write.

The source code for this project can be found on Github

ws2811 LED protocol

Each string of LEDs requires only one output on the Raspberry Pi. Normally, the Pi keeps the output low, which prepares the LEDs to receive data, while allowing them to keep displaying the previous values. To write data, the Pi sends out a stream of pulses, where a zero is given by a short pulse (400ns on, 800ns off), and a one is given by a long pulse (800ns on, 400ns off). Data is sent out in 24-bit blocks, with one block for each LED. The first 8 bits of each block are for the intensity of the green component, the second are for the red component, and the third are for the blue component. Each byte is transmitted with the most significant bit first.

SMI

The secondary memory interface (SMI) can be used to write data to the Pi's output ports with precise timings. The SMI hardware is configured to update the output every 400 nanoseconds. This means that every 400ns, the SMI hardware takes a value from its first-in-first-out (FIFO) buffer and outputs it to the output pins. Since each bit is 1200ns, there are 3 SMI writes per bit. The first write sets all outputs to 1, the second outputs the data, and the third write sets all outputs to 0. This creates a long pulse for ones and a short pulse for zeros. This can be seen in the above image, where each vertical line represents an SMI write.

In the above image, channel 1 receives 1100011 and channel 2 receives 1011010. To output the data to the SMI hardware, the program must first replace every 1 with 110 (long pulse) and every 0 with 100 (short pulse). Thus, channel 1 would become 110110100100100110110 and channel 2 would become 110100110110100110100. Then, the program must combine the two bitstreams into a sequence of 16-bit words that are output to the SMI hardware. In this case, that sequence is (in hexadecimal):
0005 0005 0000 0005 0001 0000 0005 0004 0000 0005 0004 0000 0005 0000 0000 0005 0005 0000 0005 0001 0000

DMA

In order to maintain the required precise timing even when the CPU is doing something else, the program must use the DMA hardware to automatically load the next values into the SMI buffer. The DMA hardware can load information from one part of the Pi's memory to another automatically and without CPU intervention. To prevent a buffer underflow or overflow, the DMA hardware is configured to load the next value when the number of bytes in the buffer goes below a given threshold.

Potential issues when using the program

The main issues or challenges I encountered when creating this program were:
  • The documentation for the SMI hardware is hard to find as it is not included in the datasheet of the BCM2835 chip. This made it difficult to debug issues with the program.
  • The SMI hardware may also be used by other programs or features of the Pi. This will interfere with the output of the program and cause the LEDs to not update or display the wrong colors. For example, in order to make the program work, I had to disable the video output of the Pi with tvservice --off.
  • Since the DMA has no access to the CPU caches, the program must acquire uncached memory where the DMA control information and the data to be transferred can be stored. However, the process my program uses for acquiring uncached memory only works on older versions of Linux. The program seems to work on Linux version 4.4. I have not found a way to acquire uncached memory on newer versions of Linux.
  • The Raspberry Pi has 16 DMA channels, which may be used by other programs. One must select an unused DMA channel, otherwise the program may interfere with other programs on the Pi and vice versa.

Comments

Post a Comment

Popular posts from this blog

Improving and calibrating the capacitive water sensor

Image
In a previous article, I explained a type of water level sensor that works capactitively and therefore passes no direct current through the water. When I wrote that article, I had already made two of these sensors and installed one in each of the two sump pump wells in my basement. These sensors have been working quite well for a long time, but they have a few issues. In this article, I will describe the improvements I have made to the sensor design and how I calibrated the sensors to allow me to determine the water flow rate and the volume of water the sump pump pumps each time it comes on. Introduction The two water level sensors I installed in the sump pump wells were equipped with nRF24L01 wireless modules. They transmitted measurements every 30 seconds to a Raspberry Pi, which recorded them to a database. This allowed me to visualize the water level in the sump-pumps in real time and see roughly how often the sump pumps came on. However, the water level followed this interest
Read more

Turn a buck converter module into a buck-boost converter with only two components

Image
In this article I will show how you can turn a buck converter module (like the one shown below), which can only output a voltage lower than the input voltage, into a buck-boost converter module, which can output a voltage that is either lower or higher than the input voltage. Buck converter theory The schematic of a buck converter is shown below: Link to simulation The components in the box, in addition to the feedback loop (not shown), are usually integrated into a single chip. A regular buck-converter works by switching current into the output capacitor through an inductor. When the transistor in the box is on, current can flow from the supply to the output via the inductor. The voltage across the inductor is \(V_{in}-V_{out}\) and the rate of change of the current is \(\frac{V_{in}-V_{out}}{L}\). When the transistor in the box switches off, the current in the inductor continues to flow, but now through the diode. The voltage across the inductor is \(V_{out}\) and the rate of
Read more

Self-starting inverter

Image
In this article, I will explain a circuit that can be used to automatically start an inverter when a load is connected to it and turn it off once the load is disconnected. This circuit works by biasing the output of the inverter with a low-current signal from the battery and waiting for a change in that signal. The circuit then uses a current transformer to monitor the current through the load. If there is no current in the load for a few seconds, the inverter is switched off. The inverter The inverter I am using is a modified square wave inverter. The voltage between the live and neutral terminals at the output looks like this: However, this diagram misses out on an important fact: the neutral of the output is not connected to the negative battery terminal. In fact, the modified square wave is generated by alternately switching the live and neutral terminals of the output to an internal high-voltage rail. As a result, both live and neutral are always positive relative to the nega
Read more