Network

本文说明本章节功能的接入方式、关键源码和应用参考，帮助开发者快速完成集成。

应用例程

场景

文件

调用接口

小智机器人联网对话入口

app_chatbot_gui.c

网络数据回调、app_malloc() / app_free()

AI App 火山方舟 Chat Completions

ai_main.c

webclient_session_create()、webclient_post()、webclient_read()

AI App 火山同声传译 WebSocket

ai_simi_service.c

WebSocket 连接、音频数据收发回调

浏览器 HTTP 图片 / 视频 / JSON 请求

browser_thread.c

webclient_session_create()、webclient_get()、webclient_read()

云书城列表 / 封面 / 下载

reader_cloud.c

webclient_session_create()、webclient_get()、webclient_read()

高德地图网络请求

gaode_map_net_process.c

高德地图网络请求封装接口

高德地图离线包下载

gaode_map_svg_download.c

webclient_session_create()、webclient_get()、webclient_read()

FAQ1 Solution 支持哪些设备侧上网方式？

Solution 当前常见设备侧 IP 网络方式包括：

  1. Wi-Fi：设备直接连接 AP，通过 lwIP 访问服务器。

  2. 4G/LTE：设备通过 Cat1/4G modem 入网，数据面接入 lwIP/netdev 或 PPP/PPPoS。

  3. BT PAN：设备通过蓝牙 PAN profile 获得 IP 网络能力。

FAQ2 普通蓝牙已经连接，为什么还是不能访问服务器？

普通蓝牙连接、A2DP、HFP、BLE GATT 都不等于 IP 网络。只有启用 BT PAN profile，并完成 PAN 到 lwIP 的网络适配后，蓝牙才可以作为 IP 网络通道。

完成 PAN 入网后，它和 Wi-Fi、4G 一样都是 IP 网络通道。业务可以用它获取天气、同步配置、下载电子书/图片/音频资源，也可以用于 HTTP OTA。OTA 只是一个使用 PAN 的业务示例，不代表 PAN 只能用于 OTA。

FAQ3 业务代码访问服务器前要检查什么？

建议至少检查：

  1. Wi-Fi、4G 或 PAN 是否已经完成连接；

  2. APP_NETWORK_USED 是否打开；

  3. 如果使用 BT PAN，先在 menuconfig → (Top) → Bluetooth config 打开 BLUETOOTH、BSP_BLE_SIBLES、PERI_USING_BT，再在 SDK 蓝牙配置路径打开 BT_FINSH、BT_FINSH_PAN，使用手动经典 BT profile 时还要打开 BT_PROFILE_CUSTOMIZE 和 CFG_PAN；

  4. net_is_connected() 是否返回 true；

  5. 如果访问域名，DNS 是否正常；

  6. 如果访问 HTTPS，mbedtls/WebClient TLS 配置是否打开；

  7. 文件下载前，目标内存或文件系统空间是否足够。

应用侧等待网络 ready 的例程见 网络访问与文件下载。

FAQ4 Wi-Fi 已连接，但 net_is_connected() 仍为 false 怎么办？

请按顺序检查：

  1. Wi-Fi 是否真正获取到 IP 地址；

  2. lwIP 是否启用；

  3. 默认 netdev 是否切到 Wi-Fi；

  4. DHCP 是否成功；

  5. 连接回调和 app_net 状态是否同步；

  6. 是否存在 4G、PAN 等其他网络设备抢占默认路由。

Wi-Fi 的底层配置、驱动和 FinSH 调试命令请参考 SDIO Wi-Fi。

FAQ5 4G 已注册网络，但访问服务器失败怎么办？

请按顺序检查：

  1. SIM 卡、天线、运营商注册是否正常；

  2. APN、拨号或数据通道是否正确；

  3. 当前 modem 采用 PPP/PPPoS 还是类以太网/NAT 数据通道；

  4. lwIP、netdev 或 PPP 是否启用；

  5. 是否获取到 IP、网关和 DNS；

  6. net_is_connected() 是否返回 true；

  7. 服务器地址、端口、防火墙和 TLS 配置是否正确。

