企业官网建设流程全解析

• 物联网
• 嵌入式
• 驱动开发
• 硬件开发

本文以 esp-iot-solution 仓库中的 USB Dongle 示例 为背景，完整讲解其命令行接口（CLI）的全部内置命令。该示例将 ESP32-S 系列芯片模拟为 USB 无线网卡 / 蓝牙适配器，Host 主机通过 USB-CDC 串口或 UART 发送命令即可完成 AP/STA 模式切换、扫描、SmartConfig 一键配网、内存与版本查询等操作。阅读本文后，你将掌握help、ap、sta、mode、smartconfig、scan、ram、restart、version共 9 条命令的用法、参数语义、返回格式与底层实现原理，并能在自己的项目中基于 FreeRTOS-Plus-CLI 快速扩展新命令。

一、命令体系概览与交互方式

USB Dongle 示例在 main/CLI_Commands.c 中基于 FreeRTOS-Plus-CLI（组件位于 components/FreeRTOS-Plus-CLI/FreeRTOS_CLI.c）注册并实现了全部命令，命令解析入口为 main/Command_Parse.c。

1.1 命令如何到达设备

命令可以通过两条物理通道发送到设备：

• USB-CDC（ACM）通道：固件使能 TinyUSB CDC 时，Host 侧会枚举出/dev/ttyACM*（Linux）或 COM 口（Windows）。设备侧的回调 tinyusb_cdc_rx_callback 将收到的字节流交给Command_Parse()。
• UART 通道：当 CDC 未使能（例如同时使能 ECM/RNDIS 与 BTH 时端点不足）时，可通过Example Configuration中的UART_ENABLE选项改用 UART 传输命令，端口、波特率、TX/RX 引脚均可通过 Kconfig.projbuild 配置（波特率范围 1200~115200，默认 115200）。

命令的最终输出（如扫描结果、查询结果）通过 data_back.c 中的esp_data_back()统一回写：UART 使能时调用uart_write_bytes，否则经 TinyUSB CDC 队列写回 Host。

1.2 命令格式约定

解析器 Command_Parse.c 的关键约定如下：

• 以换行符\n作为命令结束标志（\r被忽略），因此在串口终端输入命令后必须回车，且命令末尾需带\n（LF）。
• 单条命令输入缓冲上限cmdMAX_INPUT_SIZE为 80 字节，输出缓冲上限cmdMAX_OUTPUT_SIZE为 1024 字节，超长输入会被截断。
• 支持退格键（\b）删除已输入字符。
• 每条命令执行完成后会输出提示符>，表示等待下一条命令。
• Wi-Fi 相关命令（ap、sta、mode、scan、smartconfig）仅在 USB Network Class（ECM/RNDIS/NCM）使能时才可用，代码中通过#if CFG_TUD_NCM || CFG_TUD_ECM_RNDIS条件编译控制；smartconfig在 ESP32-P4 目标上不可用（#if !CONFIG_IDF_TARGET_ESP32P4）。

二、help：列出所有已注册命令

功能：列出当前固件中注册的全部命令及其用法说明。

命令：

help

响应示例：

help: Lists all the registered commands ap <ssid> [<password>]: configure ssid and password sta -s <ssid> [-p <password>]: join specified soft-AP sta -d: disconnect specified soft-AP mode <mode>: <sta> station mode; <ap> ap mode smartconfig [op]: op:1, start smartconfig; op:0, stop smartconfig scan [<ssid>]: <ssid> SSID of AP want to be scanned ram: Get the current size of free heap memory and minimum size of free heap memory restart: Software reset of the chip version: Get version of chip and SDK >

每条命令的用法说明来自注册时定义的CLI_Command_Definition_t结构体中的 HelpString 字段。从源码结构看，help输出内容由各命令定义自动汇总生成，因此当开发者新增命令后，help列表会自动更新，无需手工维护。此外，若在menuconfig中开启CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS，还会额外注册task-status命令，用于打印每个任务的运行状态表。

