本文介绍如何使用 ESP32 开发板跑通 网易云信智能硬件线上 Demo。您可以参考本文完成 ESP-IDF 环境准备、Demo 工程配置、固件编译烧录、设备配网和智能体绑定。

准备工作

根据本文操作前，请确保您已经完成以下准备：

1. 已获取网易云信应用的 App Key。详细步骤请参考 创建应用并获取 AppKey。
2. 已开通音视频通话 2.0 和对话式 AI 能力。详细步骤请参考 接入概述。
3. 已准备 ESP32 开发板、USB 数据线和可用的 Wi-Fi 网络。
4. 已准备 Windows 或 macOS 开发环境，并安装 Python 3 和 Git。

本文以 ESP32-S3 开发板为例说明。若您使用 ESP32-C3、ESP32-P4 等其他型号，请将命令和配置文件中的芯片型号替换为实际型号。

安装 ESP-IDF

ESP32 Demo 依赖 ESP-IDF 开发环境。建议使用 ESP-IDF 5.4.1 或 5.4.2。

Windows

Windows 环境建议使用乐鑫官方离线安装包安装 ESP-IDF，不建议通过 VS Code 插件首次安装。

1. 前往 ESP-IDF 工具安装器 下载离线安装包。
2. 双击安装包并按提示完成安装。
3. 安装完成后，打开 ESP-IDF PowerShell Environment 或 ESP-IDF Command Prompt。
4. 执行以下命令验证安装结果：

bashidf.py --version

如果命令输出 ESP-IDF 版本号，表示安装成功。

macOS

macOS 环境可通过 Git 拉取 ESP-IDF 源码并安装工具链。

bashmkdir -p ~/esp
cd ~/esp
git clone -b v5.4.2 --recursive https://github.com/espressif/esp-idf.git
cd ~/esp/esp-idf
./install.sh esp32s3

如果需要同时支持多个 ESP32 芯片型号，可按需安装：

bash./install.sh esp32c3,esp32s3

安装完成后，在需要使用 ESP-IDF 的终端中执行：

bash. $HOME/esp/esp-idf/export.sh
idf.py --version

如果需要频繁使用 ESP-IDF，可为 export.sh 配置 shell alias。不要直接在所有终端会话中默认执行 export.sh，避免影响其他 Python 或编译环境。

连接开发板

将 ESP32 开发板连接到电脑，并确认串口名称：

• Windows：串口名称通常为 COMx，例如 COM3。
• macOS：串口名称通常以 /dev/cu. 开头，例如 /dev/cu.usbmodemXXXX。

如果电脑无法识别串口，请根据开发板使用的 USB 转串口芯片安装对应驱动，例如 CP210x 或 CH340。更多串口连接说明，请参考乐鑫文档 与 ESP32 创建串口连接。

下载 Demo 工程

拉取 ESP32 Demo 工程：

bashgit clone https://github.com/netease-im/nertc-esp32-demo.git
cd nertc-esp32-demo

配置 App Key

Demo 工程通过本地配置文件写入 App Key、配网方式等参数。以 ESP32-S3 为例，编辑以下文件：

textcreate_local_config/config.json.s3

将文件中的 App Key 修改为您在网易云信控制台获取的 App Key。

如果使用 ESP32-C3，请编辑同目录下的：

textcreate_local_config/config.json.c3

如需使用蓝牙配网，请将配置文件中的 blufi_wifi 设置为 true；如使用默认 Wi-Fi 配网方式，可设置为 false。

配置工程

在 Demo 工程根目录下执行以下命令。以下示例以 ESP32-S3 为例：

bashidf.py erase-flash
idf.py set-target esp32s3
idf.py fullclean
idf.py menuconfig

在 menuconfig 中根据实际开发板选择板型，并确认 Flash 大小等配置与硬件一致。例如使用 16 MB Flash 的开发板时，需要将 Flash size 配置为 16 MB。

