TiRTC 开发文档

中文

English

中文

English

Espressif ESP32-P4 集成说明 ​

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

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

接入基线 ​

项目要求
SDK 包espressif_esp32p4、v2.3.0、mini
ESP-IDF5.5.4
工具链riscv32-esp-elf-gcc 14.2.0_20260121
FreeRTOS tickCONFIG_FREERTOS_HZ=1000
FreeRTOS trace关闭
lwIP socket 基线CONFIG_LWIP_MAX_SOCKETS=10
外部内存启用并成功初始化 PSRAM
网络就绪标志默认 netif 已取得 IP，DNS 可用

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

先确认联网路径 ​

ESP32-P4 本身不集成 Wi-Fi。采用 ESP32-C6/C61 无线协处理器时，可参考 ESP-IDF 的网络扩展架构和 esp_wifi_remote 组件说明；典型路径是：

text
TiRTC / BSD socket
  -> lwIP / esp_netif
  -> esp_wifi_remote
  -> ESP-Hosted
  -> SDIO
  -> ESP32-C6/C61
  -> Wi-Fi AP

TiRTC 不直接操作 ESP-Hosted 或 SDIO，只使用工程提供的默认网络接口。因此，“P4 工程可以编译”不等于无线链路可用。启动 TiRTC 前必须分别确认：

  1. C6/C61 已烧录与主机端组件匹配的从机固件。
  2. SDIO 引脚、总线宽度、时钟和复位电平与板级原理图一致。
  3. ESP-Hosted 和 remote Wi-Fi 初始化完成。
  4. 已收到 IP_EVENT_STA_GOT_IP，默认路由和 DNS 可用。

ESP-IDF 5.5.4 下可以在应用组件的 idf_component.yml 中固定已验证的主机端组件系列：

yaml
dependencies:
  espressif/esp_hosted:
    version: "==1.4.*"
  espressif/esp_wifi_remote:
    version: "==0.14.*"

上面的版本只约束 P4 主机端。C6/C61 固件仍需与所选 ESP-Hosted 版本配套；不要只升级主机端组件。SDIO GPIO、总线宽度和时钟属于板级配置，必须按实际硬件填写，不能照抄其他开发板。

P4 通过 C6/C61 接入 Wi-Fi 时，TiRTC 的 TIRTC_OPT_NETWORK_TYPE 仍设置为 TIRTC_NETCONN_WIFI。外接 Ethernet 或其他 lwIP netif 时，也应先让默认路由和 DNS 完整建立，再启动 SDK。

作为 ESP-IDF 组件接入 ​

推荐目录：

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 与 lwIP 构建契约 ​

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

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
CONFIG_LWIP_MAX_SOCKETS=10

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

text
CONFIG_SPIRAM=y
CONFIG_SPIRAM_USE_MALLOC=y
CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM=y

P4 开发板的 PSRAM 模式、频率和容量可能不同，应按模组和板级说明配置。工程同时使用远程 Wi-Fi、HTTP、音视频或其他网络模块时，所有模块共享 lwIP socket 表；不要把 CONFIG_LWIP_MAX_SOCKETS 调低。确需增大时，应同时评估内存占用和峰值并发连接数。

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

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

检查最终生效值时，以 build/config/sdkconfig.h 为准：

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|CONFIG_LWIP_MAX_SOCKETS" \
  sdkconfig build/config/sdkconfig.h

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

在网络就绪后启动 TiRTC ​

推荐启动顺序：

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

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

TiRtcInit() 本身不访问网络，可以提前调用；TiRtcStart() 应在网络路径完整就绪后调用。设备上电时间无效时，应先通过 SNTP 校准时间，尤其是在使用 HTTPS 服务地址时。完整的身份选项、回调结构和启动顺序见连接设备。

使用 HTTPS 服务地址 ​

TiRTC 2.3.0 ESP32-P4 包支持 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、lwIP socket 和 SDK 日志，不要通过改回 HTTP 掩盖 TLS 配置问题。

规划 PSRAM、内部 RAM 与 DMA ​

P4 的 TiRTC、ESP-Hosted、摄像头、H.264、显示和音频任务可能同时运行。内存分配应按能力划分，而不是简单地把所有对象都放进 PSRAM：

内存适合放置
PSRAM大媒体帧、编码输出、接收帧副本、固定帧池、UI 图像、较大的后台任务栈
内部 RAMSDIO/摄像头/显示 DMA 描述符及 DMA 缓冲、同步对象、小型控制队列、ISR 状态、Flash cache 关闭期间仍要访问的数据

首次接入应同时记录内部 RAM 和 PSRAM 的 free、minimum 与 largest block。总空闲内存仍然很多，不代表还能申请连续的 SDIO 或显示 DMA 块。建议在启动时完成大缓冲和固定帧池的预分配，并使用有界队列，避免通话过程中反复申请大块内存造成碎片。

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

接入 P4 媒体流水线 ​

TiRTC 只传输已经编码好的媒体帧，不负责摄像头、麦克风、编解码和显示。P4 可以使用硬件 H.264 编码器生成上行视频；收到下行 H.264 后，解码器、颜色转换和显示仍由应用负责。

完整帧格式、H.264 SPS/PPS、关键帧、stream_id、订阅和 2.3.0 码率建议，见播放音视频。P4 侧还应注意：

  1. on_update_bitrate 中只把目标码率投递给编码任务，不在 SDK 回调中重配硬件编码器。
  2. 压缩 H.264 的 P 帧依赖前序参考帧，不要为了追赶实时性任意丢弃队列中间的压缩帧。
  3. 展示落后时，优先淘汰已经完成解码的旧原始帧；如果压缩参考链已经损坏，则清理解码状态并请求新的完整关键帧。
  4. 编码、解码、颜色转换和显示任务都使用有界队列，并主动让出 CPU，避免长期占用核心使 SDK 网络线程或系统 Idle 任务得不到调度。

验收清单 ​

  1. 构建日志显示目标为 esp32p4，编译器为 riscv32-esp-elf-gcc 14.2.0_20260121。
  2. C6/C61 固件与 P4 侧 ESP-Hosted 组件版本配套，SDIO 初始化无版本或传输错误。
  3. 运行时打印 TiRtcGetVersion() 和 TiRtcGetBuildInfo()，确认库和头文件均为 2.3.0。
  4. 启动日志确认 PSRAM 可用、remote Wi-Fi 已取得 IP、DNS 和系统时间有效。
  5. TiRtcStart() 返回后继续等待 TIRTC_EVENT_SYS_STARTED；返回 0 只表示启动请求已受理。
  6. 分别验证构建、P4 烧录、C6/C61 联网、TiRTC 启动、建连和媒体结果，不用前一层结果替代后一层。

TiRTC 开发文档

Copyright © 2025