三、ap：配置并启动 Soft-AP，或查询当前 AP 配置

功能：将设备配置为 AP（热点）模式，或查询当前 AP 的 SSID 与密码。

设置命令（设置 SSID 为Soft_AP、密码为espressif）：

ap Soft_AP espressif

查询命令（不带参数时查询当前 AP 配置）：

ap

响应示例：

AP mode:Soft_AP,espressif >

注意事项：

• password为可选项。若只提供 SSID 而不提供密码，例如ap Soft_AP，则 AP 以WIFI_AUTH_OPEN（开放、不加密）模式运行。
• 若提供了密码，密码长度必须不小于 8 位。底层实现位于 cmd_wifi.c 的 wifi_cmd_ap_set：当密码字符串非空但长度小于 8 时，会打印password less than 8并返回ESP_FAIL；密码为空时自动将认证模式设置为WIFI_AUTH_OPEN，否则使用WIFI_AUTH_WPA_WPA2_PSK。
• AP 默认最大连接数为 4（max_connection = 4）。
• 查询逻辑（wifi_cmd_query）在WIFI_MODE_AP下通过esp_wifi_get_config读取实际生效的配置并格式化回显。

四、sta：连接 / 断开 Station 模式下的目标 AP

功能：让设备以 Station 身份加入指定的 Wi-Fi 网络，断开当前连接，或查询已连接 AP 的信息。

4.1 连接指定 AP

设置命令：

sta -s AP_Test -p espressif

参数含义：-s后跟目标 SSID，-p后跟可选的密码。

说明：

• password为可选项，即sta -s <ssid>可省略密码（此时以空密码尝试连接）。
• 底层 wifi_cmd_sta_join 会先通过事件组CONNECTED_BIT判断是否已连接：若已连接则先断开，再设置WIFI_MODE_STA、写入wifi_config_t并调用esp_wifi_connect()，最后最多等待 5 秒等待连接成功事件。
• 连接成功后设备会注册 Wi-Fi RX 回调pkt_wifi2usb，将收到的网络包经 TinyUSB 转发给 Host，实现 USB 网卡上网；同时（ECM/NCM 模式）会通过tud_network_link_state通知 Host 链路 UP。
• 参数解析由prvStationCommand（CLI_Commands.c）通过FreeRTOS_CLIGetParameter逐段完成，会校验-s/-p标志，非法参数返回Invalid parameter。

4.2 查询已连接 AP 信息

查询命令：

sta

响应示例（依次为 SSID、信道、监听间隔、认证模式值）：

<ssid>,<channel>,<listen_interval>,<authmode> >

其中authmode为数值，对应关系如下表：

查询实现同样位于 wifi_cmd_query：在 STA 模式下先检查CONNECTED_BIT，已连接则读取cfg.sta.ssid / channel / listen_interval / threshold.authmode并格式化输出；未连接则仅打印日志。

4.3 断开当前连接

设置命令：

sta -d

响应示例：

OK >

实现对应 wif_cmd_disconnect_wifi：若当前已连接则清除CONNECTED_BIT、调用esp_wifi_disconnect()并等待DISCONNECTED_BIT，成功返回OK，否则返回FAIL。断开后设备会注销 Wi-Fi RX 回调，并在 ECM/NCM 模式下通知 Host 链路 DOWN。

五、mode：切换 Wi-Fi 工作模式

功能：在 Station 模式与 AP 模式之间切换。

设置 Station 模式：

mode sta

设置 AP 模式：

mode ap

实现位于 wifi_cmd_set_mode：参数sta对应esp_wifi_set_mode(WIFI_MODE_STA)，参数ap对应WIFI_MODE_AP；传入其他参数时返回ESP_FAIL，CLI 层会回显Invalid parameter。

实战建议：mode只负责切换模式本身；配合ap命令可快速把设备变成热点，配合sta命令可切换为联网设备，适合在开发阶段测试不同网络拓扑。

六、smartconfig：ESPTOUCH 一键配网

