TiRTC 开发文档

中文

English

中文

English

Espressif ESP32-S3 集成说明 ​

在按 C SDK 接入 完成通用接入后，如果你使用的是 Espressif ESP32-S3 和 TiRTC C SDK 2.3.0 mini 包，再继续看本文。

本文补充 ESP32-S3 工程里需要单独处理的静态库接入、FreeRTOS、Wi-Fi、PSRAM 和媒体任务边界。通用的初始化、设备启动、连接和音视频接口，仍以已有指南为准。

接入基线 ​

项目要求
SDK 包espressif_esp32s3、v2.3.0、mini
ESP-IDF5.5.4
工具链xtensa-esp-elf-gcc 14.2.0_20260121
FreeRTOS tickCONFIG_FREERTOS_HZ=1000
FreeRTOS trace关闭
外部内存启用并成功初始化 PSRAM
网络就绪标志已收到 IP_EVENT_STA_GOT_IP

从下载 C SDK取得 ESP32-S3 对应包。解压后先核对包名、同名 .sha256 和 manifest/build-contract.env，再把文件放入工程。ESP32-S3 与 ESP32-P4 的静态库不能混用，头文件和 libTiRTC.a 也必须来自同一个版本包。

作为 ESP-IDF 组件接入 ​

推荐把 SDK 单独放成组件，不要把头文件和静态库散落到应用目录：

