LED Bit format

WS2812 uses PWM signals to send 0 and 1 bits. In each bit, the high signal first for a specific period, then the low signal. Depending on the length of the high portion, it can mean a 0-bit (short high level) or a 1-bit (long high level).

Raw Timing

Different manufacturers and models use different timing specifications. In most cases, the high level period is less than 0.5 microseconds for 0-bit; or larger than 0.5 microseconds for 1-bit. The low level period varies.

Following tables shows the timing diagram for some WS2812:

As we can see, it is chaotic. Different manufacturers, different models, completely different timing. It is hard to find a universal timing that fits all. Furthermore, when buying WS2812 LEDs on eBay or Amazon, the vendor only states WS2812, and there is no way to tell which manufacturer and which specific model it is. Unless buying a whole reel (so you can see the label), the best solution is to test it to find the actual timing; and of course, do not mix them (unless after testing the timing compatibility).

Timing for CPU clocked @ 8MHz

Although you are allowed to use any frequency between 0 to 20MHz to clock the AVR, a low-cost system will use the internal 8MHz RC clock (in that way, we can save a crystal, two capacitors, and get two free IOs to use). That means, every CPU cycle is 125 nanoseconds. Therefore, in terms of CPU cycles, to send a 1 or 0:

Timing for CPU clocked @ 16MHz

If you want to clock the CPU at 16MHz (like Arduino) using external crystal:

Timing for CPU clocked @ 20MHz

If you want to clock the CPU at max frequency (20MHz) using external crystal:

Example: XL-5050RGBW-WS2812B-HM & Worldsemi WS2812B with CPUs at Different Clocks

Let's use XL-5050RGBW-WS2812B-HM and Worldsemi WS2812B with CPUs at different clocks as out next example:

Furthermore, both 0-bit and 1-bit starts with a high level. At a specific cycle (2nd cycle for this example), we will send the data (high for 1-bit, low for 0-bit). At another specific cycle (6th cycle for this example), we send low.

It is clear to say, the timing requirement is tight for our application when the CPU is running at 8MHz. We will have to buffer the data in SRAM, and then burst output the data to satisfy the timing requirement.

Reset

To reset (start a new stream), we will need to pull the signal low for a long period. Above examples shows 80 or 280 microseconds, but other models may varies.

This time period allows us to load the prepared data in SRAM for burst output.

Furthermore, we can utilize this time period to send data streams to other LEDs. For example, we can use 100 microseconds to send data to LED series A, use the next 100 microseconds to send data to LED series B. Once B is finished, we can go back to A, which is now ready for the next data stream.

LED Word format

WS2812 supports 24-bit RGB color. That is, it takes 24 bits of data to program one LED. Green first, then red, then blue. MSB first.

Multiple LEDs are connected in series. We send a data stream to program them. The first LED in the series will consume the first 24 bits of data (bit 0 to bit 23); the second LED will consume the second 24 bits of data (bit 24 to bit 47), and so on.

8-Lane Parallel Bus

The more LEDs, the longer to take to program the entire light bar.

Furthermore, we are now using only 1 output bit. AVR (and other 8-bit MCUs) group 8-bit into a byte as a port. Bit output on ports is very inefficient.

To speed up the transmission, we can break the light bar into 8 segments. Next, we can use a 8-bit IO port to drive the segmented light bar, one bit for one segment.

As the above figure shows, the first byte output by the MCU will contain the first bit of all 8 segments, the second byte output by the MCU will contain the second bit of all 8 segments, and so on...

Example: 24 LEDs in 8 Segments

Following example shows 24 LEDs divided into 8 segments. That is, each segment has 3 LEDs.

With out segmented design, the controller should output:

		LED 0 G		LED 0 R		LED 0 B		LED 1 G		LED 1 R		LED 1 B		LED 2 G		LED 2 R		LED 2 B