功能：通过乐鑫 ESPTOUCH 协议，由手机 App 将 Wi-Fi 的 SSID 与密码广播给设备，实现免输入配网。该命令在 ESP32-P4 目标上被禁用。

6.1 开启 SmartConfig 配网

命令：

smartconfig 1

响应示例（设备成功收到手机广播的 SSID 与密码后回显）：

>SSID:FAST_XLZ,PASSWORD:12345678 OK >

SSID:xxx,PASSWORD:xxx这行由事件处理函数在收到SC_EVENT_GOT_SSID_PSWD时通过esp_data_back实时回传（cmd_wifi.c）；配网成功后smartconfig_task等待ESPTOUCH_DONE_BIT，打印OK并自动停止 SmartConfig、删除任务。

6.2 关闭 SmartConfig 配网

命令：

smartconfig 0

响应示例：

OK >

对应 wifi_cmd_stop_smart_config：调用esp_smartconfig_stop()并删除配网任务。

6.3 注意事项

• 使用smartconfig 1开启配网并成功连接后，不需要再执行smartconfig 0，配网任务会在成功后自动停止。
• smartconfig 0仅在SmartConfig 配网失败时才有必要调用，用于手动终止配网流程。
• 若重复执行smartconfig 1，CLI 会回显SmartConfig Task has been created, Don't create repeatedly。
• 传入0、1之外的参数会回显Valid parameters are '0' and '1'。

6.4 配网操作步骤

按以下步骤完成一次完整的 SmartConfig 配网：

1. 下载 ESPTOUCH APP（Android 与 iOS 版本的官方源码链接见原文档 Commands.md 对应小节，属乐鑫官方 ESPTOUCH 应用仓库）。
2. 确保手机连接至目标 AP（必须是2.4GHz频段，ESPTOUCH 协议不兼容 5GHz）。
3. 打开 ESPTOUCH APP，输入目标 Wi-Fi 的密码并确认。
4. 在 PC 端通过 USB（CDC 串口）或 UART 端口发送smartconfig 1命令开始配网。

6.5 底层实现机制

配网逻辑由 smartconfig_task 承载：任务启动时通过esp_smartconfig_set_type(SC_TYPE_ESPTOUCH)设定协议类型，先断开当前 Wi-Fi 连接，再调用esp_smartconfig_start()进入监听状态；随后在事件循环中等待CONNECTED_BIT与ESPTOUCH_DONE_BIT，收到 SSID/密码事件后写入wifi_config_t并调用esp_wifi_connect()，配网完成（SC_EVENT_SEND_ACK_DONE）后自动停止并回收任务资源。若使用 ESPTOUCH V2 协议，事件回调还会通过esp_smartconfig_get_rvd_data读取设备附带数据。

七、scan：扫描周边 AP

功能：发起 Wi-Fi 扫描，列出附近 AP 的 SSID 与 RSSI。

扫描特定 SSID 的 AP：

scan <SSID>

扫描所有 AP：

scan

响应示例：

> [ssid][rssi=-22] >

说明：

• 扫描通过 wifi_cmd_sta_scan 实现：将可选 SSID 写入wifi_scan_config_t后调用esp_wifi_scan_start(&scan_config, false)异步扫描。
• 扫描结果由 scan_done_handler 异步回传：先通过esp_wifi_scan_get_ap_num获取 AP 数量，再读取wifi_ap_record_t数组，逐条以[ssid][rssi=xxx]格式回传；若未发现任何 AP 则回显No AP found。
• 由于扫描是异步的，命令执行后结果不会立即返回，需等待扫描完成事件（WIFI_EVENT_SCAN_DONE）触发回调后才会陆续输出。

八、ram：查看内存使用情况

功能：获取当前剩余堆内存大小，以及系统运行期间出现过的历史最小空闲堆内存大小（用于评估内存峰值占用）。

命令：

ram

响应示例：

free heap size: 132612, min heap size: 116788 >

实现位于 prvRamCommand：

