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 里看？

分工如下：