DOCSEARCHbyAlgolia
Submit Docs

heatshrink Documentation

repository·master·Indexed 23 days ago

https://github.com/atomicobject/heatshrink

A data compression and decompression library designed for embedded and real-time systems. It prioritizes low memory usage and incremental, bounded CPU consumption, offering both a standalone command-line tool and a library API with support for dynamic or static memory allocation.

Tokens
743
Snippets
0
Records
4
Agent score
32%

What's inside heatshrink

  1. How to use the heatshrink encoder and decoder API

    master

    The encoder and decoder operate as state machines using a streaming pattern. Follow these steps to process data:

    1. Initialize: Allocate a heatshrink_encoder or heatshrink_decoder state machine using their respective alloc functions, or statically allocate one and call their reset function to initialize it.
    2. Sink Input: Use sink to feed an input buffer into the state machine. The input_size pointer argument will be updated to indicate how many bytes were actually consumed. If input_size is 0, the buffer is full.
    3. Poll Output: Use poll to move data from the state machine into an output buffer. The output_size pointer argument will be updated to indicate how many bytes were output. The return value indicates if further output is available.
    4. Finish Stream: When the input stream ends, call finish to notify the state machine. If finish indicates output remains, continue calling poll until it indicates the output is exhausted.

    Note: You cannot sink more data after calling finish without calling reset first.

  2. Integrate heatshrink into your project

    master

    You can use heatshrink as a standalone command-line tool or as a library. To use it as a library, copy the following files into your project:

    • heatshrink_common.h
    • heatshrink_config.h
    • Either heatshrink_encoder.c and heatshrink_encoder.h (for compression)
    • Or heatshrink_decoder.c and heatshrink_decoder.h (for decompression)

    If your project requires both encoding and decoding, you can build them as static libraries.

    Memory Allocation

    By default, the library uses dynamic memory allocation. For embedded environments where you prefer static allocation, set HEATSHRINK_DYNAMIC_ALLOC to 0 in heatshrink_config.h.

  3. Configure heatshrink window and lookahead sizes

    master

    The compression effectiveness and memory usage are controlled by the window and lookahead sizes. These are set during dynamic allocation or via heatshrink_config.h for static allocation.

    • window_sz2 (CLI flag: -w): Sets the window size to $2^W$ bytes. This determines how far back the algorithm searches for patterns.
      • Valid range: 4 to 15.
      • Example: 8 results in a 256-byte window ($2^8$).
    • lookahead_sz2 (CLI flag: -l): Sets the lookahead size to $2^L$ bytes. This determines the maximum length for detected repeated patterns.
      • Valid range: 3 to window_sz2 - 1.
      • Note: An overly large lookahead can reduce compression efficiency due to fixed bit-size overhead.

    Recommended Defaults for Embedded Systems:

    • window_sz2: 8 to 10.
    • lookahead_sz2: Approximately half of the window size (e.g., -w 8 -l 4 or -w 10 -l 5).

  4. Configure the decoder input buffer size

    master

    The input_buffer_size setting determines how large an input buffer the decoder uses.

    • Impact: It affects how much work the decoder can perform in a single step.
    • Trade-offs: A larger buffer uses more memory. An extremely small buffer (e.g., 1 byte) increases overhead due to frequent suspend/resume function calls but does not affect compression quality.