Using DSP Libraries with Zig on ESP32: Complete Integration Guide

The dsp.zig module in the kassane/zig-esp-idf-sample repository provides a thin, ergonomic Zig wrapper around Espressif's ESP-DSP C library, exposing FIR filters, FFTs, vector math, and matrix operations with compile-time safety and zero-copy memory handling.

This repository demonstrates how to leverage Espressif's optimized DSP primitives on ESP32 microcontrollers using the Zig programming language. By wrapping the ESP-DSP C library in idiomatic Zig APIs, you gain access to high-performance digital signal processing capabilities while maintaining Zig's memory safety guarantees and modern syntax.

Architecture and Module Structure

The integration follows a layered architecture that bridges Zig's module system with the ESP-IDF build infrastructure.

Core Components

At the heart of the implementation lies the main/imports/dsp.zig file, which defines high-level types including FirF32, FFT, Math, Matrix, and BiquadFilter. This wrapper performs automatic error handling via errors.espCheckError, converting low-level C return codes into Zig error unions.

The sys module provides auto-generated bindings to the underlying ESP-DSP C API, exposing functions like sys.dsps_fir_init_f32 and sys.fft2r_*. These bindings are generated at build-time from the ESP-DSP headers downloaded by the IDF build system.

Build System Integration

In build.zig, the DSP module is registered in the module_specs table with explicit dependencies:

.{
    .name = "dsp",
    .deps = &.{ "sys", "error" },
},

The idf_wrapped_modules function (lines 18-45 in build.zig) resolves these dependencies and re-exports the DSP module through the top-level esp_idf umbrella. This ensures that when you import esp_idf, the dsp namespace is available alongside other ESP-IDF functionalities.

Setting Up DSP Dependencies

Before using DSP functions, you must ensure the ESP-DSP library is available in your build environment. The repository handles this through the ESP-IDF component manager:

1. Run idf.py add-dependency espressif/esp-dsp to fetch the C library
2. The build system automatically generates sys.zig bindings from the DSP headers
3. Import the module via const dsp = @import("esp_idf").dsp;

The dependency resolution guarantees that sys and error modules are compiled and available before the dsp wrapper attempts to link against them.

Practical DSP Operations with Zig

The following examples demonstrate practical usage patterns from main/examples/dsp-math.zig, showing how to implement common signal processing tasks using the Zig wrapper.

FIR Filter Implementation (FirF32)

Finite Impulse Response filters provide stable, linear-phase filtering essential for audio and sensor applications. The FirF32 type manages delay lines and coefficient arrays with automatic memory alignment:

const dsp = @import("esp_idf").dsp;

// Coefficients for a 5-tap low-pass FIR
const coeffs = [_]f32{ 0.2, 0.2, 0.2, 0.2, 0.2 };
var delay = [_]f32{0} ** 5;

var fir = try dsp.FirF32.init(&coeffs, &delay);
defer fir.deinit() catch {};

var input = [_]f32{ 1, 2, 3, 4, 5, 6, 7, 8 };
var output: [input.len]f32 = undefined;

try fir.process(&input, &output);

The init method (defined in dsp.zig lines 75-88) validates that the coefficient and delay arrays match in length, returning an error if the constraint is violated. The process method (lines 97-100) calls the underlying sys.dsps_fir_f32 function while enforcing type safety.

Real-Valued FFT with Radix-2

For spectral analysis, the repository provides optimized FFT implementations that leverage the ESP32's DSP acceleration:

const dsp = @import("esp_idf").dsp;

const size: u32 = 256;  // Must be power-of-2
var table: [size]f32 = undefined;
try dsp.FFT.initRadix2F32(&table, size);
defer dsp.FFT.deinitRadix2F32();

var data: [size * 2]f32 = undefined;
for (data, 0..) |*v, i| {
    v.* = if (i % 2 == 0) @floatFromInt(i) else 0;
}

try dsp.FFT.fft2rF32(&data, size, &table);

This example initializes twiddle factors using initRadix2F32 (lines 135-138), prepares interleaved real/imaginary data, and executes the transform via fft2rF32 (lines 145-149). The wrapper ensures that input arrays meet the library's alignment requirements.

Vector Mathematics Operations

Basic linear algebra operations are exposed through the Math namespace, providing element-wise addition, multiplication, and scaling without manual pointer management:

const dsp = @import("esp_idf").dsp;

var a: [128]f32 = .{0} ** 128;
var b: [128]f32 = .{0} ** 128;
var out: [128]f32 = undefined;

// Populate input arrays...

try dsp.Math.addF32(&a, &b, &out);

The addF32 implementation (lines 81-86 in dsp.zig) automatically checks array lengths and delegates to sys.dsps_add_f32, returning descriptive errors if dimension mismatches occur.

Window Function Generation

Signal conditioning often requires windowing to reduce spectral leakage. The wrapper provides common window functions as static methods:

const dsp = @import("esp_idf").dsp;

var win: [256]f32 = undefined;
dsp.Window.hann(&win);

The hann function (lines 92-94) populates the provided buffer with Hann window coefficients, ready for element-wise multiplication with input signals prior to FFT processing.

Biquad IIR Filtering

For recursive filtering applications, the BiquadFilter type encapsulates filter state and coefficient calculation:

const dsp = @import("esp_idf").dsp;

var lp = try dsp.BiquadFilter.init(.lowpass, 1000.0, 0.707, 0.0);
defer lp.reset();

var input = [_]f32{ /* your samples */ };
var output: [input.len]f32 = undefined;

try lp.process(&input, &output);

The init method (lines 38-53) configures the filter structure based on the specified type (lowpass, highpass, bandpass), while process (lines 59-62) manages the direct-form II implementation using the ESP-DSP optimized routines.

Implementation Details and Error Handling

All high-level types in main/imports/dsp.zig follow consistent patterns for resource management and error propagation. The espCheckError utility (from the error module) translates ESP-DSP return codes into Zig error sets, allowing you to use try and errdefer for robust error handling.

The wrapper maintains zero-copy semantics where possible—arrays passed to process methods are referenced directly rather than duplicated, ensuring efficient memory usage on resource-constrained ESP32 devices. Compile-time checks validate array sizes when lengths are known at comptime, while runtime checks handle dynamic configurations.

Summary

• The main/imports/dsp.zig module provides idiomatic Zig bindings for Espressif's ESP-DSP library, wrapping C primitives like sys.dsps_fir_init_f32 into type-safe structs.
• Build system integration via build.zig and idf_wrapped_modules automatically handles dependencies on sys and error modules, re-exporting DSP functionality through the esp_idf namespace.
• High-level types including FirF32, FFT, Math, Matrix, and BiquadFilter offer zero-copy processing with automatic error checking via espCheckError.
• Practical examples in main/examples/dsp-math.zig demonstrate FIR filtering, radix-2 FFT, vector operations, window functions, and IIR filtering on ESP32 hardware.

Frequently Asked Questions

How do I add the ESP-DSP library to my existing ESP-IDF Zig project?

Add the dependency using the ESP-IDF component manager by running idf.py add-dependency espressif/esp-dsp. During the next build, the Zig build system will automatically generate the sys.zig bindings from the downloaded C headers and register the dsp module in module_specs. Ensure your build.zig includes the idf_wrapped_modules logic to resolve the dsp dependency on sys and error.

What DSP operations are supported by the Zig wrapper?

The wrapper exposes the full ESP-DSP capability set including FIR and IIR filters (FirF32, BiquadFilter), real-valued FFTs (FFT.fft2rF32), vector mathematics (Math.addF32, Math.mulF32), matrix operations, and window functions (Window.hann). All operations use 32-bit floating-point (f32) arithmetic optimized for the ESP32's Xtensa or RISC-V DSP instructions.

Does the Zig wrapper introduce performance overhead compared to raw C?

No significant overhead is introduced. The wrapper functions as a thin abstraction layer that validates inputs and translates Zig slice syntax to C pointers, then directly calls the underlying sys.dsps_* functions. Memory buffers are passed by reference without copying, and error checking occurs only at initialization or when explicitly requested, preserving the real-time performance characteristics of the ESP-DSP library.

Can I use DSP functions on both Xtensa and RISC-V ESP32 variants?

Yes. The repository supports both architectures through conditional compilation in the ESP-IDF build system. The sys module bindings adapt to the target architecture automatically, and the Zig wrapper in main/imports/dsp.zig contains no architecture-specific code. Simply build for your target (idf.py --target esp32c3 for RISC-V or esp32 for Xtensa) and the appropriate DSP optimizations will be linked automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}