ESP32-targz Arduino Library

Use the TarGzUnpacker class to unpack a .tar.gz archive. You can choose between two modes:

1. With intermediate file: Uses a temporary file (default is /tmp/tmp.tar) during the process.
2. Without intermediate file: Direct expansion (uses more heap memory).

Note: For ESP32, direct expansion from a Stream (like an HTTP stream) is also supported via tarGzStreamExpander.

// mount spiffs (or any other filesystem)
tarGzFS.begin();

TarGzUnpacker *TARGZUnpacker = new TarGzUnpacker();

TARGZUnpacker->haltOnError( true );
TARGZUnpacker->setTarVerify( true );
TARGZUnpacker->setupFSCallbacks( targzTotalBytesFn, targzFreeBytesFn );
TARGZUnpacker->setGzProgressCallback( BaseUnpacker::defaultProgressCallback );
TARGZUnpacker->setLoggerCallback( BaseUnpacker::targzPrintLoggerCallback  );
TARGZUnpacker->setTarProgressCallback( BaseUnpacker::defaultProgressCallback );
TARGZUnpacker->setTarStatusProgressCallback( BaseUnpacker::defaultTarStatusProgressCallback );
TARGZUnpacker->setTarMessageCallback( BaseUnpacker::targzPrintLoggerCallback );

// using an intermediate file (default is /tmp/tmp.tar)
if( !TARGZUnpacker->tarGzExpander(tarGzFS, "/targz_example.tar.gz", tarGzFS, "/tmp") ) {
  Serial.printf("tarGzExpander+intermediate file failed with return code #%d\n", TARGZUnpacker->tarGzGetError() );
}

// or without intermediate file
if( ! TARGZUnpacker->tarGzExpander(tarGzFS, "/targz_example.tar.gz", tarGzFS, "/tmp", nullptr ) ) {
  Serial.printf("tarGzExpander+intermediate file failed with return code #%d\n", TARGZUnpacker->tarGzGetError() );
}

Use the TarUnpacker class to unpack a .tar archive to a destination directory.

Key features:

• setTarVerify(true): Enables health checks (slower process).
• setupFSCallbacks(...): Recommended to prevent partition overflow.
• setTarProgressCallback(...): Prints progress for individual files.
• setTarStatusProgressCallback(...): Prints filenames as they are expanded.

// mount spiffs (or any other filesystem)
tarGzFS.begin();

TarUnpacker *TARUnpacker = new TarUnpacker();

TARUnpacker->haltOnError( true ); // stop on fail (manual restart/reset required)
TARUnpacker->setTarVerify( true ); // true = enables health checks but slows down the overall process
TARUnpacker->setupFSCallbacks( targzTotalBytesFn, targzFreeBytesFn ); // prevent the partition from exploding, recommended
TARUnpacker->setTarProgressCallback( BaseUnpacker::defaultProgressCallback ); // prints the untarring progress for each individual file
TARUnpacker->setTarStatusProgressCallback( BaseUnpacker::defaultTarStatusProgressCallback ); // print the filenames as they're expanded
TARUnpacker->setTarMessageCallback( BaseUnpacker::targzPrintLoggerCallback  ); // tar log verbosity

if( !TARUnpacker->tarExpander(tarGzFS, "/tar_example.tar", tarGzFS, "/") ) {
  Serial.printf("tarExpander failed with return code #%d\n", TARUnpacker->tarGzGetError() );
}

Use the GzUnpacker class to decompress a single .gz file from a source filesystem to a destination filesystem.

Recommended steps:

1. Mount your filesystem using tarGzFS.begin().
2. Initialize GzUnpacker.
3. Set error handling, filesystem callbacks (to prevent partition overflow), and progress/logger callbacks.
4. Call gzExpander() to perform the extraction.

// mount spiffs (or any other filesystem)
tarGzFS.begin();

GzUnpacker *GZUnpacker = new GzUnpacker();

GZUnpacker->haltOnError( true ); // stop on fail (manual restart/reset required)
GZUnpacker->setupFSCallbacks( targzTotalBytesFn, targzFreeBytesFn ); // prevent the partition from exploding, recommended
GZUnpacker->setGzProgressCallback( BaseUnpacker::defaultProgressCallback ); // targzNullProgressCallback or defaultProgressCallback
GZUnpacker->setLoggerCallback( BaseUnpacker::targzPrintLoggerCallback  );    // gz log verbosity

// expand one file
if( !GZUnpacker->gzExpander(tarGzFS, "/gz_example.gz", tarGzFS, "/gz_example.jpg") ) {
  Serial.printf("gzExpander failed with return code #%d", GZUnpacker->tarGzGetError() );
}