splink/README.md

# WS2812 driver gateware for blinkenwall v3

At 100 FPS, a single strand of WS2812 can only be just over 300 LEDs long:

```
MAX_LENGTH = (1 / FPS - RESET_TIME) / BIT_TIME / BITS_PER_PIXEL
318 = (1 / 100 - 50e-6) / 1.3e-6 / 24
```

Because blinkenwall v3 has `64 * 96 = 6144` pixels, driving it at 100 FPS requires at least
`6144 / 318 = 20` parallel drivers. For simplicity, the wall is devided into 24 strands of
256 LEDs. Unfortunately, most microcontrollers have at most a couple WS2812-capable interfaces
(typically SPI), so this would require coordinating several microcontrollers in parallel. A
much more integrated solution is to instantiate as many WS2812 drivers as desired in an FPGA,
then point the entire video firehose at the FPGA.

## Ethernet communication

The controller accepts UDP packets containing image data on port 61437 ("PIXEL"). Each packet
contains color data for one strand of LEDs.

The packet structure is as follows:

<table>
<tr>
	<th></th>
	<th>00</th>
	<th>01</th>
	<th>02</th>
	<th>03</th>
	<th>04</th>
	<th>05</th>
	<th>06</th>
	<th>07</th>
	<th>08</th>
	<th>09</th>
	<th>0a</th>
	<th>0b</th>
	<th>0c</th>
	<th>0d</th>
	<th>0e</th>
	<th>0f</th>
</tr>
<tr>
	<th>00</th>
	<td colspan="4">magic (<code>0x5049_584c</code>)</td>
	<td colspan="4">strand number</td>
	<td colspan="4">frame number</td>
	<td>0</td>
	<td>px1 R</td>
	<td>px1 G</td>
	<td>px1 B</td>
</tr>
<tr>
	<th>10</th>
	<td>0</td>
	<td>px2 R</td>
	<td>px2 G</td>
	<td>px2 B</td>
	<td>0</td>
	<td>px3 R</td>
	<td>px3 G</td>
	<td>px3 B</td>
	<td>0</td>
	<td>px4 R</td>
	<td>px4 G</td>
	<td>px4 B</td>
	<td colspan="4">...</td>
</tr>
</table>

Every packet begins with a magic number `0x5049584c` (ASCII for "PIXL"), followed by the strand
number and the frame number. All numbers are big endian. After the header follows the pixel data,
separated into one 4-byte word per LED.

Once all strands for a given frame number have been received and the video page has been flipped,
the controller answers with a confirmation packet:

<table>
<tr>
	<th></th>
	<th>00</th>
	<th>01</th>
	<th>02</th>
	<th>03</th>
	<th>04</th>
	<th>05</th>
	<th>06</th>
	<th>07</th>
	<th>08</th>
	<th>09</th>
	<th>0a</th>
	<th>0b</th>
	<th>0c</th>
	<th>0d</th>
	<th>0e</th>
	<th>0f</th>
</tr>
<tr>
	<th>00</th>
	<td colspan="4">frame number</td>
</tr>
</table>