Support streaming decompression

[LordMike]

The problem

Today, the OD firmware allocates a buffer of about 50 KB. This is a static buffer, always allocated - which also means some build targets cannot support compression. The flow of data is then that a client starts image transferring, and streams compressed image data into the buffer. The buffer then holds the full image, compressed, before it on image completion then decompresses the entire buffer in one go and streams it to the panel IC.

The reason it does this, is mostly due to the API. The uzlib implementation does not offer an easy way to "push" data (as we receive it from the BLE connection) through decompression, and into the panel.

This issue is to gather information on what can be done. I will group options into two:

• Keeping the existing zlib approach. This can mostly be done without protocol changes at all, as the change is purely MCU side.
• Introduce new compression algorithms

The Zlib approach

We keep zlib as is and improve it. This is protocol compatible and just improves the MCU side. Clients (like the HA integration) that do logic to decide when to send data will have to change a bit, as they can now send more compressed data to OD than before - with a slight risk that older MCU firmwares will fail.

All zlib-compatible options have the same core memory constraint: Deflate can refer back into a sliding history window. Normal zlib streams often use 32 KB (windowBits=15), but the client can compress with a smaller window:

windowBits	History window
9	512 B
10	1 KB
11	2 KB
14	16 KB
15	32 KB

If we exposed windowBits (a protocol change, either as new algorithms like ZIP_SMALL, or as compressionBuffer=9), we could graduate the window from the client side, and do best compression. We should see better compression ratios, with larger window sizes.

uzlib

Details

• Pro: Already integrated and MCU-friendly.
• Pro: Small fixed decompressor state, roughly 1.3 KB, plus the selected dictionary/window.
• Con: Pull-style API; no clean “need more input” result.
• Con: True packet-driven streaming likely needs awkward buffering/task logic or a small uzlib fork.

Best fit if we prioritize low fixed RAM and want to keep the current dependency. For clean streaming from BLE/WiFi packets, we would likely need to patch/wrap uzlib so temporary input exhaustion is resumable instead of being treated as EOF/error.

Miniz / tinfl

Details

• Pro: Real push-style incremental API with “needs input” / “has output” states.
• Pro: Maps cleanly to BLE/WiFi packets and direct panel SPI output.
• Con: Larger fixed decompressor state, roughly 8-11 KB.
• Con: Likely too heavy for the 24 KB RAM target unless combined with small-window streams.

Best fit if we want the cleanest implementation for normal nRF/ESP targets. We can feed packet bytes into tinfl, write produced bytes directly to the panel, and remove the full compressed-image buffer.

G5 / Group5

• Pro: Very small decoder target; designed for constrained MCUs and no 32 KB Deflate window.
• Pro: Supports 1bpp directly and 4-color output as two separately compressed 1bpp planes.
• Con: Not push-style as-is; current decoder takes a full compressed buffer pointer and decodes one output line at a time.
• Con: Does not support native 4bpp / 16-color images; its “4 color” and 4GRAY modes are effectively 2bpp split into two 1bpp planes.

bitbank2 (who also makes the bb_epaper library) has experimented with image compression and touts some impressive numbers. Best fit as a new low-memory compression mode, especially for the 24 KB target. We would need protocol/client changes and a firmware decoder adaptation that reads compressed bytes from a small input ring instead of a full buffer.

Notes from the repo: README says G5 is a lossless 1bpp format, with three/four-color support implemented as two compressed 1bpp images. The code exposes decodeLine(), stores current/reference line flip arrays, and the converter modes are BW, BWR, BWYR, and 4GRAY.

heatshrink

• Pro: Designed for embedded streaming; API is explicitly sink input, poll output, then finish.
• Pro: Very small decoder state; RAM is mostly 2^window_sz2 history plus a configurable input buffer.
• Pro: Works on arbitrary bytes, so it can handle 1bpp, 2bpp, 4bpp, etc. without image-specific changes.
• Con: Not zlib-compatible, so this requires a new protocol mode and client-side encoder support.
• Con: Compression ratio is likely worse than zlib on many images; needs testing with real OD payloads.