如果 Demo 启用了端侧 AEC，请不要同时开启服务端 AEC，避免回声消除链路重复处理。

配置完成后保存并退出 menuconfig。

烧录本地配置

在 Demo 工程根目录下执行以下命令，将本地配置写入设备。

macOS 示例：

bashpython3 config.py --build --flash -p /dev/cu.usbmodemXXXX

Windows 示例：

bashpython config.py --build --flash -p COM3

如果使用蓝牙配网，需要增加 --blufi 参数：

bashpython3 config.py --build --flash --blufi -p /dev/cu.usbmodemXXXX

请将上述命令中的串口名称替换为您的实际串口。

编译并烧录 Demo

执行以下命令编译工程：

bashidf.py build

编译成功后，烧录固件并打开串口日志：

macOS 示例：

bashidf.py -p /dev/cu.usbmodemXXXX flash monitor

Windows 示例：

bashidf.py -p COM3 flash monitor

monitor 会打开串口日志。后续设备配网、设备 ID 获取、加入房间和智能体连接状态均可通过串口日志排查。

配置智能体

登录 网易云信智能体管理平台，完成以下配置：

1. 创建用户。
2. 创建或选择智能体。
3. 在设备管理中绑定设备。

如需了解完整配置流程，请参考 配置智能体。

设备配网

Wi-Fi 配网

完成固件烧录后，设备默认进入配网流程。请根据设备语音提示或串口日志提示完成 Wi-Fi 配网。

蓝牙配网

如需使用蓝牙配网，请确保已完成以下配置：

1. 在 create_local_config/config.json.s3 或对应芯片型号配置文件中，将 blufi_wifi 设置为 true。
2. 烧录本地配置时增加 --blufi 参数。
3. 使用配套小程序搜索附近设备，并按提示完成配网。

获取设备 ID

设备配网成功后，重启设备并查看串口日志。日志中会输出设备 ID（deviceId），默认通常为设备网卡 MAC 地址。

获取 deviceId 后，在智能体管理平台的设备管理页面中绑定设备：

• 用户 ID：填写前文创建的用户 ID。
• 设备 ID：填写串口日志中的 deviceId。

绑定完成后重启设备。设备启动后会自动关联已绑定的智能体，默认唤醒词为“你好云信”。

验证 Demo

完成设备绑定并重启后，可按以下方式验证：

1. 观察串口日志，确认设备已完成网络连接、SDK 初始化和智能体连接。
2. 对设备说出默认唤醒词“你好云信”。
3. 设备被唤醒后，说出测试问题，确认智能体是否正常回复。

如果设备可以被唤醒并完成语音问答，表示线上 Demo 已跑通。

常见问题排查

问题	可能原因	处理建议
idf.py 命令不存在	ESP-IDF 环境变量未生效	Windows 请使用 ESP-IDF PowerShell 或 Command Prompt；macOS 请先执行 . $HOME/esp/esp-idf/export.sh。
找不到串口	USB 驱动缺失或数据线不支持数据传输	更换 USB 数据线，或安装 CP210x、CH340 等串口驱动。
烧录失败	串口被占用、芯片型号配置错误或 Flash 配置不匹配	关闭占用串口的工具，确认 set-target 和 menuconfig 中的板型、Flash 配置正确。
配网失败	Wi-Fi 信息错误或设备未进入配网模式	重新擦除 Flash 并烧录配置，确认 Wi-Fi 可用。
设备无法绑定智能体	deviceId 填写错误或用户 ID 不匹配	以串口日志输出的 deviceId 为准，检查智能体平台中的设备绑定关系。
唤醒后无回复	App Key、License、智能体配置或网络状态异常	检查本地配置、智能体绑定、设备网络和串口日志中的错误码。
依赖组件拉取失败	网络异常或组件版本兼容问题	清理 managed_components 后重新构建；如仍失败，请根据日志确认失败组件和版本。

如需进一步排查，请保存完整 monitor 日志，并联系网易云信技术支持工程师。