ESP32 예제 코드¶

참고: 이 문서는 레거시 C 참조 예제이다. 신규 개발에는 Rust SDK 예제와 Rust SDK를 사용한다.

ESP32 플랫폼(ESP32-S3, ESP32-C3)에서 Xylolabs API를 사용하기 위한 C 예제 코드이다.

파일 구조¶

File	Description
`s3_audio_example.c`	ESP32-S3 오디오+센서 통합 예제 (XAP 코덱, WiFi HTTP POST)
`c3_sensor_example.c`	ESP32-C3 경량 센서 전용 노드 (XMBP over WiFi)

설계 원칙¶

WiFi 네이티브 (모뎀 AT 명령 불필요)¶

ESP32는 WiFi 스택이 내장되어 있다. UART AT 명령으로 외부 LTE-M1 모뎀을 제어해야 하는 STM32나 Pico 예제와 달리, ESP32는 esp_wifi와 esp_tls를 사용하여 직접 연결한다. 외부 모뎀 하드웨어가 필요 없다.

Sensor/I2S -> Static buffer -> esp_tls (TLS 1.2) -> api.xylolabs.com
                 ^ 중간 복사 없음                   ^ 네이티브 WiFi, AT 명령 불필요

PSRAM 지원 (ESP32-S3)¶

ESP32-S3는 외부 PSRAM(SPI를 통해 최대 8MB)을 선택적으로 지원한다. 플랫폼 레이어는 런타임에 PSRAM 가용성을 감지하여 대용량 오디오 버퍼에 사용할 수 있다. XAP 인코딩에서 약 8KB의 인코더 상태는 내부 SRAM에 충분히 들어가며, PSRAM은 수 초 분량의 오디오 누적 버퍼에만 필요하다.

// 플랫폼 설정 예제
platform_esp32_config_t cfg = {
    .wifi_ssid     = "MyNetwork",
    .wifi_password = "MyPassword",
    .use_psram     = true,   // PSRAM이 장착된 경우 활성화
};

FreeRTOS 태스크¶

ESP-IDF는 FreeRTOS 위에서 동작한다. 예제는 두 개의 태스크를 사용한다. - capture_task: I2S DMA 버퍼를 읽고 XAP으로 인코딩 (Core 0에 고정) - upload_task: Xylolabs API로 HTTP POST 처리 (Core 1)

인코딩된 프레임은 FreeRTOS 큐를 통해 태스크 간에 전달되어 오디오 캡처를 블로킹하지 않는다.

XAP 기본 코덱¶

ESP32-S3는 하드웨어 부동소수점 유닛을 갖춘 Xtensa LX7 듀얼코어 240MHz 프로세서를 탑재하여 XAP(LC3 기반)를 기본 오디오 코덱으로 사용한다. XAP 48kHz/64kbps는 약 8:1 압축을 달성하여 대역폭을 96 KB/s (48kHz PCM)에서 약 8 KB/s (XAP 압축)로 줄이다.

ESP32-C3 예제는 오디오를 완전히 생략한다. XMBP를 사용하는 센서 전용 노드이다.

레거시 C 빌드¶

이 예제들은 ESP-IDF 프레임워크를 사용한다. ESP-IDF v5.x에서 테스트되었는다.

# ESP-IDF 환경 설정 (최초 1회)
. $IDF_PATH/export.sh

# 타겟 설정
idf.py set-target esp32s3   # s3_audio_example용
# idf.py set-target esp32c3 # c3_sensor_example용

# 빌드
idf.py build

# 플래시 및 모니터링
idf.py -p /dev/ttyUSB0 flash monitor

CMakeLists.txt (최소 구성)¶

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 설정¶

WiFi 자격 증명은 소스 파일 상수에 설정된다. 프로덕션 환경에서는 하드코딩 대신 NVS(비휘발성 저장소)에 자격 증명을 저장하는 것을 권장한다.

// 개발 환경: 하드코딩 (예제 전용)
#define WIFI_SSID     "MyNetwork"
#define WIFI_PASSWORD "MyPassword"

// 프로덕션: NVS에서 읽기
nvs_get_str(nvs_handle, "wifi_ssid", ssid_buf, &len);

WiFi 재연결¶

플랫폼 레이어는 esp_event 시스템을 사용하여 WiFi 재연결을 자동으로 처리한다. 연결이 끊어지면 지수 백오프로 최대 5회 재시도하고, 이후 워치독 리부팅을 트리거한다.

API 문서 참고¶

API Reference -- XMBP 프로토콜, 수집 세션, 오디오 업로드, API 키 관리, 장치 관리