Segment 0	0000 0000	0000 0001	0000 0010	0000 0100	0000 0101	0000 0110	0000 1000	0000 1001	0000 1010
Segment 1	0001 0000	0001 0001	0001 0010	0001 0100	0001 0101	0001 0110	0001 1000	0001 1001	0001 1010
Segment 2	0010 0000	0010 0001	0010 0010	0010 0100	0010 0101	0010 0110	0010 1000	0010 1001	0010 1010
Segment 3	0011 0000	0011 0001	0011 0010	0011 0100	0011 0101	0011 0110	0011 1000	0011 1001	0011 1010
Segment 4	0100 0000	0100 0001	0100 0010	0100 0100	0100 0101	0100 0110	0100 1000	0100 1001	0100 1010
Segment 5	0101 0000	0101 0001	0101 0010	0101 0100	0101 0101	0101 0110	0101 1000	0101 1001	0101 1010
Segment 6	0110 0000	0110 0001	0110 0010	0110 0100	0110 0101	0110 0110	0110 1000	0110 1001	0110 1010
Segment 7	0111 0000	0111 0001	0111 0010	0111 0100	0111 0101	0111 0110	0111 1000	0111 1001	0111 1010
	

With the segmented design, the controller should output:

00000000 00001111 00110011 01010101 00000000 00000000 00000000 00000000
00000000 00001111 00110011 01010101 00000000 00000000 00000000 11111111
00000000 00001111 00110011 01010101 00000000 00000000 11111111 00000000
00000000 00001111 00110011 01010101 00000000 11111111 00000000 00000000
00000000 00001111 00110011 01010101 00000000 11111111 00000000 11111111
00000000 00001111 00110011 01010101 00000000 11111111 11111111 00000000
00000000 00001111 00110011 01010101 11111111 00000000 00000000 00000000
00000000 00001111 00110011 01010101 11111111 00000000 00000000 11111111
00000000 00001111 00110011 01010101 11111111 00000000 11111111 00000000
	

The first bit in each segment is 00000000; therefore, we output 00000000 in the beginning. The second bit in each segment is 00001111; therefore, we output 00001111 then. The third bit in each segment is 00110011; therefore, we output 00110011 next.

Bit Driver

As we discussed in the previous section, timing requirement is tight. Especially, for XL-5050RGBW-WS2812B-HM, the shorter signal only last 350 microseconds, that's even less than 3 cycles for 8MHz (375 microseconds). Therefore, the most important aspect of this driver is to be fast and accurate.

For each data bit, we will need to:

1. At the beginning, set output high.
2. Read the color data bit, and index the read pointer.
3. At the some cycle, output the color data bit.
4. At the some cycle, set output low.
5. Check for the boundary of data stream (number of data bits in each segment).
   • If it is not the last data bit: At the 8th cycle, go to step 1.
   • If it is the last data bit: Stop sending, keep the output low for at least 80 microseconds. We can prepare data for the next output burst during this time.

Let’s write this task in C, assume we will be using PORTA on ATtiny461 to drive the LEDs:

1.c
#define SIZE (24 * 8) // 24 bits/LED

#include <avr/io.h>

volatile uint8_t data[SIZE];

void main() {
	DDRA = 0xFF;
	for (volatile uint8_t* p = data; p < &(data[SIZE]); p++) {
		PORTA = 0xFF;
		PORTA = *p;
		/* asm("nop\n"); */
		PORTA = 0x00;
	}
	for(;;);
}
	

Compile with avr-gcc 1.c -o 1.out -mmcu=attiny461 -O3.

The Evil for Loop with 16-bit Memory Addressing

Let's disassemble the above C code with avr-objdump -m avr25 -D 1.out > 1.txt:

00000048 <main>:
  48:	8f ef       	ldi	r24, 0xFF	; 255
  4a:	8a bb       	out	0x1a, r24	; 26
  4c:	e0 e6       	ldi	r30, 0x60	; 96
  4e:	f0 e0       	ldi	r31, 0x00	; 0
  50:	9f ef       	ldi	r25, 0xFF	; 255
  52:	9b bb       	out	0x1b, r25	; 27 === Cycle 0   ===
  54:	81 91       	ld	r24, Z+		; load needs 2 cycles
  56:	8b bb       	out	0x1b, r24	; 27 === Cycle 3   ===
  ...               	nop			;    === Cycle 3+n ===
  58:	1b ba       	out	0x1b, r1	; 27 === Cycle 4+n ===
  5a:	81 e0       	ldi	r24, 0x01	; 1
  5c:	e0 32       	cpi	r30, 0x20	; 32
  5e:	f8 07       	cpc	r31, r24
  60:	a8 f3       	brcs	.-16     	; 0x52 <main+0xa> === Cycle 8+n, plus another 2 cycles to jump to beginning of the loop ===
  62:	ff cf       	rjmp	.-2      	; 0x68 <main+0x20>
	

