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).

File Structure

File	Description
s3_audio_example.c	ESP32-S3 full audio + sensors with XAP codec, WiFi HTTP POST

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).

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

# 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