ESP32 Example Code¶

Note: These are legacy C reference examples. For new development, use the Rust SDK examples with the Rust SDK instead.

C example code for using the Xylolabs API on ESP32 platforms (ESP32-S3 and ESP32-C3).

File Structure¶

File	Description
`s3_audio_example.c`	ESP32-S3 full audio + sensors with XAP codec, WiFi HTTP POST
`c3_sensor_example.c`	ESP32-C3 lightweight sensor-only node, XMBP over WiFi

Design Principles¶

WiFi Native (No Modem AT Commands)¶

ESP32 has an integrated WiFi stack. Unlike STM32 or Pico examples that require an external LTE-M1 modem via AT commands, ESP32 connects directly using esp_wifi and esp_tls. No external modem hardware is needed.

Sensor/I2S -> Static buffer -> esp_tls (TLS 1.2) -> api.xylolabs.com
                 ^ No intermediate copies           ^ Native WiFi, no AT commands

PSRAM Support (ESP32-S3)¶

The ESP32-S3 optionally supports external PSRAM (up to 8MB via SPI). The platform layer detects PSRAM availability at runtime and can use it for large audio buffers. For XAP encoding, the ~8KB encoder state fits in internal SRAM; PSRAM is only needed for multi-second audio accumulation buffers.

// Platform config example
platform_esp32_config_t cfg = {
    .wifi_ssid     = "MyNetwork",
    .wifi_password = "MyPassword",
    .use_psram     = true,   // enable PSRAM if fitted
};

FreeRTOS Tasks¶

ESP-IDF runs FreeRTOS. The examples use two tasks: - capture_task: Reads I2S DMA buffers and encodes with XAP (pinned to Core 0) - upload_task: Handles HTTP POST to the Xylolabs API (Core 1)

A FreeRTOS queue passes encoded frames between tasks without blocking audio capture.

XAP Default Codec¶

XAP (LC3-based) is the default audio codec on ESP32-S3, which has a Cortex-M (Xtensa LX7 dual-core 240 MHz) with hardware floating-point. XAP at 48kHz/64kbps achieves ~8:1 compression, reducing bandwidth from 96 KB/s (48kHz PCM) to ~8 KB/s (XAP compressed).

The ESP32-C3 example omits audio entirely; it is a sensor-only node using XMBP.

Legacy C Build¶

These examples use the ESP-IDF framework. Tested with ESP-IDF v5.x.

# Set up ESP-IDF environment (one-time)
. $IDF_PATH/export.sh

# Configure target
idf.py set-target esp32s3   # for s3_audio_example
# idf.py set-target esp32c3 # for c3_sensor_example

# Build
idf.py build

# Flash and monitor
idf.py -p /dev/ttyUSB0 flash monitor

CMakeLists.txt (minimal)¶

cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(xylolabs_esp32_example)

main/CMakeLists.txt¶

idf_component_register(
    SRCS "s3_audio_example.c"
    INCLUDE_DIRS "."
    REQUIRES esp_wifi esp_tls nvs_flash driver freertos
)

WiFi Configuration¶

WiFi credentials are set in the source file constants. For production use, store credentials in NVS (Non-Volatile Storage) rather than hard-coding them:

// Development: hard-coded (example only)
#define WIFI_SSID     "MyNetwork"
#define WIFI_PASSWORD "MyPassword"

// Production: read from NVS
nvs_get_str(nvs_handle, "wifi_ssid", ssid_buf, &len);

WiFi Reconnection¶

The platform layer handles WiFi reconnection automatically using the esp_event system. On disconnect, it retries with exponential backoff up to 5 times, then triggers a watchdog-induced reboot.

API Documentation Reference¶

API Reference -- XMBP protocol, ingest sessions, audio uploads, API key management, device management