.. _WiFi-AT: Wi-Fi AT 命令集 ======================= :link_to_translation:`en:[English]` - :ref:`AT+CWMODE `：查询/设置 Wi-Fi 模式 (Station/SoftAP/Station+SoftAP) - :ref:`AT+CWSTATE `：查询 Wi-Fi 状态和 Wi-Fi 信息 - :ref:`AT+CWJAP `：连接 AP - :ref:`AT+CWRECONNCFG `：查询/设置 Wi-Fi 重连配置 - :ref:`AT+CWLAPOPT `：设置 :ref:`AT+CWLAP ` 命令扫描结果的属性 - :ref:`AT+CWLAP `：扫描当前可用的 AP - :ref:`AT+CWQAP `：断开与 AP 的连接 - :ref:`AT+CWSAP `：配置 ESP32 SoftAP 参数 - :ref:`AT+CWLIF `：查询连接到 ESP SoftAP 的 station 信息 - :ref:`AT+CWQIF `：断开 station 与 ESP SoftAP 的连接 - :ref:`AT+CWDHCP `：启用/禁用 DHCP - :ref:`AT+CWDHCPS `：查询/设置 ESP SoftAP DHCP 分配的 IP 地址范围 - :ref:`AT+CWAUTOCONN `：上电是否自动连接 AP - :ref:`AT+CWAPPROTO `：查询/设置 SoftAP 模式下 802.11 b/g/n 协议标准 - :ref:`AT+CWSTAPROTO `：设置 Station 模式下 802.11 b/g/n 协议标准 - :ref:`AT+CIPSTAMAC `：查询/设置 ESP Station 的 MAC 地址 - :ref:`AT+CIPAPMAC `：查询/设置 ESP SoftAP 的 MAC 地址 - :ref:`AT+CIPSTA `：查询/设置 ESP Station 的 IP 地址 - :ref:`AT+CIPAP `：查询/设置 ESP SoftAP 的 IP 地址 - :ref:`AT+CWSTARTSMART `：开启 SmartConfig - :ref:`AT+CWSTOPSMART `：停止 SmartConfig - :ref:`AT+WPS `：设置 WPS 功能 - :ref:`AT+MDNS `：设置 mDNS 功能 - [ESP32 Only] :ref:`AT+CWJEAP `：连接 WPA2 企业版 AP - :ref:`AT+CWHOSTNAME `：查询/设置 ESP Station 的主机名称 - :ref:`AT+CWCOUNTRY `：查询/设置 Wi-Fi 国家代码 .. _cmd-MODE: :ref:`AT+CWMODE `：查询/设置 Wi-Fi 模式 (Station/SoftAP/Station+SoftAP) ------------------------------------------------------------------------------------- 查询命令 ^^^^^^^^ **功能：** 查询 ESP 设备的 Wi-Fi 模式 **命令：** :: AT+CWMODE? **响应：** :: +CWMODE: OK 设置命令 ^^^^^^^^ **功能：** 设置 ESP 设备的 Wi-Fi 模式 **命令：** :: AT+CWMODE=[,] **响应：** :: OK 参数 ^^^^ - ****：模式 - 0: 无 Wi-Fi 模式，并且关闭 Wi-Fi RF - 1: Station 模式 - 2: SoftAP 模式 - 3: SoftAP+Station 模式 - ****：切换 ESP 设备的 Wi-Fi 模式时（例如，从 SoftAP 或无 Wi-Fi 模式切换为 Station 模式或 SoftAP+Station 模式），是否启用自动连接 AP 的功能，默认值：1。参数缺省时，使用默认值，也就是能自动连接。 - 0: 禁用自动连接 AP 的功能 - 1: 启用自动连接 AP 的功能，若之前已经将自动连接 AP 的配置保存到 flash 中，则 ESP 设备将自动连接 AP 说明 ^^^^ - 若 :ref:`AT+SYSSTORE=1 `，本设置将保存在 NVS 分区 示例 ^^^^ :: AT+CWMODE=3 .. _cmd-WSTATE: :ref:`AT+CWSTATE `：查询 Wi-Fi 状态和 Wi-Fi 信息 ------------------------------------------------------------- 查询命令 ^^^^^^^^ **功能：** 查询 ESP 设备的 Wi-Fi 状态和 Wi-Fi 信息 **命令：** :: AT+CWSTATE? **响应：** :: +CWSTATE:,<"ssid"> OK 参数 ^^^^ - ****：当前 Wi-Fi 状态 - 0: ESP station 尚未进行任何 Wi-Fi 连接 - 1: ESP station 已经连接上 AP，但尚未获取到 IPv4 地址 - 2: ESP station 已经连接上 AP，并已经获取到 IPv4 地址 - 3: ESP station 正在进行 Wi-Fi 连接或 Wi-Fi 重连 - 4: ESP station 处于 Wi-Fi 断开状态 - **<"ssid">**：目标 AP 的 SSID 说明 ^^^^ - 当 ESP station 没有连接上 AP 时，推荐使用此命令查询 Wi-Fi 信息；当 ESP station 已连接上 AP 后，推荐使用 :ref:`AT+CWJAP ` 命令查询 Wi-Fi 信息 .. _cmd-JAP: :ref:`AT+CWJAP `：连接 AP ------------------------------------------------ 查询命令 ^^^^^^^^ **功能：** 查询与 ESP Station 连接的 AP 信息 **命令：** :: AT+CWJAP? **响应：** :: +CWJAP:,,,,,,,, OK 设置命令 ^^^^^^^^ **功能：** 设置 ESP Station 需连接的 AP **命令：** :: AT+CWJAP=[],[][,][,][,][,][,][,][,] **响应：** :: WIFI CONNECTED WIFI GOT IP OK [WIFI GOT IPv6 LL] [WIFI GOT IPv6 GL] 或 :: +CWJAP: ERROR 执行命令 ^^^^^^^^ **功能：** 将 ESP station 连接至上次 Wi-Fi 配置中的 AP **命令：** :: AT+CWJAP **响应：** :: WIFI CONNECTED WIFI GOT IP OK [WIFI GOT IPv6 LL] [WIFI GOT IPv6 GL] 或 :: +CWJAP: ERROR 参数 ^^^^ - ****：目标 AP 的 SSID - 如果 SSID 和密码中有 ``,``、``"``、``\\`` 等特殊字符，需转义 - ****：密码最长 64 字节 ASCII - ****：目标 AP 的 MAC 地址，当多个 AP 有相同的 SSID 时，该参数不可省略 - ****：信道号 - ****：信号强度 - ****：PCI 认证 - 0: ESP station 可与任何一种加密方式的 AP 连接，包括 OPEN 和 WEP - 1: ESP station 可与除 OPEN 和 WEP 之外的任何一种加密方式的 AP 连接 - ****：Wi-Fi 重连间隔，单位：秒，默认值：1，最大值：7200 - 0: 断开连接后，ESP station 不重连 AP - [1,7200]: 断开连接后，ESP station 每隔指定的时间与 AP 重连 - ****：监听 AP beacon 的间隔，单位为 AP beacon 间隔，默认值：3，范围：[1,100] - ****：扫描模式 - 0: 快速扫描，找到目标 AP 后终止扫描，ESP station 与第一个扫描到的 AP 连接 - 1: 全信道扫描，所有信道都扫描后才终止扫描，ESP station 与扫描到的信号最强的 AP 连接 - ****：:ref:`AT+CWJAP ` 命令超时的最大值，单位：秒，默认值：15，范围：[3,600] - ****：PMF（Protected Management Frames，受保护的管理帧），默认值 0 - 0 表示禁用 PMF - bit 0: 具有 PMF 功能，提示支持 PMF，如果其他设备具有 PMF 功能，则 ESP 设备将优先选择以 PMF 模式连接 - bit 1: 需要 PMF，提示需要 PMF，设备将不会关联不支持 PMF 功能的设备 - ****：错误码，仅供参考 - 1: 连接超时 - 2: 密码错误 - 3: 无法找到目标 AP - 4: 连接失败 - 其它值: 发生未知错误 说明 ^^^^ - 如果 :ref:`AT+SYSSTORE=1 `，配置更改将保存到 NVS 分区 - 使用本命令需要开启 station 模式 - 本命令中的 ```` 参数与 :ref:`AT+CWRECONNCFG ` 命令中的 ```` 参数相同。如果运行本命令时不设置 ```` 参数，Wi-Fi 重连间隔时间将采用默认值 1 - 如果同时省略 ```` 和 ```` 参数，将使用上一次设置的值 - 执行命令与设置命令的超时时间相同，默认为 15 秒，可通过参数 ```` 设置 - 想要获取 IPv6 地址，需要先设置 :ref:`AT+CIPV6=1 ` - 回复 ``OK`` 代表 IPv4 网络已经准备就绪，而不代表 IPv6 网络准备就绪。当前 ESP-AT 以 IPv4 网络为主，IPv6 网络为辅。 - ``WIFI GOT IPv6 LL`` 代表已经获取到本地链路 IPv6 地址，这个地址是通过 EUI-64 本地计算出来的，不需要路由器参与。由于并行时序，这个打印可能在 ``OK`` 之前，也可能在 ``OK`` 之后。 - ``WIFI GOT IPv6 GL`` 代表已经获取到全局 IPv6 地址，该地址是由 AP 下发的前缀加上内部计算出来的后缀进行组合而来的，需要路由器参与。由于并行时序，这个打印可能在 ``OK`` 之前，也可能在 ``OK`` 之后；也可能由于 AP 不支持 IPv6 而不打印。 示例 ^^^^ :: // 如果目标 AP 的 SSID 是 "abc"，密码是 "0123456789"，则命令是： AT+CWJAP="abc","0123456789" // 如果目标 AP 的 SSID 是 "ab\,c"，密码是 "0123456789"\"，则命令是： AT+CWJAP="ab\\\,c","0123456789\"\\" // 如果多个 AP 有相同的 SSID "abc"，可通过 BSSID 找到目标 AP： AT+CWJAP="abc","0123456789","ca:d7:19:d8:a6:44" // 如果 ESP-AT 要求通过 PMF 连接 AP，则命令是： AT+CWJAP="abc","0123456789",,,,,,,3 .. _cmd-RECONNCFG: :ref:`AT+CWRECONNCFG `：查询/设置 Wi-Fi 重连配置 ------------------------------------------------------------------------------------------- 查询命令 ^^^^^^^^ **功能：** 查询 Wi-Fi 重连配置 **命令：** :: AT+CWRECONNCFG? **响应：** :: +CWRECONNCFG:, OK 设置命令 ^^^^^^^^ **功能：** 设置 Wi-Fi 重连配置 **命令：** :: AT+CWRECONNCFG=, **响应：** :: OK 参数 ^^^^ - ****：Wi-Fi 重连间隔，单位：秒，默认值：0，最大值 7200 - 0: 断开连接后，ESP station 不重连 AP - [1,7200]: 断开连接后，ESP station 每隔指定的时间与 AP 重连 - ****：ESP 设备尝试重连 AP 的次数，本参数在 ```` 不为 0 时有效，默认值：0，最大值：1000 - 0: ESP station 始终尝试连接 AP - [1,1000]: ESP station 按照本参数指定的次数重连 AP 示例 ^^^^ :: // ESP station 每隔 1 秒尝试重连 AP，共尝试 100 次 AT+CWRECONNCFG=1,100 // ESP station 在断开连接后不重连 AP AT+CWRECONNCFG=0,0 说明 ^^^^ - 本命令中的 ```` 参数与 :ref:`AT+CWJAP ` 中的 ``[]`` 参数相同 - 该命令适用于被动断开 AP、Wi-Fi 模式切换和开机后 Wi-Fi 自动连接 .. _cmd-LAPOPT: :ref:`AT+CWLAPOPT `：设置 :ref:`AT+CWLAP ` 命令扫描结果的属性 ---------------------------------------------------------------------------------------------------- 设置命令 ^^^^^^^^ **命令：** :: AT+CWLAPOPT=,[,][,] **响应：** :: OK 或者 :: ERROR 参数 ^^^^ - ****：保留项 - ****：:ref:`AT+CWLAP ` 的扫描结果是否显示以下参数，默认值：0x7FF，若 bit 设为 1，则显示对应参数，若设为 0，则不显示对应参数 - bit 0: 是否显示 - bit 1: 是否显示 - bit 2: 是否显示 - bit 3: 是否显示 - bit 4: 是否显示 - bit 5: 是否显示 - bit 6: 是否显示 - bit 7: 是否显示 - bit 8: 是否显示 - bit 9: 是否显示 - bit 10: 是否显示 - **[]**：:ref:`AT+CWLAP ` 的扫描结果是否按照本参数过滤，也即，是否过滤掉信号强度低于 ``rssi filter`` 参数值的 AP，单位：dBm，默认值：–100，范围：[–100,40] - **[]**：:ref:`AT+CWLAP ` 的扫描结果是否显示以下认证方式的 AP，默认值：0xFFFF，如果 ``bit x`` 设为 1，则显示对应认证方式的 AP，若设为 0，则不显示 - bit 0: 是否显示 ``OPEN`` 认证方式的 AP - bit 1: 是否显示 ``WEP`` 认证方式的 AP - bit 2: 是否显示 ``WPA_PSK`` 认证方式的 AP - bit 3: 是否显示 ``WPA2_PSK`` 认证方式的 AP - bit 4: 是否显示 ``WPA_WPA2_PSK`` 认证方式的 AP - bit 5: 是否显示 ``WPA2_ENTERPRISE`` 认证方式的 AP - bit 6: 是否显示 ``WPA3_PSK`` 认证方式的 AP - bit 7: 是否显示 ``WPA2_WPA3_PSK`` 认证方式的 AP - [ESP32-C3 Only] bit 8: 是否显示 ``WAPI_PSK`` 认证方式的 AP 示例 ^^^^ :: // 第一个参数为 1，表示 AT+CWLAP 命令扫描结果按照信号强度 RSSI 值排序 // 第二个参数为 31，即 0x1F，表示所有值为 1 的 bit 对应的参数都会显示出来 AT+CWLAPOPT=1,31 AT+CWLAP // 只显示认证方式为 OPEN 的 AP AT+CWLAPOPT=1,31,-100,1 AT+CWLAP .. _cmd-LAP: :ref:`AT+CWLAP `：扫描当前可用的 AP ------------------------------------------------------ 设置命令 ^^^^^^^^ **功能：** 列出符合特定条件的 AP，如指定 SSID、MAC 地址或信道号 **命令：** :: AT+CWLAP=[,,,,,] 执行命令 ^^^^^^^^ **功能：** 列出当前可用的 AP **命令：** :: AT+CWLAP **响应：** :: +CWLAP:,,,,,,,,,, OK 参数 ^^^^ - ****：加密方式 - 0: OPEN - 1: WEP - 2: WPA_PSK - 3: WPA2_PSK - 4: WPA_WPA2_PSK - 5: WPA2_ENTERPRISE - 6: WPA3_PSK - 7: WPA2_WPA3_PSK - [ESP32-C3 Only] 8: WAPI_PSK - ****：字符串参数，AP 的 SSID - ****：信号强度 - ****：字符串参数，AP 的 MAC 地址 - ****：信道号 - ****：Wi-Fi 扫描类型 - 0: 主动扫描 - 1: 被动扫描 - ****：每个信道最短扫描时间，单位：毫秒，范围：[0,1500]，如果扫描类型为被动扫描，本参数无效 - ****：每个信道最长扫描时间，单位：毫秒，范围：[0,1500]，如果设为 0，固件采用参数默认值，主动扫描为 120 ms，被动扫描为 360 ms - ****：频偏（保留项目） - ****：频率校准值（保留项目） - ****：成对加密类型 - 0: None - 1: WEP40 - 2: WEP104 - 3: TKIP - 4: CCMP - 5: TKIP and CCMP - 6: AES-CMAC-128 - 7: 未知 - ****：组加密类型，与 ```` 参数的枚举值相同 - ****：802.11 b/g/n，若 bit 设为 1，则表示使能对应模式，若设为 0，则表示禁用对应模式 - bit 0: 是否使能 802.11b 模式 - bit 1: 是否使能 802.11g 模式 - bit 2: 是否使能 802.11n 模式 - ****：wps flag - 0: 不支持 WPS - 1: 支持 WPS 说明 ^^^^ - 对于 ESP8266 设备，**** 和 **** 必须设置为相同的值。如果这两个参数被省略或者同时设置为 0 或者设置的值不相等，则固件采用参数默认值，主动扫描为 120 ms，被动扫描为 360 ms。 示例 ^^^^ :: AT+CWLAP="Wi-Fi","ca:d7:19:d8:a6:44",6,0,400,1000 // 寻找指定 SSID 的 AP AT+CWLAP="Wi-Fi" .. _cmd-QAP: :ref:`AT+CWQAP `：断开与 AP 的连接 ------------------------------------------------------ 执行命令 ^^^^^^^^ **命令：** :: AT+CWQAP **响应：** :: OK .. _cmd-SAP: :ref:`AT+CWSAP `：配置 ESP SoftAP 参数 ------------------------------------------------------------- 查询命令 ^^^^^^^^ **功能：** 查询 ESP SoftAP 的配置参数 **命令：** :: AT+CWSAP? **响应：** :: +CWSAP:,,,,,