heatshrink-ts

Typescript Decoder for Heatshrink

Introduction

Heatshrink is a compression library that can be used in very low resource microcontroller devices. It is based on LZSS encoding, which looks for repeated strings of characters and replaces them with references to a previous occurence rather than repeating them.

You can read more details at the repository for the original C implementation of heatshrink.

This typescript package only implements the heatshrink decoding process so it can decode compressed data that it receives from a device using the heatshrink library. It is written in typescript and distributed on NPM for easy installation and usage.

Installation and Basic Usage

npm install heatshrink-ts

The primary class is the HeatshrinkDecoder object that can take in compressed data and turn it back into uncompressed data.

import { HeatshrinkDecoder } from "heatshrink-ts";

const WINDOW_BITS = 8;
const LOOKAHEAD_BITS = 4;
const INPUT_BUFFER_LENGTH = 64;

// Heatshrink Encoded form of the ASCII string 'this is a test'
let encodedInput = new Uint8Array([0xba, 0x5a, 0x2d, 0x37, 0x39, 0x00, 0x08, 0xac, 0x32, 0x0b, 0xa5, 0x96, 0xe7, 0x74]);

let decoder = new HeatshrinkDecoder(WINDOW_BITS, LOOKAHEAD_BITS, INPUT_BUFFER_LENGTH);
decoder.process(encodedInput);

let output = decoder.getOutput();

// This will print 'Decoded output: this is a test'
let outputString = String.fromCharCode(...output);
console.log("Decoded output: " + outputString);

There are 2 key parameters that need to match between the encoder and decoder:

• The window size (WINDOW_BITS), which is a number between 4 and 15, inclusive that sets how large of a sliding window is used to look for repeated strings. It is internally considered as a power of 2, so the value 8 would be 2**8 or 256 bytes for the sliding window.

• The lookahead size (LOOKAHEAD_BITS), which is a number between 2 and 15, always strictly smaller than the window size. This sets how long of a repeated pattern the encoder can see and therefore compress. According to the heatshrink documentation, a good size is WINDOW_BITS / 2.

Important: Neither of these two parameters are transferred with heatshrink compressed data but they are required to decode it properly. You must magically know the right values for the encoder that was used to produce your encoded data or the decoding process will not produce the correct output.

The input buffer length can be whatever you want but a larger input buffer is a little more time efficient. 64 bytes is a reasonable value. This parameter will probably go away in the future since it is not so meaningful in a non-embedded context.

API Documentation

API Documentation can be found at: https://iotile.github.io/heatshrink-ts/