Problem:

• It takes at least 3 cycles to be able to send the data bit after pull the signal high. This makes driving XL-5050RGBW-WS2812B-HM with 8MHz clock impossible, but Worldsemi WS2812B is OK.
• It takes 5 cycles between pulling the signal low for current bit and pulling the signal high for next bit. The for loop requires us to check for the boundary p < &(data[SIZE]). Because the address is 16-bit long, AVR needs multiple cycles to perform the compute.

But... What if we can rearrange the instructions to perform the index check while the CPU is idling for timing (the nop instructions)?

Be Fast!

2.c

#define SIZE (24 * 8) // 24 bits/LED

#include <avr/io.h>
uint8_t data[SIZE];

__attribute__((naked)) void burst(uint8_t* start, uint8_t* end) {
	asm(
		"movw	r30, r24\n\t"		// First argument in r25:r24, r31:r30 (Z) are call-used regs
		"ldi	r24, 0xFF\n\t"		// R24 is call-used, content in R24 copied to R30 and no loinger required
		// Loop starts
		"1:	\n\t"
		"out	%[port], r24\n\t"	// Cycle 0
		"ld	r25, Z+\n\t"		// R25 is call-used (load requires 2 cycles)
		"out	%[port], r25\n\t"	// Cycle 3
		"cp	r30, r22\n\t"		// Second argument in r23:r22
		"cpc	r31, r23\n\t"
		"out	%[port], r1\n\t"	// Cycle 6, R1 is always 0, OUT instruction will NOT clob zero flag
		"nop	\n\t"
		"nop	\n\t"
		"brne	1b\n\t"			// Cycle 9 and 10 (branch requires 2 cycles)
		"ret	\n\t"
		:
		: [port] "I" (_SFR_IO_ADDR(PORTA))
	);
}

void main() {
	DDRA = 0xFF;
	burst(data, &(data[SIZE]));
	for(;;);
}
		

00000048 <burst>:
  48:	fc 01       	movw	r30, r24
  4a:	8f ef       	ldi	r24, 0xFF	; 255
  4c:	8b bb       	out	0x1b, r24	; 27
  4e:	91 91       	ld	r25, Z+
  50:	9b bb       	out	0x1b, r25	; 27
  52:	e6 17       	cp	r30, r22
  54:	f7 07       	cpc	r31, r23
  56:	00 00       	nop
  58:	00 00       	nop
  5a:	1b ba       	out	0x1b, r1	; 27
  5c:	c1 f3       	brne	.-18     	; 0x4c <burst+0x4>
  5e:	08 95       	ret

00000060 <main>:
  60:	8f ef       	ldi	r24, 0xFF	; 255
  62:	8a bb       	out	0x1a, r24	; 26
  64:	60 e2       	ldi	r22, 0x20	; 32
  66:	71 e0       	ldi	r23, 0x01	; 1
  68:	80 e6       	ldi	r24, 0x60	; 96
  6a:	90 e0       	ldi	r25, 0x00	; 0
  6c:	ee df       	rcall	.-38     	; 0x48 <burst>
  6e:	ff cf       	rjmp	.-2      	; 0x6e <main+0xe>
		

We successfully satisfy the timing requirement.

Word Format Converter

Since we are using parallel design, we will have to convert the signal from the original GRB8.

Following C code shows how to perform the conversion:

#include <stdio.h>
#include <stdint.h>
#include <stdlib.h>
#include <errno.h>

typedef struct __attribute__((packed)) RGB {
	uint8_t r, g, b;
} RGB;
typedef struct __attribute__((packed)) Lane {
	uint8_t g[8];
	uint8_t r[8];
	uint8_t b[8];
} Lane;