4G modem 接入和适配细节请参考 4G（LTE）。

FAQ6 怎么做网络速率测试？

推荐用 HTTP 下载已知大小的测试文件，循环 webclient_read()，统计总字节数和耗时后换算 KB/s 或 Mbps。测试前先等待 net_is_connected()，避免把入网等待时间算进吞吐。

速率测试例程见 网络访问与文件下载 - HTTP 下载速率测试。connectivity demo 的 speed 面板只是 UI 展示参考，真实吞吐以 HTTP 下载统计为准。

FAQ7 HTTP 下载文件应该保存到内存还是文件系统？

建议按文件大小和使用方式选择：

场景

推荐方式

小 JSON、小配置、小图片

下载到内存

短 mp3/wav 提示音

下载到内存后 mp3ctrl_open_buffer() 播放

大音频、资源包、地图、图片包

下载到文件系统

固件升级包

优先使用 OTA 框架

边下载边播放的音频

ringbuffer 或 PCM 流式播放

不知道总长度的流

ringbuffer 或边收边解析

Solution 工程中，网络读取缓冲和下载结果缓冲建议用 app_cache_alloc() / app_cache_realloc() / app_cache_free()，优先放到 PSRAM cache heap，避免大块数据挤占普通 system heap。

下载到内存和文件系统的例程见 网络访问与文件下载。

FAQ8 WebClient 下载大文件中断怎么办？

处理策略取决于业务类型：

  1. 小文件：直接重新下载。

  2. 大文件：使用 HTTP Range 实现断点续传，可参考 WebClient 示例。

  3. OTA 固件：优先使用 HTTP OTA，避免业务层重复实现升级安全策略。

  4. 流式音频：中断后停止播放或重新建链，必要时清空 ringbuffer。

FAQ9 HTTPS 访问失败常见原因有哪些？

常见原因包括：

  1. 未打开 WebClient TLS/mbedtls 配置；

  2. 系统时间不正确，导致证书校验失败；

  3. 根证书缺失或证书链不完整；

  4. 服务器 SNI、域名和证书 CN/SAN 不匹配；

  5. 内存不足，TLS handshake 失败；

  6. 网络 MTU、DNS 或路由异常。

如果只是验证网络链路，建议先使用 HTTP 或 ping 验证，再切换到 HTTPS。

FAQ10 如何访问大模型？

有三种推荐方式：

  1. 使用小智 AI 组件：参考 solution/components/xiaozhi/，该组件已有 WebSocket/MQTT、TTS/STT/LLM 事件和 Opus 音频链路。

  2. 参考 AI App 示例：参考动态应用中的 AI App，其中随机单词使用火山方舟 Chat Completions，同声传译使用火山 WebSocket 服务。

  3. 自定义 HTTP/WebSocket API：使用 Wi-Fi/4G/PAN 入网，WebClient 或 WebSocket 发送 JSON 请求，解析普通 JSON 或流式返回。

如果大模型返回音频或 TTS 流，播放链路请参考 网络音频播放。

FAQ11 服务器返回流式音频，网络 FAQ 还是音频 FAQ 里看？

分工如下：

FAQ12 如何使用 WebClient 下载网络文件并保存到文件系统？

solution/examples/_dynamic_app/c/app/reader/src/reader_cloud.c 提供了一个网络文件下载参考。它不是只能用于 Reader 或 BT PAN：只要设备已经获得可用的 IP 网络，Wi-Fi、4G/LTE 和 BT PAN 都可以复用相同的 WebClient 下载逻辑。

  1. 参考代码

网络接收位于 reader_cloud_recv_entry()：

session = webclient_session_create(READER_HTTP_HEADER_SIZE);
...
webclient_set_timeout(session, READER_CLOUD_IO_TIMEOUT_MS);
resp_status = webclient_get(session, task->url);
...
bytes_read = webclient_read(session,
                            pipe->slots[slot].data,
                            READER_CLOUD_READ_SIZE);

文件写入位于 reader_cloud_write_entry()。下载内容先保存为临时文件：

