![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2020\/07\/Nucleo-64-baner.jpg\")
<\/a><\/figure>\n<\/div>\n\n\n<\/p>\n\n\n\n
What are WS2812B LEDs?<\/h1>\n\n\n\n
These are RGB LEDs in a 5050 package with a built-in PWM controller with 8-bit resolution per color. PWM duty values are delivered digitally via just a single data line. We communicate with WS2812B LEDs using one-wire NZR communication similar to 1-Wire, except the communication for the LEDs is unidirectional. This means we can send the LED information about how it should be set, but we won\u2019t learn from it what state it is in. Fortunately, that\u2019s not a particular problem. What does it look like? Of course, the documentation explains everything best ( The transmitted signals, just like for 1-Wire, have predefined timing constants. For complete operation we only need 3 signals: logic 0, logic 1, and RESET.<\/p>\n\n\n <\/p>\n\n\n\n From the figure above it follows that the communication frequency is around 800 kHz.<\/p>\n\n\n An important feature of the LEDs is the ability to chain them. The LEDs have 4 pins. Two are for power (in the range 3.5\u20135.3 V) and two for data\u2014input and output. After an LED receives all the bytes it needs about colors, it automatically passes the input signal to its output. Thanks to this, they can theoretically be connected into infinite chains. <\/p>\n\n\n\n The manufacturer also notes that a 100 nF capacitor should be placed next to each LED in the chain. Strips available from the Middle Kingdom come with such capacitors.<\/p>\n\n\n\n The data write sequence to the LEDs starts with a RESET signal lasting at least 50 \u00b5s. Next come the data for the LEDs in GRB order from the first to the last LED. It\u2019s important that the data cannot have any interruptions during transmission. From the moment an anomaly occurs, the colors will start to differ from what was intended.<\/p>\n\n\n\n Today I\u2019ll be basing this on the STM32F103C8T6 found in the cheap boards from China widely known as BluePill<\/a>. These Chinese modules are very popular and inexpensive. I have a few myself, so why not use them.<\/p>\n\n\n <\/p>\n\n\n\n The microcontrollers don\u2019t have hardware support for the interface required by WS2812B LEDs. We have to handle it another way. The first thing that comes to mind is bit-banging the GPIO. On AVR, programmers manage via the assembly instruction \u2018nop\u2019, which allows you to wait the required time to change the state in a more or less controlled way. But using nops on STM32 won\u2019t make me write a universal and portable library\u2014we have a lot of different MCU configurations and use many different clock speeds. I need something better. You can guard the GPIO with a Timer and change its state after specific times. Maybe that would work, but I didn\u2019t even try that method. I came across the idea on the internet of using the MOSI signal from the SPI interface. It seemed interesting, so I started digging into it. The wiring diagram for the LED strip is trivially simple. I will use SPI number 1. Warning! Do not power directly from the STM32 module.<\/strong> WS2812B LEDs require around 50 mA per LED at maximum brightness. A chain of 60 LEDs\/meter will therefore require around 3 A\/meter at full, bright white! Supply power from an external, capable power supply.<\/p>\n\n\n <\/p>\n\n\n\n Pin PA5 serves as SCK of the SPI1 interface. It won\u2019t be needed, but in this case it cannot be used for anything other than SPI.<\/p>\n\n\n\n To control the pulse width of the NRZ signal, I had to use an entire SPI byte as a single bit for the LED. Thus the duration of one byte should be about 1.25 \u00b5s, so one SPI bit should last about 0.156 \u00b5s. This gives an SPI clock of 6.4 MHz. In the F103C8T6 the SPI prescaler values to choose from are 2, 4, 8, 16, 32, 64, 128 and 256, which correspondingly gives the MCU clock:<\/p>\n\n\n\n <\/p>\n\n\n\n Frankly, these values are not great. It\u2019s hard to set them like that in Cube. I encountered a claim on a certain popular forum that it MUST BE 6.4 MHz, PERIOD! Well, unfortunately, it doesn\u2019t have to be. We have something called tolerance (after all, there\u2019s so much fighting for it everywhere), and for WS2812B the tolerance of input signals can be \u00b10.15 \u00b5s, i.e., \u00b10.66 MHz. It will be much easier to get 6 MHz on SPI, e.g., by using a 48 MHz MCU clock and the SPI prescaler set to 8. Cube additionally suggests the SPI baud rate after selecting the prescaler. If you want a higher\/lower MCU clock, look for one where the prescaler gives about 6 MHz on SPI.<\/p>\n\n\n <\/p>\n\n\n\n 6 MHz means bit durations of:<\/p>\n\n\n\n Do any of the times above match the WS2812B timing table?<\/p>\n\n\n\n For T0H, 2 bits fit (0.35 \u00b5s \u00b10.15), and for T1H, 5 bits fit (0.9 \u00b5s \u00b10.15). The rest naturally fits too \ud83d\ude09<\/p>\n\n\n\n Since SPI transfers from the MSB (thanks, Piotr!), the definitions of the logic states will look like this:<\/p>\n\n\n\n For convenience, I created a structure that contains the color data for a single LED.<\/p>\n\n\n\n The basic library contains only three self-explanatory functions.<\/p>\n\n\n\n Initialization consists only of assigning a pointer to SPI to the library.<\/p>\n\n\n\n Setting an LED is done by the LED number in the chain and providing a struct variable with that LED\u2019s colors.<\/p>\n\n\n\n Refresh sets the SPI buffer bytes according to the LED colors. It creates a big buffer containing all the data for all LEDs. Unfortunately, this eats huge amounts of RAM, but there\u2019s a remedy for that, which I\u2019ll get to in a moment.<\/p>\n\n\n\n I think sending data to the LEDs is worth discussing. It\u2019s an interesting challenge to have the data reach the LEDs in one uninterrupted stream with a small MCU overhead.<\/p>\n\n\n\n Preparing data in the buffer according to colors involves quite a lot of bit shifts, which, fortunately, are light for the MCU.<\/p>\n\n\n\n And this works, but not quite correctly. Unfortunately, the last 3\u20134 LEDs on a 100-LED strip most often have random colors. This is probably because an interrupt occurs during the SPI transfer. It\u2019s probably the SysTick Timer interrupt, but I didn\u2019t check\u2014there\u2019s no point. You can disable it, but I don\u2019t recommend it. What now? Every STM32 has something called DMA. In plain terms, it\u2019s a peripheral with direct memory access. You can delegate to it an operation involving memory or another peripheral. Thanks to this, the MCU has time to perform other tasks, such as the SysTick interrupt that disrupted the data transfer to the LEDs.<\/p>\n\n\n\n Configuring DMA in Cube is simple. In the Configuration tab and the System table, there\u2019s a DMA configuration button. Add a DMA configuration for SPI1_TX, which was configured earlier. Set the priority to Very High because this is a key operation. In the settings at the bottom, select Normal mode and memory increment, which in this case will be the RAM buffer.<\/p>\n\n\n <\/p>\n\n\n\n How should it work now? Only the data transfer call over SPI in the refresh function changes. Now it looks like this:<\/p>\n\n\n\n The second line waits for the transfer to complete. You can skip it, but you should do so consciously and be careful not to cause a \u201ccollision\u201d on the DMA, because everything will break.<\/p>\n\n\n <\/p>\n\n\n\n Now the LEDs work like a charm. Each one has exactly the color I intended.<\/p>\n\n\n\n Sending data for 35 LEDs (that\u2019s how many I have connected for testing) is just over 1 ms, specifically 1.22 ms. The time needed to prepare the send buffer is 0.27 ms of MCU life. For simple applications, you can wait out the transfer time as I did. However, it\u2019s worth trying to use that time for other tasks. That\u2019s almost a millisecond with just 35 LEDs. Controlling 100 LEDs, the saved time will be about 2.8 ms, and a thousand LEDs is already 28 ms. Quite a saving, because during that time you can refresh a TFT instead of idly waiting.<\/p>\n\n\n\n Unfortunately, a huge downside of this solution is the data buffer passed to the SPI transfer. Each LED consumes 24 bytes of RAM. For the STM32F103C8T6 the compiler reports memory issues already at around 300 LEDs. A bit sad \ud83d\ude41<\/p>\n\n\n\n There is a way! Every STM32 not only has DMA but also a few interesting interrupts that it can trigger during its operation.<\/p>\n\n\n\n The first two will be perfect. After all, you can create a small data buffer, run cyclic DMA, and when the half-transfer interrupt occurs, replace the first half of the buffer. Brilliant! Note also that preparing a complete buffer takes significantly less time than sending half of that buffer. The MCU should manage it with a finger in\u2026 GND \ud83d\ude09<\/p>\n\n\n\n Important: The function that starts the SPI transfer via DMA takes the size of the buffer holding the data, not the total amount of data you want to send! Starting DMA in circular buffer mode will keep sending data until you stop it manually. Therefore, in the half-transfer and full-transfer interrupts, you need to count how many LEDs\u2019 data have already been sent and stop the DMA after the last batch.<\/p>\n\n\n\n I\u2019ll shorten the data buffer to 48 bytes, i.e., it will fit the data for two LEDs. This will pack nicely. The operating scheme is as follows:<\/p>\n\n\n\n A fun fact. The HAL library is written in such a way that the callbacks of individual DMA interrupts are declared in it with the weak<\/em> symbol. This means that you can override them in your source files, but they must have the same name, arguments, and return type. ST wrote HAL so that you don\u2019t have to worry about enabling the appropriate DMA interrupts via bits and registers. If we declare our own functions appropriate to the interrupt we need, inside the HAL_SPI_Transmit_DM<\/em> function this will be detected and the library will activate the appropriate interrupts for us. You don\u2019t have to worry about anything. Nice, isn\u2019t it? The only thing to remember is to enable the global DMA interrupt in Cube and assign it a priority. Moving on to my code:<\/p>\n\n\n\n What do the waveform and the individual stages of preparing and sending data from the buffer look like now?<\/p>\n\n\n <\/p>\n\n\n\n The total frame transfer time has not changed significantly. Overall, the transfer increased slightly to 1.23 ms. The time required to send half the buffer (24 bytes) via DMA is 31 \u00b5s. Very little. Preparing the next batch of 24 bytes of data takes the MCU only 7 \u00b5s. That gives 26 \u00b5s of CPU time saved per LED, which it can use for something else. Too little? With 100 LEDs that\u2019s 2.6 ms, while with 1000 we have 26 ms of CPU time. The transfer time differences compared to sending one large buffer are small. But what RAM savings! 912 bytes for a full buffer vs. 48 bytes for chunking\u2014and that\u2019s with just 35 LEDs. Increasing the number of lit points in the chain and sticking with the concept of one big buffer causes the buffer size to grow drastically. 100 LEDs is already about 2.4 kB of data. Meanwhile, using a small buffer and half-transfer DMA interrupts, the buffer remains unchanged! Beautiful.<\/p>\n\n\n\n WS2812B LEDs are great. With a really minimal number of connections, we can set EVERY<\/strong> LED individually. It\u2019s true there\u2019s no actual addressing of the LEDs here, but you can easily move through them in the buffer. We achieve this effect without multiplexing and without separating color channels. Control may seem troublesome, but skillful use of standard interfaces in STM32 allows for trouble-free control of really long chains. The use of SPI presented in this post has one basic drawback. The pin responsible for the SCK of the serial interface is unused and can\u2019t be used for anything else (at least not that I know of). When creating a packed and complicated project, that pin could come in handy. Fortunately, most projects I know using flashy combinations on LEDs don\u2019t have too many circuits connected to the MCU. Go ahead and create your own! In two weeks I\u2019ll present some ready-made lighting effects that will certainly come in handy on the Christmas tree.<\/p>\n\n\n\n Thank you for reading this post. If you like this topic, let me know in the comments. I\u2019d also be grateful for suggestions of topics you\u2019d like me to cover.<\/p>\n\n\n\n The code is, as usual, available on my GitHub: link<\/a><\/p>\n\n\n\n If you noticed any error, disagree with something, would like to add something important, or simply think you\u2019d like to discuss this topic, write a comment. Remember that the discussion should be polite and in accordance with the rules of the Polish language.<\/span><\/p>\n\n\n\n This article is part of the series:<\/p>\n\n\n\n
WS2812B Datasheet<\/a>
). Even though it\u2019s very short, I\u2019ll summarize the most important information here.<\/p>\n\n\n\n![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_timings.png\")
<\/a><\/figure>\n<\/div>\n\n\n![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_pinout.png\")
<\/a><\/figure>\n<\/div>\n\n\nSTM32 code<\/h2>\n\n\n\n
![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2019\/11\/BluePill-baner2.jpg\")
<\/a><\/figure>\n<\/div>\n\n\n![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_schematic_spi-300x227.png\")
<\/a><\/figure>\n<\/div>\n\n\n\n
![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_cube_spi_prescaler.png\")
<\/a><\/figure>\n<\/div>\n\n\n![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_cube_spi_prescaler_preset.png\")
<\/a><\/figure>\n<\/div>\n\n\n\n
#define zero 0b11000000\n#define one 0b11111000\n<\/pre>\n\n\n\n
typedef struct ws2812b_color {\n uint8_t red, green, blue;\n} ws2812b_color;\n<\/pre>\n\n\n\nvoid WS2812B_Init(SPI_HandleTypeDef * spi_handler);\nvoid WS2812B_SetDiodeColor(int16_t diode_id, ws2812b_color color);\nvoid WS2812B_Refresh();<\/pre>\n\n\n\n
Sending data<\/h2>\n\n\n\n
for(uint8_t i = 0; i < 72; i++)\n\tbuffer[i] = 0x00;\n\nfor(uint16_t i=0, j=72; i<WS2812B_LEDS; i++)\n{\n\t\/\/GREEN\n\tfor(int8_t k=7; k>=0; k--)\n\t{\n\t\tif((ws2812b_array[i].green & (1<<k)) == 0)\n\t\t\tbuffer[j] = zero;\n\t\telse\n\t\t\tbuffer[j] = one;\n\t\tj++;\n\t}\n\n\t\/\/RED\n\tfor(int8_t k=7; k>=0; k--)\n\t{\n\t\tif((ws2812b_array[i].red & (1<<k)) == 0)\n\t\t\tbuffer[j] = zero;\n\t\telse\n\t\t\tbuffer[j] = one;\n\t\tj++;\n\t}\n\n\t\/\/BLUE\n\tfor(int8_t k=7; k>=0; k--)\n\t{\n\t\tif((ws2812b_array[i].blue & (1<<k)) == 0)\n\t\t\tbuffer[j] = zero;\n\t\telse\n\t\t\tbuffer[j] = one;\n\t\tj++;\n\t}\n}\n\nHAL_SPI_Transmit(hspi_ws2812b, buffer, (WS2812B_LEDS+3) * 24, 1000);\n<\/pre>\n\n\n\n![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_cube_dma.png\")
<\/a><\/figure>\n<\/div>\n\n\nHAL_SPI_Transmit_DMA(hspi_ws2812b, buffer, (WS2812B_LEDS+3) * 24);\nwhile(HAL_DMA_STATE_READY != HAL_DMA_GetState(hspi_ws2812b->hdmatx));<\/pre>\n\n\n\n
![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_timings_data_transfer-1024x176.png\"){kind=spacer}
<\/a><\/figure>\n<\/div>\n\n\nReducing RAM usage<\/h2>\n\n\n\n
\n
![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_timings_dma_half-1024x240.png\")
<\/a><\/figure>\n<\/div>\n\n\n\n
void WS2812B_Refresh()\n{\n\tCurrentLed = 0;\n\tResetSignal = 0;\n\n\tfor(uint8_t i = 0; i < 48; i++)\n\t\tbuffer[i] = 0x00;\n\n\tHAL_SPI_Transmit_DMA(hspi_ws2812b, buffer, 48); \/\/ Additional 3 for reset signal\n\twhile(HAL_DMA_STATE_READY != HAL_DMA_GetState(hspi_ws2812b->hdmatx));\n}\n\nvoid HAL_SPI_TxHalfCpltCallback(SPI_HandleTypeDef *hspi)\n{\n\tif(hspi == hspi_ws2812b)\n\t{\n\t\tif(!ResetSignal)\n\t\t{\n\t\t\tfor(uint8_t k = 0; k < 24; k++) \/\/ To 72 impulses of reset\n\t\t\t{\n\t\t\t\tbuffer[k] = 0x00;\n\t\t\t}\n\t\t\tResetSignal = 1; \/\/ End reset signal\n\t\t}\n\t\telse \/\/ LEDs Odd 1,3,5,7...\n\t\t{\n\t\t\tif(CurrentLed > WS2812B_LEDS)\n\t\t\t{\n\t\t\t\tHAL_SPI_DMAStop(hspi_ws2812b);\n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\tuint8_t j = 0;\n\t\t\t\t\/\/GREEN\n\t\t\t\tfor(int8_t k=7; k>=0; k--)\n\t\t\t\t{\n\t\t\t\t\tif((ws2812b_array[CurrentLed].green & (1<<k)) == 0)\n\t\t\t\t\t\tbuffer[j] = zero;\n\t\t\t\t\telse\n\t\t\t\t\t\tbuffer[j] = one;\n\t\t\t\t\tj++;\n\t\t\t\t}\n\n\t\t\t\t\/\/RED\n\t\t\t\tfor(int8_t k=7; k>=0; k--)\n\t\t\t\t{\n\t\t\t\t\tif((ws2812b_array[CurrentLed].red & (1<<k)) == 0)\n\t\t\t\t\t\tbuffer[j] = zero;\n\t\t\t\t\telse\n\t\t\t\t\t\tbuffer[j] = one;\n\t\t\t\t\tj++;\n\t\t\t\t}\n\n\t\t\t\t\/\/BLUE\n\t\t\t\tfor(int8_t k=7; k>=0; k--)\n\t\t\t\t{\n\t\t\t\t\tif((ws2812b_array[CurrentLed].blue & (1<<k)) == 0)\n\t\t\t\t\t\tbuffer[j] = zero;\n\t\t\t\t\telse\n\t\t\t\t\t\tbuffer[j] = one;\n\t\t\t\t\tj++;\n\t\t\t\t}\n\t\t\t\tCurrentLed++;\n\t\t\t}\n\t\t}\n\t}\n}\n\nvoid HAL_SPI_TxCpltCallback(SPI_HandleTypeDef *hspi)\n{\n\tif(hspi == hspi_ws2812b)\n\t{\n\t\tif(CurrentLed > WS2812B_LEDS)\n\t\t{\n\t\t\tHAL_SPI_DMAStop(hspi_ws2812b);\n\t\t}\n\t\telse\n\t\t{\n\t\t\t\/\/ Even LEDs 0,2,0\n\t\t\tuint8_t j = 24;\n\t\t\t\/\/GREEN\n\t\t\tfor(int8_t k=7; k>=0; k--)\n\t\t\t{\n\t\t\t\tif((ws2812b_array[CurrentLed].green & (1<<k)) == 0)\n\t\t\t\t\tbuffer[j] = zero;\n\t\t\t\telse\n\t\t\t\t\tbuffer[j] = one;\n\t\t\t\tj++;\n\t\t\t}\n\n\t\t\t\/\/RED\n\t\t\tfor(int8_t k=7; k>=0; k--)\n\t\t\t{\n\t\t\t\tif((ws2812b_array[CurrentLed].red & (1<<k)) == 0)\n\t\t\t\t\tbuffer[j] = zero;\n\t\t\t\telse\n\t\t\t\t\tbuffer[j] = one;\n\t\t\t\tj++;\n\t\t\t}\n\n\t\t\t\/\/BLUE\n\t\t\tfor(int8_t k=7; k>=0; k--)\n\t\t\t{\n\t\t\t\tif((ws2812b_array[CurrentLed].blue & (1<<k)) == 0)\n\t\t\t\t\tbuffer[j] = zero;\n\t\t\t\telse\n\t\t\t\t\tbuffer[j] = one;\n\t\t\t\tj++;\n\t\t\t}\n\t\t\tCurrentLed++;\n\t\t}\n\t}\n}\n<\/pre>\n\n\n\nResults of the reduced buffer<\/h2>\n\n\n\n
![\"\"](\"http:\/\/msalamon.pl\/wp-content\/uploads\/2018\/10\/ws2812b_timings_dma_small_buffer-1024x240.png\")
<\/a><\/figure>\n<\/div>\n\n\nSummary<\/h2>\n\n\n\n