WiFi controlled Neo Pixels strips

In this project I explain how to drive NeoPixels with an Arduino M0 PRO (SAMD21) using the SPI peripheral with the DMA controller to create colored animated patterns. Since displaying simple animation is boring, I’ll show how to send commands over a WiFi connection in order to change the colored patterns created with the leds. Making all these components work together in a timely fashion inside the application is not trivial. Using the SPI with direct memory access offloads some work from the CPU to the DMA controller, but listening for commands over the UART from the WiFi module while updating the animation requires careful planning of the CPU usage. The simplest approach, the one shown here, is to use a classic superloop, or infinite-loop and ISRs.

Driving NeoPixels with the SPI

NeoPixels are integrated light sources in which a RGB led is packaged with a driver chip (the WS2812/WS2812B or the SK6812) and controlled by a single-wire. They can be used singularly or most often come in strips of a variable number of elements. The protocol is simple, a 24-bit RGB color (8 bits per color) is sent through the only data wire with a timing specified in the chip datasheet: data transmission is allowed up to 800KHz and coding a 0 or a 1 is just a matter of generating a square wave with the correct duty cycle:

figure 1: coding of 0 and 1 signals, timing characteristics and order of color data

If we need to drive a strip of leds we need to send the color for the first led, then the second and so on until the color for the last led of the strip has been sent. When we’re done we simply latch the data by sending a 300 microseconds worth of zeroes, then the leds lights up. Timing is not very strict (the chip allows for little tolerance) and different driver chips specify different timing characteristics but they all work the same (see the datasheet for the various driver chips at the end of the article). Since timing is so crucial we could write some time-critical code in assembly to toggle the level of the data pin in order to generate the correct signal to drive the leds. This approach would be difficult to integrate with the other components, since we want to animate the leds and at the same time the application need to listen for commands over the UART (and possibly do something else). Since the datasheet allows for a little tolerance in the signal timing we can use the SPI to generate a bit pattern that resembles the square wave that corresponds to a zero or a one code. Each bit is expanded into three bits: if we want to send a 1 code we send a 110 pattern, if we want to send a 0 code we send a 100 pattern, while the SPI is configured with a speed of 800 KHz * 3 = 2.4 MHz:

figure 2: bit code expansion into a three-bits pattern

At the end of the data we need to provide the latch signal, so the SPI will send 90 bytes filled with zeroes. We send data using the direct memory access capability of the SAMD21, freeing the CPU from loading the SPI register with data. So if the strip contains N leds we need a buffer of N * 3 * 3 (each led needs three bytes and each bit is expanded into three bits) + 90 bytes for latching. Since it’s from this buffer that the DMA controller fetches the data for the SPI I’ll call it the DMA buffer. Another buffer is created which is used as a framebuffer  and is updated by the application: this buffer contains just the original color data (3 bytes per led pixel), so it’s easy to read from and write to (in the same way a display framebuffer is updated); each byte in this framebuffer is then expanded into three bytes by indexing into a lookup table (the table has 256 entries, one for each possible byte) and copied into the DMA buffer, ready to be sent out by the SPI:

figure 3: the pixel framebuffer is expanded into the DMA buffer that is sent to the SPI peripheral by the DMA controller

The DMA controller

The DMA controller of the SAMD21 allows all kinds of data transfer (peripheral to memory, memory to peripheral, memory to memory and peripheral to peripheral), has 12 configurable channels  and use transfer descriptors to configure the tranfers. The DMA controller is configured to receive requests from the SPI peripheral whenever it need to send data (the SPI triggers DMA data transfers). Data is tranferred from the DMA buffer to the SPI data register continuously (one byte at the time) even if the data stays the same (to avoid glitches in the light patterns); the DMA channel is re-enabled after each DMA transfer complete interrupt. I provide a simple way to add channels to the DMA controller, even if in this application we need only one for the SPI:

A section in RAM is allocated for transfer descriptors (in this application we need just one but it can be extended to as many descriptors as needed). A DMA channel is configured and added for the SPI in the NeoPixel_init() function inside the NeoPixel.c file:

So, at the beginning both the DMA buffer and the frame buffer (here called pixel_buffer) are empty (filled with zeroes, all leds off). The DMA is initialized, a channel linked to the SPI (SERCOM0) is added and the SPI initialized and enabled. The NUM_PIXELS macro is defined in NeoPixel.h to select how many pixels the strip is made of. At this point the SPI is sending the contents of the DMA buffer on the data line, but we still have to “draw” on the framebuffer to display light patterns. The fundamental function is NeoPixel_set_pixel():

After checking that the selected pixel is in range, the function draw the selected color into the framebuffer. To display the updated buffer we need to call NeoPixel_update(), which copies the pixel buffer into the DMA buffer, expanding the bytes by performing a table lookup into the expand array (the index into the expand array is the byte itself):

The DMA continuously transfers data from the DMA buffer to the SPI data register, so as soon as the NeoPixel_update() function executes the leds are updated with the contents of the pixel buffer.

Animating the pixels: the timer

The NeoPixel_update_animation() function updates the pixel framebuffer with a new frame of the animation. This function is called in the infinite loop of the main() function. To display a smooth animation the buffer should be updated 30 times per second, so we need a timer that generates a periodic interrupt that will serve as a timebase for the animation. Configuring the Timer/Counter of the SAMD21 is easy (the clock is configured to run at 48 MHz from GCLK_GEN0):

The timer is used in 16 bit mide and CC0 register is used with the prescaler value to set a periodic overflow 30 times a second. We also need to provide an interrupt handler to reset the timer overflow flag and to set the global flag to notify the application that the time is right to update the animation. The NeoPixel_update() function executes its body only when the flag is set:

An enumerated type Animation contains the current animation to be updated (in this example I implemented some simple lighting patterns), and a switch statement selects the current one. Another function NeoPixel_set_animation() selects the light pattern to animate. A variable called frame keeps track of the current frame of the animation.

Changing the animation over WiFi: the superloop

After initializing the board, the application sets a lighting pattern with the NeoPixel_set_animation() function and enters the infinite loop, which continuosly calls the NeoPixel_update_animation() function. So far so good, but I wanted to add some more interactivity to this project. A WiFi module (the ubiquitous ESP8266) is connected to the SERCOM-USART peripheral of the SAMD21. In this post don’t explain how to use the module (see the codeprovided at the end of the article). I set up a UDP connection, the ESP receives data and send them over USART to the SAMD21. The Serial library parse the data and looks for a command to change the animation. Receiving commands from the USART FIFO and parsing them is another task that has to be executed together with the animation of the leds. The USART ISR takes care of storing data from the WiFi module, so the application can check for commands and update the leds without blocking. The final application superloop is as follow:

figure 4: the superloop (infinite loop) inside main(): in yellow the two tasks, the arrows indicates ISRs (red) and application calls (blue)

The key aspect of this simple strategy is that the two tasks never block: the NeoPixel_update_animation() task only draws a new frame to the framebuffer if the timer has overflown and set the flag, otherwise it returns immediately. Same for the WiFi_receive_data() function, which use a non blocking implementation of the serial function Serial_find_timeout(): this function looks for a matching string in the USART receive FIFO and returns if it fails after a number of attempts (or if the FIFO is empty). The DMA capability of the SAMD21, with a careful use of non blocking functions and ISRs allow to execute the two tasks “concurrently” in a simple single threaded environment.

The final test

I assembled a little test device with a NeoPixel ring and a SAMD21 micro breakout board from Sparkfun. I added a microphone connected to the ADC of the microcontroller and a new animation pattern that follows the level of incoming sounds/voices. I use a UDP client on my PC to change the patterns. The complete code is provided after the video.

 

source code

1 Response

  1. Jonas says:

    Thank you for this great tutorial!
    I hade to make a change to the memcpy instruction in order to make it work, did this:
    memcpy(&descriptor_section[used_channels – 1), descriptor, sizeof(DmacDescriptor));
    instead of:
    memcpy(descriptor_section + used_channels * sizeof(DmacDescriptor), descriptor, sizeof(DmacDescriptor));

    Worked better for me, do not really have any idea why though.

Leave a Reply

Your email address will not be published. Required fields are marked *