dfs_file_open(&fd, pipe->temp_path,
              O_WRONLY | O_BINARY | O_CREAT | O_TRUNC);
...
write_len = dfs_file_write(&fd,
                           pipe->slots[slot].data,
                           bytes_to_write);

下载成功后，reader_cloud_file_once() 将临时文件改名为最终文件：

dfs_file_unlink(task->file_path);
if (dfs_file_rename(pipe->temp_path, task->file_path) == 0)
    ret = 0;

  1. 下载流程和前置检查

整体流程为：创建 WebClient 会话并发送 GET 请求，循环读取网络数据，将数据分块写入 .tmp 临时文件；确认 HTTP 状态、读取结果、写入长度和文件总长度均正常后，再用临时文件替换最终文件。这样可以避免把未下载完整的文件直接当作有效文件使用。

下载前应先确认：

  1. 网络已经连接，设备已获取 IP、网关和 DNS，且 net_is_connected() 返回 true；

  2. 已启用 WebClient；使用 HTTPS 时还要启用 mbedtls；

  3. 文件系统已经挂载，目标目录可写且剩余空间足够；

  4. 对 webclient_session_create()、webclient_get()、webclient_read()、dfs_file_open()、dfs_file_write() 和 dfs_file_rename() 的返回值均进行了检查。

  5. BT PAN 使用说明

如果使用 BT PAN，必须先完成 PAN 连接和网络适配。普通蓝牙配对、A2DP、HFP 或 BLE GATT 连接成功并不代表设备已经具备 IP 网络能力。BT PAN 接通后，它只作为网络通道，后续下载代码与 Wi-Fi、4G/LTE 相同。

  1. HTTPS 证书校验失败

日志出现 verify peer certificate fail、The certificate is not correctly signed by the trusted CA 等信息时，请检查：

  1. HCPU 工程的 menuconfig 中是否启用了 WebClient TLS、mbedtls 和 Using user CA；

  2. 是否获取了目标服务器证书链对应的根 CA，而不是固定使用某个网站的证书；

  3. 根 CA 是否为 PEM 格式，即内容以 -----BEGIN CERTIFICATE----- 开头、以 -----END CERTIFICATE----- 结尾；

  4. 根 CA 是否已放入 sdk/external/mbedtls_228/certs/，并重新编译、烧录 HCPU 固件；

  5. 设备系统时间是否正确，域名是否与证书的 CN/SAN 匹配。

README.md is not CA file! Skipped! 表示构建脚本跳过了证书目录中的说明文件，不是证书校验失败的原因。证书目录建议只保留业务需要的根 CA，避免无关证书增加 ROM/RAM 占用。

  1. 文件路径数组越界

目录名和文件名由外部参数传入时，不要使用过小的固定数组配合 rt_sprintf()。例如下面的代码可能覆盖数组边界：

char path_file_name[30];
rt_sprintf(path_file_name, "/%s/%s", dir_name, file_name);

应预留足够空间，并使用带长度限制的 rt_snprintf()：

#define DOWNLOAD_PATH_LEN 128

char path_file_name[DOWNLOAD_PATH_LEN];
int len = rt_snprintf(path_file_name, sizeof(path_file_name),
                      "/%s/%s", dir_name, file_name);

if (len < 0 || len >= (int)sizeof(path_file_name))
{
    rt_kprintf("download path is too long\n");
    return -RT_EINVAL;
}

工程已有统一路径长度宏时，应优先复用，例如 Reader 中的 READER_CLOUD_PATH_LEN。

  1. 命令行过长被截断

URL 较长时，完整命令可能超过默认的 FINSH_CMD_SIZE（通常为 80），表现为命令没有执行、URL 后半段被当作新命令，或者提示 command not found。这是 shell 输入长度不足导致的截断。

请在 HCPU 工程的 menuconfig 中进入 RTOS → RT-Thread Components → Command shell，将 The command line size for shell 调大，例如设为 256，然后重新编译并烧录 HCPU 固件。

更多 BT PAN 配置和完整下载示例见 网络访问与文件下载。