Best fit for the smallest targets and for clean packet-driven decompression. Firmware would feed BLE/WiFi chunks into heatshrink_decoder_sink(), drain output with heatshrink_decoder_poll(), and write produced bytes directly to panel SPI. Encoder/decoder settings like window_sz2 and lookahead_sz2 must be agreed by protocol/capability negotiation.

[LordMike]

I put a bot on the task and arrived at the below.

I did a compression benchmark here: https://github.com/LordMike/opendisplay-compression-benchmark; the results for this post are here: https://github.com/LordMike/opendisplay-compression-benchmark/tree/cddb95e3d830a34d21ee16ba5549b236ad35cfff/results/run-20260508-035515

The test corpus currently contains 489 PNG source/generated images across 15 resolutions. From those I generated:

• 900 .bs-od files for the current OpenDisplay pixel-stream layout - this is what we would stream to the MCU in the color scheme chosen
• 900 .bs-1bppstreams files for G5-compatible per-plane input - G5 is a bit special, and wants series of individual planes, so the stream is different.
• 9000 compression tests in total, across zlib/heatshrink/g5.

Tested variants:

• zlib
  • current: current firmware-style zlib settings; best baseline for comparing against what we already do today.
  • l9-ws9: high compression level, 512 byte window; smallest zlib memory-oriented variant tested.
  • l9-ws12: high compression level, 4 KB window; middle-ground variant with much lower decoder window memory than current.
  • l9-ws15: high compression level, 32 KB window; largest-window zlib variant and generally best compression ratio.
• heatshrink
  • w9-l4: 512 byte window, 16 byte lookahead; smallest heatshrink memory-oriented variant tested.
  • w11-l5: 2 KB window, 32 byte lookahead; middle-ground heatshrink variant.
  • w13-l6: 8 KB window, 64 byte lookahead; largest heatshrink variant tested and generally best heatshrink compression ratio.
• G5
  • virtual-f64: treats the input as one virtual stream and allows up to 64 flips per row; smallest/strictest G5 variant, but failed most often.
  • perplane-f128: converts the image into separate 1bpp planes and allows up to 128 flips per row; closer to how G5 expects image data.
  • perplane-f256: per-plane encoding with up to 256 flips per row; most permissive G5 variant tested, but still failed many inputs and expanded badly on noisy/dithered cases.

Headline result: zlib is clearly the best general-purpose option. zlib.l9-ws15 had the best weighted compression ratio overall at 24.9%, but the current zlib setup was very close at 25.3% and much faster due to the lower level of 6. zlib.l9-ws12 was also very close at 25.6%, which is interesting because it would imply a 4 KB decompression window instead of 32 KB - interestingly, we don't lose a lot of compression ratio, even if we turn down the windowSize to 9 (ie. 512 bytes).

Best reliable weighted ratios:

Variant	Ratio
zlib.l9-ws15	24.9%
zlib.current	25.3%
zlib.l9-ws12	25.6%
zlib.l9-ws9	26.9%
heatshrink.w13-l6	32.8%
heatshrink.w11-l5	35.3%
heatshrink.w9-l4	38.4%

G5 was not reliable for this use case. It only succeeded on 661 / 2700 attempted scenarios, with failures mostly caused by rows exceeding the configured flip limit. Some G5 results are good on very simple line-art-like inputs, but it expands badly on other cases, especially checkerboards/dither-like mono input.

Some observations:

• Clean generated/UI-style imagery compressed very well with zlib: about 13.0%.
• Real/photo-derived imagery was much worse: about 38.5% with best zlib.
• Stress-test random/noise data is basically incompressible, as expected. Zlib stays around 100%, while heatshrink can expand to around 108-112%.
• Dithered photo variants are significantly worse than clean quantized/palette-style inputs. Mono dithered photos are especially bad, often around 70-80% even with zlib.
• Heatshrink did not beat zlib on any logical input in this corpus.
• The most interesting firmware tradeoff seems to be zlib with reduced windowBits, especially ws12: very close to current compression ratio, but with a much smaller decompression window requirement.

My current conclusion from the benchmark is that zlib still looks like the right baseline. The strongest practical candidate is probably not a new algorithm, but keeping zlib and testing whether a smaller negotiated windowBits value gives us the memory reduction we need without sacrificing too much compression.

