basic

# Basic Example

Minimal round-trip demo: compress a string with zstd, decompress it, verify the bytes match.

## What it demonstrates

- The one-shot zstd API (`ZSTD_compress` / `ZSTD_decompress`) with no advanced configuration
- The recommended embedded pattern: run zstd from a **dedicated worker task** with a measured stack budget, not from the main task
- Reporting stack high-water mark via `uxTaskGetStackHighWaterMark()` so you can right-size your task

This is the right starting point if you just want to confirm zstd works on your target and see baseline compression behaviour. It is **not** the right pattern for production code that compresses lots of small messages — see [`../dictionary`](../dictionary) for that.

## Build and run

```bash
idf.py set-target esp32        # or esp32s3, esp32c3, etc.
idf.py build
idf.py -p COMx flash monitor
```

## Expected output

```
I (xxx) zstd_example: Compressed 246 bytes -> 110 bytes (2.2x)
I (xxx) zstd_example: Decompressed 110 bytes -> 246 bytes
I (xxx) zstd_example: Round-trip match: YES
I (xxx) zstd_example: Free heap: 372000 bytes
I (xxx) zstd_example: Worker stack: 5588 / 16384 bytes used (10796 free)
```

## Why a worker task?

`ZSTD_compress` and `ZSTD_decompress` use several KB of stack inside their working buffers. The ESP-IDF main task defaults to 3,584 bytes — too small. Symptom: compression appears to succeed, then FreeRTOS reports `***ERROR*** A stack overflow in task main` at the next context switch.

The fix is **not** to bloat the main task; it's to do heavy work on a task you've sized appropriately:

```c
xTaskCreate(zstd_task, "zstd", 16384, NULL, 5, NULL);
```

After running once, check the `Worker stack: N / 16384 bytes used` line and trim the stack to the peak you actually observed plus a safety margin (~1–2 KB).

## What it does not cover

- Memory-conscious context reuse (each call here goes through the simple all-in-one entry point)
- Dictionary compression for small payloads
- Streaming compression / decompression

See [`../dictionary`](../dictionary) for the production-style pattern.