heatshrink

Introduction

heatshrink [1] is a data compression and decompression library for embedded and real-time systems, written by Scott Vokes at Atomic Object. It is based on LZSS and is designed for very low memory usage (as low as 50 bytes of RAM), incremental and bounded CPU use, and either static or dynamic memory allocation.

The heatshrink Zephyr module [2] is a fork of the original project maintained by Kickmaker. It adds the Zephyr integration (Kconfig options, CMake build rules and samples) on top of the upstream library; the compression code itself comes from the original heatshrink project.

The heatshrink library is licensed under the ISC license. The Zephyr integration files are licensed under the Apache-2.0 license.

Usage with Zephyr

To pull in heatshrink as a Zephyr module, either add it as a West project in the west.yml file or pull it in by adding a submanifest (e.g. zephyr/submanifests/heatshrink.yaml) file with the following content and run west update:

manifest:
  projects:
    - name: heatshrink
      url: https://github.com/kickmaker/heatshrink.git
      revision: zephyr
      path: modules/lib/heatshrink # adjust the path as needed

Enable the library with CONFIG_HEATSHRINK. By default, the encoder and decoder use statically allocated state whose window and lookahead sizes are set at build time through CONFIG_HEATSHRINK_STATIC_WINDOW_BITS and CONFIG_HEATSHRINK_STATIC_LOOKAHEAD_BITS. Data must be decoded with the same parameters that were used to encode it. CONFIG_HEATSHRINK_DYNAMIC_ALLOC allows these parameters to be selected at runtime instead, at the cost of requiring a heap. CONFIG_HEATSHRINK_ENCODER and CONFIG_HEATSHRINK_DECODER can be disabled individually to reduce the footprint.

Refer to the heatshrink_encoder.h and heatshrink_decoder.h headers, the heatshrink Zephyr module [2] documentation and the provided heatshrink sample [3] for API details.

References