[LordMike]

Dev diary: follow-up compression tests

Since the first benchmark comment, I expanded the benchmark quite a bit. The current result set is here:

https://github.com/LordMike/opendisplay-compression-benchmark/tree/0b19a74d859abf2a596ce66e78d46ce08cb906d9/results/run-20260508-full

The corpus is still the same shape: 489 source images across 15 resolutions, producing 900 .bs-od streams and 900 G5-style .bs-1bppstreams. The full result set now has 34,200 rows. All non-G5 codecs completed successfully; G5 still only succeeded on 661 / 2700 cases.

What was added

After the first zlib/heatshrink/G5 pass, I added:

• More zlib variants: l1/l6/l9 at ws9 and ws10, plus the previous ws12, ws15, and current.
• Brotli: q9-w10, q9-w12, q9-w15.
• Zstd: l19-w10, l19-w12, l19-w15.
• LZ4 and LZ4HC: block sizes 512, 1024, 16K, 32K.
• lzssraw: a simple custom LZSS-ish raw-run experiment with small windows.
• heatshrinkraw: a heatshrink-style experiment where zero-length backrefs are reused as raw-run markers.

All timings are averaged over 10 compression runs on the host machine. They are mostly useful for relative sender-side cost, not MCU decode cost.

Updated headline numbers

Best reliable weighted ratios:

Variant	Weighted ratio	Avg compress time
zstd.l19-w15	23.88%	25.79 ms
brotli.q9-w15	24.51%	8.84 ms
zlib.l9-ws15	24.88%	37.15 ms
brotli.q9-w12	24.92%	5.72 ms
zstd.l19-w12	25.13%	20.94 ms
zlib.current	25.34%	6.70 ms
zlib.l9-ws12	25.58%	12.29 ms
brotli.q9-w10	25.72%	4.41 ms
zlib.l9-ws10	26.52%	8.54 ms
zlib.l9-ws9	26.94%	10.38 ms

The surprising result is still how well small-window zlib holds up. zlib.l9-ws9 uses a 512 byte DEFLATE window and is only about 1.6 percentage points worse than the current zlib setup on weighted ratio. ws10 is slightly better again.

Notes by codec

zlib still looks like the strongest practical baseline. The important result is not that ws15 wins, but that ws9/ws10/ws12 are all close enough to be interesting. If decoder memory is the main constraint, negotiated windowBits still looks like the best first path.

Brotli did better than expected. brotli.q9-w10 is close to current zlib while using a 1 KB window setting. This may be worth investigating, but only if the embedded decoder memory/code-size story is acceptable. The window is not the whole decoder cost.

Zstd got the best ratio at larger window sizes, but the small-window variant was not better than zlib or Brotli. I do not currently see it as the best fit for very small MCUs.

LZ4/LZ4HC are very fast but compress much worse. Even LZ4HC with 512 byte blocks landed around 42.8%, so it does not look worthwhile for this problem unless speed becomes vastly more important than transfer size.

LZSS-Raw was useful as an experiment, but not a replacement. Small windows make the decoder simple, but the ratio is much worse than zlib. The best tested LZSS-Raw variant was around 35.8%.

heatshrinkraw was a test of a possible heatshrink format fix: using a zero-length backref as a raw-run marker. I wrote that up upstream here: atomicobject/heatshrink#99

That fix addresses the worst thing about heatshrink: incompressible data no longer trends toward 112.5% expansion as badly, because long literal spans can be batched as raw runs. It still does not beat zlib overall, but it makes heatshrink much less awkward as a tiny-decoder option.

G5 remains unsuitable as a general-purpose option here. It can be good on simple compatible inputs, but the failure rate and expansion cases are too awkward.

Current conclusion

The realistic candidates now seem to be:

1. zlib with a smaller negotiated window, probably ws9 or ws10.
2. heatshrink with a raw-run fix, if we value tiny decoder state/code size over compression ratio.

I would not spend more time on G5, LZ4, plain LZSS, Brotli, or Zstd for the main firmware path unless the constraints change. Brotli/Zstd can produce good ratios, but the decoder-side memory/code-size story is likely worse than the table suggests.