/heatshrink-integration

name: heatshrink-integration
description: Use when integrating or debugging heatshrink embedded compression — encoder/decoder sink/poll/finish loops, window/lookahead sz2, HSER/HSDR codes, or static vs dynamic alloc

heatshrink Integration

Overview

Use this skill to integrate heatshrink (`github.com/atomicobject/heatshrink`) by fixing memory budget, `window_sz2`/`lookahead_sz2` sizes, the sink/poll/finish streaming loop, and decompression safety. Compression bugs usually come from mismatched encoder/decoder settings, an unfinished poll loop, or output buffers that are too small.

When To Use

Use this skill when:

• The user wants heatshrink compression/decompression on an MCU.
• The task involves compressed logs, resources, firmware chunks, OTA payloads, or serial transfer compression.
• Decompression fails, output is truncated, memory is too high, or compressed data is incompatible.
• The project uses `heatshrink_encoder.h`, `heatshrink_decoder.h`, `heatshrink_config.h`, or the `heatshrink` command-line tool.

Do not use this skill for general archive formats like gzip/zip unless heatshrink is specifically involved.

First Questions

Ask for:

• Use case: logs, UI assets, firmware chunks, telemetry, or storage.
• Encoder/decoder settings: `window_sz2` (4-15) and `lookahead_sz2` (3 to `window_sz2 - 1`). The CLI's compiled default is `-w 11 -l 4`; its help text recommends `-w 8 -l 4` for embedded systems.
• Allocation model: `HEATSHRINK_DYNAMIC_ALLOC` (heap via `HEATSHRINK_MALLOC`/`HEATSHRINK_FREE`) or static (`HEATSHRINK_STATIC_WINDOW_BITS`, `HEATSHRINK_STATIC_LOOKAHEAD_BITS`, `HEATSHRINK_STATIC_INPUT_BUFFER_SIZE`).
• Streaming or one-shot mode, and input/output chunk sizes plus decompressed size bound.
• Whether compressed data comes from host tools or target firmware.
• Current return code or mismatch symptom.

Integration Checklist

1. Match settings across the boundary. Decoder `expansion_buffer_sz2` and `lookahead_sz2` must match the encoder's `window_sz2`/`lookahead_sz2`. Under static alloc, both sides must share the same `HEATSHRINK_STATIC_WINDOW_BITS`/`HEATSHRINK_STATIC_LOOKAHEAD_BITS`.

2. Choose the allocation model. Dynamic: `heatshrink_encoder_alloc(window_sz2, lookahead_sz2)` / `heatshrink_decoder_alloc(input_buffer_size, expansion_buffer_sz2, lookahead_sz2)`, freed with `*_free`. Static: set `HEATSHRINK_DYNAMIC_ALLOC 0` in `heatshrink_config.h` and use a stack/BSS instance, `*_reset` before reuse.

3. Drive the streaming loop correctly. Feed with `heatshrink_encoder_sink`/`heatshrink_decoder_sink` (check `*input_size` for bytes consumed; re-sink the remainder). Then loop `*_poll` until it returns `HSER_POLL_EMPTY`/`HSDR_POLL_EMPTY` before sinking more.

4. Flush at end of stream. After the last input, call `heatshrink_encoder_finish`/`heatshrink_decoder_finish`; while it returns `HSER_FINISH_MORE`/`HSDR_FINISH_MORE`, keep calling `*_poll` to drain output. Done is `HSER_FINISH_DONE`/`HSDR_FINISH_DONE`. Call `*_reset` before reusing the instance for a new stream.

5. Validate data integrity. Pair compression with CRC/hash when corruption matters. heatshrink carries no checksum or length header and does not reliably detect corrupt or truncated input, so integrity must be checked externally.

6. Test worst case. Some data expands; do not assume size savings. Size the output buffer/store for expansion, not just the compressed happy path.

Common Failures

• Host encoder uses different `window_sz2`/`lookahead_sz2` than the MCU decoder (or mismatched `HEATSHRINK_STATIC_*`).
• Caller stops after one `*_poll` and treats partial output as complete, instead of looping until `HSER_POLL_EMPTY`/`HSDR_POLL_EMPTY`.
• `*_finish` never called (or its `HSER_FINISH_MORE`/`HSDR_FINISH_MORE` output not drained), so the tail of the stream is lost.
• Sinking more data on the encoder after `heatshrink_encoder_finish` without `heatshrink_encoder_reset` (returns `HSER_SINK_ERROR_MISUSE`).
• Ignoring `*input_size` from `*_sink` and dropping the unconsumed bytes.
• Truncated/corrupt compressed input produces silent garbage rather than an error, because heatshrink has no integrity check; `*_SINK_ERROR_NULL`/`*_POLL_ERROR_NULL` only guard null handles or buffers, and `HSDR_POLL_ERROR_UNKNOWN` is an internal-state guard, not a corruption detector.
• Compressed firmware lacks CRC before flash write; worst-case expansion exceeds allocated storage.

Verification

Before claiming heatshrink works:

• State `window_sz2`/`lookahead_sz2`, allocation model (`HEATSHRINK_DYNAMIC_ALLOC`), decoder `input_buffer_size`, and buffer sizes.
• Confirm the poll loop drains to `*_POLL_EMPTY` and the finish loop drains `*_FINISH_MORE` to `*_FINISH_DONE`.
• Confirm a round-trip test for representative and worst-case (incompressible) data.
• Confirm that corrupt/truncated input is caught by an external integrity check, since heatshrink itself may emit silent garbage without an error code.
• Confirm the integrity check if used for firmware or persistent assets.

Example

User:

用 heatshrink 压缩资源，设备端解压出来缺尾巴。

Agent:

1. Asks for `window_sz2`/`lookahead_sz2`, decoder `input_buffer_size`/`expansion_buffer_sz2`, chunk sizes, and whether `heatshrink_decoder_finish` is called. 2. Checks that `*_poll` loops until `HSDR_POLL_EMPTY` and that `finish` is drained until `HSDR_FINISH_DONE` (the missing tail is almost always an undrained finish loop). 3. Verifies round-trip and truncated-input behavior, and that `heatshrink_decoder_reset` runs before reusing the instance.