text
components/
`-- tirtc_sdk/
    |-- CMakeLists.txt
    |-- include/
    |   `-- tirtc/
    |       |-- basedef.h
    |       |-- tgtrp.h
    |       |-- tiRTC.h
    |       `-- tiRTC_stat.h
    `-- lib/
        `-- libTiRTC.a

components/tirtc_sdk/CMakeLists.txt：

cmake
idf_component_register(
    INCLUDE_DIRS "include"
    REQUIRES freertos esp_http_client esp_netif esp_timer hal json lwip mbedtls soc
)

set(TIRTC_LIB "${CMAKE_CURRENT_LIST_DIR}/lib/libTiRTC.a")

if(NOT EXISTS "${TIRTC_LIB}")
    message(FATAL_ERROR "TiRTC static library not found: ${TIRTC_LIB}")
endif()

add_library(tirtc_prebuilt STATIC IMPORTED)
set_target_properties(tirtc_prebuilt PROPERTIES IMPORTED_LOCATION "${TIRTC_LIB}")

add_library(tirtc_link_bundle INTERFACE)
target_link_libraries(tirtc_link_bundle INTERFACE
    "-Wl,--start-group"
    tirtc_prebuilt
    $<TARGET_FILE:__idf_lwip>
    $<TARGET_FILE:__idf_mbedtls>
    $<TARGET_FILE:mbedcrypto>
    $<TARGET_FILE:mbedtls>
    $<TARGET_FILE:mbedx509>
    $<TARGET_FILE:everest>
    $<TARGET_FILE:p256m>
    $<TARGET_FILE:__idf_hal>
    $<TARGET_FILE:__idf_soc>
    "-Wl,--end-group"
)

target_link_libraries(${COMPONENT_LIB} INTERFACE tirtc_link_bundle)

应用组件在 REQUIRES 中增加 tirtc_sdk，源码统一使用：

c
#include <tirtc/tiRTC.h>

libTiRTC.a 已包含该平台配套的底层传输实现，应用只链接这一份 TiRTC 静态库。不要再混入其他版本或其他芯片的底层归档。

对齐 FreeRTOS 构建契约 ​

TiRTC 是预编译静态库，最终工程的 FreeRTOS 关键配置必须与包内 manifest/build-contract.env 一致。2.3.0 ESP32-S3 默认包对应：

text
CONFIG_FREERTOS_HZ=1000
# CONFIG_FREERTOS_USE_TRACE_FACILITY is not set
# CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS is not set
# CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS is not set

同时启用外部内存和外部任务栈支持：

text
CONFIG_SPIRAM=y
CONFIG_SPIRAM_USE_MALLOC=y
CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM=y

PSRAM 的 Quad/Octal 模式、电压和频率由具体模组决定，不要直接复制其他开发板的参数。首次接入时不要启用“PSRAM 初始化失败仍继续启动”；让硬件配置错误在启动阶段直接暴露。

修改 SDK 包或上述配置后执行一次干净构建：

bash
idf.py fullclean
idf.py reconfigure
idf.py build

检查最终生效值时，以 build/config/sdkconfig.h 为准，而不是只看 sdkconfig.defaults：

bash
grep -E "CONFIG_FREERTOS_HZ|CONFIG_FREERTOS_USE_TRACE_FACILITY|CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS|CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS|CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM" \
  sdkconfig build/config/sdkconfig.h

工程必须启用 trace 或使用不同 tick 时，应获取按该配置重新编译的 SDK 包，不要继续复用默认静态库。

在网络就绪后启动 TiRTC ​

ESP32-S3 的 WIFI_EVENT_STA_CONNECTED 只表示已关联到 AP，此时 DHCP、默认路由和 DNS 可能尚未完成。推荐启动顺序：

text
PSRAM 初始化成功
  -> Wi-Fi 启动
  -> IP_EVENT_STA_GOT_IP
  -> 校准系统时间
  -> TiRtcInit / TiRtcSetOption / TiRtcStart
  -> TIRTC_EVENT_SYS_STARTED

Wi-Fi 和 IP 事件回调中只设置 EventGroup 或发送轻量消息，由应用任务执行时间同步和 TiRTC 启动。不要在 ESP-IDF 系统事件线程里直接执行可能阻塞的 SDK 启动流程。

TiRtcInit() 本身不访问网络，可以提前调用；TiRtcStart() 应在设备已经取得 IP、默认路由和 DNS 可用后调用。设备上电时间无效时，应先通过 SNTP 校准时间，尤其是在使用 HTTPS 服务地址时。

使用原生 Wi-Fi 接入时，TIRTC_OPT_NETWORK_TYPE 保持 TIRTC_NETCONN_WIFI。完整的身份选项、回调结构和启动顺序见连接设备。

使用 HTTPS 服务地址 ​

TiRTC 2.3.0 ESP32-S3 包支持 HTTPS。工程裁剪 mbedTLS 配置时，至少保留 TLS 客户端和 TLS 1.2 能力；以下是可直接对齐的保守配置：

text
CONFIG_MBEDTLS_TLS_SERVER_AND_CLIENT=y
CONFIG_MBEDTLS_SSL_PROTO_TLS1_2=y

使用 HTTPS 时，应在 TiRtcStart() 前确认系统时间有效。若 HTTPS 请求失败，先检查最终 sdkconfig.h、系统时间、DNS 和 SDK 日志，不要通过改回 HTTP 掩盖 TLS 配置问题。

管理 PSRAM 与内部 RAM ​

ESP32-S3 上建议按用途分配内存。能力标志和外部任务栈限制可同时参考 ESP-IDF 的外部 RAM 说明：

内存适合放置
PSRAM大媒体帧、编码输出、接收帧副本、固定帧池、较大的非 DMA 队列数据
内部 RAMDMA 描述符、需要 MALLOC_CAP_DMA 的缓冲区、ISR/同步对象、小型控制消息、Flash cache 关闭期间仍要访问的数据

接入时至少打印一次 PSRAM 总量与可用量，并检查 esp_psram_get_size() 返回非 0。只看总空闲堆不够；摄像头、I2S 和显示驱动还需要连续的内部 DMA 内存，应同时关注内部 RAM 的最大可用块。

TiRTC 的音视频回调运行在 SDK 内部线程，回调参数中的数据指针只在回调期间有效。需要交给解码或播放任务时，必须在回调返回前复制到应用自己的缓冲区；较大的副本优先放入 PSRAM。回调中只做状态更新、轻量复制和队列投递，不直接编解码、写 Flash、写文件或等待锁。

接入媒体任务 ​

TiRTC 负责传输已经编码好的媒体帧，不负责摄像头采集、麦克风采集、编解码或播放。ESP32-S3 应把采集、编码、发送和接收、解码、播放分别放在有界队列连接的任务中，避免媒体处理阻塞 SDK 回调线程。

完整帧格式、H.264 SPS/PPS、关键帧、stream_id、订阅和 2.3.0 码率建议，见播放音视频。芯片侧只需额外保证两点：

  1. on_update_bitrate 中只把目标码率投递给编码任务，不在回调中重配编码器。
  2. 发送返回 TIRTC_E_BUSY 时不要靠延时堆积旧帧；按官方流程丢弃后续非关键帧并尽快恢复完整关键帧。

首次做低延迟联调时，可以在 Wi-Fi 启动成功后关闭省电模式，先排除休眠带来的时延抖动：

c
ESP_ERROR_CHECK(esp_wifi_set_ps(WIFI_PS_NONE));

该设置会增加功耗。链路跑通后，再按产品功耗目标重新评估。

验收清单 ​

  1. 构建日志显示目标为 esp32s3，编译器为 xtensa-esp-elf-gcc 14.2.0_20260121。
  2. 运行时打印 TiRtcGetVersion() 和 TiRtcGetBuildInfo()，确认库和头文件均为 2.3.0。
  3. 启动日志确认 PSRAM 可用、收到 IP_EVENT_STA_GOT_IP、系统时间有效。
  4. TiRtcStart() 返回后继续等待 TIRTC_EVENT_SYS_STARTED；返回 0 只表示启动请求已受理。
  5. 建连后再验证音频、视频、订阅、取消订阅和断开，不用“编译成功”替代真机运行结果。

常见问题定位 ​

现象优先检查
链接阶段出现 undefined reference是否使用 ESP32-S3 2.3.0 完整包、组件是否形成链接组、是否残留旧构建缓存
SDK 线程启动即崩溃build-contract.env 与最终 sdkconfig.h 是否一致，PSRAM 是否真的初始化成功
显示 Wi-Fi 已连接但 SDK 无法上线是否只等了 WIFI_EVENT_STA_CONNECTED，尚未取得 IP、DNS 或有效系统时间
ESP_ERR_NO_MEM 或 DMA 申请失败大媒体缓冲是否仍占用内部 RAM，内部连续 DMA 块是否被其他任务和队列耗尽
音视频偶发卡顿SDK 回调是否执行耗时工作，Wi-Fi 省电是否开启，媒体队列是否无界增长

仍无法定位时，按排查接入问题保留 SDK 版本、BuildInfo、完整启动日志、最终 sdkconfig 和首次异常前后的日志。

TiRTC 开发文档

Copyright © 2025