int main(int argc, char* argv[]) {
	if (argc != 7) {
		fprintf(stderr, "Use: this leds segments lines frames source dest, (%d given)\n", argc);
		return 1;
	}
	int led = atoi(argv[1]);
	int segment = atoi(argv[2]);
	int line = atoi(argv[3]);
	int frame = atoi(argv[4]);
	fprintf(stderr, "%d LEDs per segment, %d segments, %d bits buffer, %d lines, %d frames\n", led, segment, led * segment * 24, line, frame);

	uint8_t* bin = malloc(led * segment * 3);
	uint8_t* bout = malloc(led * segment * 3);
	FILE* fin = fopen(argv[5], "rb");
	FILE* fout = fopen(argv[6], "wb");
	int pRead[segment]; // Offset in bit (not byte)
	int pWrite;

	for (int iframe = 0; iframe < frame; iframe++) {
		for (int iline = 0; iline < line; iline++) {
			pWrite = 0;
			for (int isegment = 0; isegment < segment; isegment++) {
				pRead[isegment] = isegment * led * 24; // Each segment has 24 * led bits
			}
			fread(bin, 3, led * segment, fin);
			for (int iled = 0; iled < led; iled++) {
				for (int ibit = 0; ibit < 24; ibit++) {
					for (int isegment = 0; isegment < segment; isegment++) {
						int readIdx = pRead[isegment] >> 3;
						int readBit = 7 - (pRead[isegment] & 0b111);
						uint8_t x = ( bin[readIdx] >> readBit ) & 1;
						pRead[isegment]++;
						//fprintf(stderr, "Read %d: Byte %d, bit %d: %d\n", ibit, readIdx, readBit, x);
						int writeIdx = pWrite >> 3;
						int writeBit = 7 - (pWrite & 0b111);
						uint8_t write = bout[writeIdx];
						write &= ~(1<<writeBit);
						write |= x << writeBit;
						bout[writeIdx] = write;
						pWrite++;
					}
				}
			}
			fwrite(bout, 3, led * segment, fout);
			for (int i = 0; i < 3 * led * segment; i++) {
				fprintf(stderr, "Write %d:\t", i);
				for (int j = 7; j >= 0; j--) {
					fprintf(stderr, "%c", '0' + ((bout[i] >> j) & 1));
				}
				fprintf(stderr, "\n");
				if (i % 8 == 0b111) fprintf(stderr, "\n");
			}
		}
	}

	free(bin);
	free(bout);
	fclose(fin);
	fclose(fout);
	return 0;
}
	

Compile with gcc -O3 image.c -o image

Assume we have 24 LEDs in 8 segments (so, 3 LEDs each segment). If we save the original GRB8 data in a file named test.in, and we are planning to generate the processed data in test.out, we can use the command: ./image 3 8 1 1 test.in test.out.

ATtiny Family MCU Selection

For maximum performance, we will need to use a MCU with at least one full 8-bit IO port.

According to my another blog, we have the following options:

• ATtint25 has only 5 IOs.
• ATtiny24 (or ATtiny441) has 12 IOs in 2 ports 8 in port A, 4 in port B. It will work, but, leaving limited pins for other functionality (communication is on port A).
• ATtiny261 is a nice choice. We can use port A for LED data output; port B for other purposes, such as receiving data using USI.
• ATtiny2313 is a nice choice. We can use port B for LED data output; port A and port D for other purposes, such as receiving data using USART.

Memory Size Selection

To satisfy the tight timing requirement, ee will need to save the color data into SRAM buffer first, then burst output the data in the buffer.

Since each LED word is 24 bits and we are dividing the light bar into 8 segments, every 8 LEDs will need 24 bytes of buffer.

That means, theoretically, the maximum number of LEDs the ATtiny MCU could allow is:

If you want larger buffer size, consider ATmega.

You may fabricate PCB and solder the LEDs on (if you really enjoy working with SMDs). However, probably the easiest way to make a WS2812-based light bar is to buy the commonly-used cost-effective light stripe, then stick it on a hard wood or metal plate.

These light stripes may have different densities, most common ones include 144 LEDs per meter, 60 LEDs per meter and 30 LEDs per meter. The following table helps you choose the right LED stripe according to your dimension requirement.

Test Circuit

Now, we will build a 4-LED PCB test unit. This simulate a 1-segment 4-LED unit. Following diagram shows the PCB design, you can also cut a section of WS2812 stripe to build the test unit.