• free heap size取自esp_get_free_heap_size()，即当前可用堆大小；
• min heap size取自heap_caps_get_minimum_free_size(MALLOC_CAP_DEFAULT)，即自启动以来空闲堆的最低水位，可用来判断系统是否曾接近内存耗尽。

该命令在排查内存泄漏、评估功能叠加对 RAM 的影响时非常实用。

九、restart：软件复位系统

功能：对芯片执行软件复位（重启）。

命令：

restart

实现位于 prvRestartCommand，直接调用esp_restart()。命令执行后设备立即重启，USB 连接会短暂断开后重新枚举，无需复位按键即可恢复设备状态，适合在远程调试或自动化测试场景中使用。

十、version：查询芯片与 IDF 版本

功能：获取当前 ESP-IDF 版本号与芯片基本信息。

命令：

version

响应示例：

IDF Version:v4.4-dev-2571-gb1c3ee71c5 Chip info: cores:1 feature:/802.11bgn/External-Flash:2 MB revision number:0 >

实现位于 prvGetVersionCommand：

• IDF Version取自esp_get_idf_version()；
• cores为 CPU 核心数，来自esp_chip_info()；
• feature根据esp_chip_info的 features 位拼接：支持 802.11bgn 则显示/802.11bgn，支持 BLE 显示/BLE、支持经典蓝牙显示/BT，Flash 类型由CHIP_FEATURE_EMB_FLASH位区分（Embedded-Flash或External-Flash），容量由esp_flash_get_physical_size()获取并以 MB 显示；
• revision number为芯片硅版本号。

该命令可用于快速确认设备固件与芯片版本，便于排查版本相关的兼容性问题。

十一、从源码看 CLI 的注册与扩展机制

如果希望在 USB Dongle 方案中增加自定义命令，可参照 vRegisterCLICommands 的实现模式：

1. 定义CLI_Command_Definition_t结构体，包含命令名、Help 字符串、回调函数与参数个数（-1表示参数个数不限，0表示无参数，1表示恰好 1 个参数）。
2. 在回调函数中通过FreeRTOS_CLIGetParameter按位置获取参数（参数间以空格分隔），执行实际逻辑后将结果写入输出缓冲。
3. 在vRegisterCLICommands()中调用FreeRTOS_CLIRegisterCommand()注册（Wi-Fi 类命令建议放入#if CFG_TUD_NCM || CFG_TUD_ECM_RNDIS条件编译块内，与现有命令保持一致）。
4. 启动流程在 usb_dongle_main.c 中调用vRegisterCLICommands()完成注册。

命令输入缓冲（80 字节）与输出缓冲（1024 字节）的定义位于 Command_Parse.c，若新增命令的输出较长，需注意输出缓冲上限。

十二、常见使用流程串联

以下是一个典型的 USB Dongle 配网上网完整流程：

1. 按 README.md 完成硬件连接（ESP32-S2/S3 的 USB D+/D- 对应 GPIO20/GPIO19，ESP32-P4 见 README 引脚表）与固件编译烧录（idf.py -p (PORT) build flash monitor）。
2. 将设备插入 PC，Host 侧出现 USB 网卡（Linux 用ifconfig -a查看，Windows 使用 RNDIS、MAC 使用 ECM）与 CDC 串口设备。
3. 打开串口终端连接 CDC 口，输入help确认命令可用。
4. 输入scan查看周边 AP，或直接输入sta -s <ssid> -p <password>手动连接路由器；若路由器密码未知，可输入smartconfig 1配合手机 ESPTOUCH App 一键配网。
5. 连接成功后设备回显相关信息，Host 的 USB 网卡获得 IP 即可上网；输入ram可监控内存余量，输入version可确认固件版本。
6. 需要恢复时输入sta -d断开连接，输入restart软复位设备。

命令的完整参考（中英双语）见 Commands.md 与 Commands_EN.md，更多关于 USB 网络类支持组合、DFU 升级与平台差异（Windows/MAC/Linux）的说明可查阅 USB Dongle README。

• 物联网
• 嵌入式
• 驱动开发
• 硬件开发