We will connect the unit to a ATtiny44 MCU. The data input pin of the test unit will be connected to port A pin 0 of the MCU, which simulates segment 0.

All LEDs On with Different Color

#define SIZE (24 * 3) // 24 bits/LED, 8 segment, 3LEDs per segment

#include <avr/io.h>

uint8_t data[SIZE] = {
//	MSB 7 6     5     4     3     2     1     0 LSB
	
	/* LED 0 */
	0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, //Green
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Red
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Blue
	/* LED 1 */
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Green
	0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Red
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Blue
	/* LED 2 */
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Green
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Red
	0x55, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Blue
	
	/* Parallel design, each bit in a byte represents a segment */
};

__attribute__((naked)) void burst(uint8_t* start, uint8_t* end) {
	asm(
		"movw	r30, r24\n\t"		// First argument in r25:r24, r31:r30 (Z) are call-used regs
		"ldi	r24, 0xFF\n\t"		// R24 is call-used, content in R24 copied to R30 and no loinger required
		// Loop starts
		"1:	\n\t"
		"out	%[port], r24\n\t"	// Cycle 0
		"ld	r25, Z+\n\t"		// R25 is call-used
		"out	%[port], r25\n\t"	// Cycle 3
		"cp	r30, r22\n\t"		// Second argument in r23:r22
		"cpc	r31, r23\n\t"
		"out	%[port], r1\n\t"	// Cycle 6, R1 is always 0, OUT instruction will not clob zero flag
		"nop	\n\t"
		"brne	1b\n\t"			// Cycle 7 and 8
		"ret	\n\t"
		:
		: [port] "I" (_SFR_IO_ADDR(PORTA))
	);
}

int main() {
	DDRA = 0xFF;
	PORTA = 0x00;
	
	for (uint8_t d = 0; ; d++) {
		burst(data, &(data[SIZE]));
		
		for (uint32_t i = 0; i < 100000; i++); // Reset
	}
	
	return 0;
}
	

In the above example, we are driving 24 LEDs divided into 8 segments (So, 3 LEDs in each segment). We save the color data in array data[SIZE].

/* LED 0 */
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, //Green
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Red
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Blue
	

The first 24 bytes contains the data for the first LED in each segment. Bit 0 of each byte for segment 0, bit 1 of each byte for segment 1, and so on...

In this example, the MCU will write 11111111 00000000 00000000 to all segments. This will turn the green color at maximum intensity.

/* LED 1 */
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Green
0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Red
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Blue
	

The second 24 bytes contains the data for the second LED in each segment.

In this example, the MCU will write 00000000 10000000 00000000 to all segments. This will turn the red color at half intensity.

/* LED 2 */
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Green
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Red
0x55, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //Blue
	

The third 24 bytes contains the data for the third LED in each segment.

We will need to look this example bitwisely. Because the first byte in bule channel is 0x55 (0b01010101), the MCU will write 00000000 00000000 10000000 to segment 0, 2, 4, 6; 00000000 00000000 00000000 to segment 1, 3, 5, 7. This will turn the bule color at half intensity for even segments; off for odd segments.

Since the buffer is 72 bytes large, the MCU will output 72 bits on each segment. Each LED will consume 24 bits of data; therefore, any LED after the 3rd LED will receive no data.

Program the MCU, we can see the first LED is green with maxmium intensity, the second and third LEDs are red and blue with half intensity.

Blinking LED

int main() {
	DDRA = 0xFF;
	PORTA = 0x00;
	
	for (uint8_t d = 0; ; d++) {
		data[0] = ~data[0];
		burst(data, &(data[SIZE]));
		for (uint32_t i = 0; i < 100000; i++); // Reset
		data[32] = ~data[32];
		burst(data, &(data[SIZE]));
		for (uint32_t i = 0; i < 100000; i++); // Reset
		data[64] = ~data[64];
		burst(data, &(data[SIZE]));
		for (uint32_t i = 0; i < 100000; i++); // Reset
	}
	
	return 0;
}
	

In this example, the MCU will toggle the MSB (first bit) of LED 0 green, LED 1 red and LED 2 blue, it will cause the LEDs in segment 0 light in the following patterns in loop:

Now, program the MCU.

We can confirm the LEDs light on and off same as the pattern table above. Note the green intensity change.