WebSocket AT 命令集

备注

• Websocket AT 命令集默认未启用。

• 参考 配置 SDK（menuconfig） 进入 CONFIG AT CMD 配置，勾选 Enable WebSocket 来启用 WebSocket AT 命令集。

AT+WSGLCFG

功能说明

配置 WebSocket 客户端全局参数

命令格式

AT+WSGLCFG=[<connect_timeout>][,<recv_timeout>][,<send_timeout>][,<send_blocktime>][,<keepalive_idle>][,<keepalive_interval>][,<keepalive_count>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<connect_timeout>:

连接超时时间（毫秒）

• 非负整数

• 默认值：0（无限等待）

<recv_timeout>:

接收超时（毫秒）

• 非负整数

• 默认值：0（无超时）

<send_timeout>:

发送超时（毫秒）

• 非负整数

• 默认值：0（无超时）

<send_blocktime>:

发送阻塞时间（毫秒）

• 非负整数

• 特殊值 0 表示立即返回

<keepalive_idle>:

TCP 保活探测起始时间（秒）

• 范围[1,7200]

• 默认值：0（禁用）

<keepalive_interval>:

保活探测间隔（秒）

• 范围[1,75]

• 默认值：0（禁用）

<keepalive_count>:

保活探测次数

• 范围[1,10]

• 默认值：0（禁用）

错误代码

• 1: 参数范围错误

示例

配置全局参数：

AT+WSGLCFG=5,2000,2000,0,300,5,3

OK

AT+WSCFG

功能说明

配置指定连接 ID 的 WebSocket 客户端参数

命令格式

AT+WSCFG=<link_id>,<ping_interval>,<ping_timeout>[,<tx_buffer_size>][,<rx_buffer_size>][,<max_queue_size>][,<protocol>][,<version>][,<stable_buf_num>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

<ping_interval>:

Ping 心跳间隔（秒）

• 范围[1,7200]

• 默认值：10

<ping_timeout>:

Ping 超时时间（秒）

• 范围[1,7200]

• 默认值：120

<tx_buffer_size>:

发送数据缓冲区大小（字节）

• 范围[1500,16384]

• 默认值：1500

<rx_buffer_size>:

接收数据缓冲区大小（字节）

• 范围[1500,16384]

• 默认值：1500

<max_queue_size>:

最大队列深度

• 范围[1,50]

• 默认值：3

<protocol>:

子协议类型

• 字符串格式（如”chat”,”superchat”）

• 默认值：空

<version>:

协议版本

• 当前仅支持”13”

• 默认值：13

<stable_buf_num>:

稳定缓冲区数量

• 范围[1,<max_queue_size>]

• 默认值：3

错误代码

• 1: 参数超出范围

• 2: 内存申请失败

示例

配置连接 ID 0 的相关参数：

AT+WSCFG=0,30,120,2048,1500,5,"chat",13,3

OK

AT+WSHEAD

功能说明

配置 Websocket 客户端的请求头。

一些 Websocket 服务器在连接的时候客户端需要提供 Authorization ， Cookie 或者 Origin 等请求头，可以使用该命令进行添加。

每条连接 ID 支持最大 10 条请求头

命令格式

AT+WSHEAD=<link_id>,<header_len>[,<header>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

<header_len>:

请求头长度

• 整条命令受到 命令长度 限制

• 0：清除所有请求头

<header>:

请求头数据

错误代码

• 1: 参数超出范围

• 2: 内存申请失败

• 3: 连接头数量超过最大值

示例

配置连接 ID 1 的 2 条请求头：

AT+WSHEAD=1,26,Origin: http://example.com

OK
AT+WSHEAD=1,24,Cookie: sessionId=abc789

OK

AT+WSHEADRAW

功能说明

用 透传（TT）模式 配置 Websocket 客户端的请求头。

适用于单条请求头长度超过 2000 字节或者请求头中包含转义字符的场景。

一些 Websocket 服务器在连接的时候客户端需要提供 Authorization ， Cookie 或者 Origin 等请求头，可以使用该命令进行添加。

每条连接 ID 支持最大 10 条请求头

备注

该命令仅支持在 主控控制模式 下使用。

命令格式

AT+WSHEADRAW=<link_id>,<header_len>

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

<header_len>:

请求头长度

• 长度无限制

• 0：清除所有请求头

错误代码

• 1: 参数超出范围

• 2: 内存申请失败

• 3: 进入 TT 模式失败

• 4: 连接头数量超过最大值

示例

配置连接 ID 1 的 2 条请求头：

AT+WSHEADRAW=1,39
>>>
Sec-WebSocket-Protocol: chat, superchat

OK

AT+WSCONN

功能说明

建立 WebSocket 客户端连接

命令格式

AT+WSCONN=<link_id>,<host>[,<path>][,<port>],<conn_type>[,<cert_index>]

响应格式

成功响应：

[$][WS][EVENT]:linkid:<link_id>, connected

OK

错误响应：

ERROR:<error_no>

AT 消息

当连接成功时，会有如下提示消息：

[$][WS][EVENT]:linkid:<link_id>, connected

当连接断开时，会有如下提示消息：

[$][WS][EVENT]:linkid:<link_id>, disconnect

当收到 PONG 消息的时候，会如下提示消息：

[$][WS][EVENT]:linkid:%d, pong

当收到数据包的时候，会如下提示消息：

[$][WS][DATA][<link_id>][<数据长度>]:<数据>

参数

<link_id>:

连接 ID

• 有效范围：0-2

<host>:

目标主机，不需要 ws:// 或者 wss:// 前缀

• 支持域名或 IPv4 地址

• 最大长度：128 字符

<path>:

资源路径

• 默认值：”/”

• 最大长度：256 字符

<port>:

端口

• 范围：[0,65535] （默认值 0）

• 0： WS 使用 80 端口， WSS 使用 443 端口

<conn_type>:

连接类型

• 1: Websocket over TCP

• 2: Websocket over TLS（不校验证书）

• 3: Websocket over TLS（用 CA 证书验证服务器证书）

• 4: Websocket over TLS（提供客户端证书给服务器验证）

• 5: Websocket over TLS（双向认证，3 和 4 的合集）

<cert_index>:

安全证书套件索引，参考 AT 安全证书

• [1-10]

• 仅<conn_type>是 3-5 时需要

错误代码

• 1: 参数超出范围

• 2: 内存申请失败

• 3: 套接字创建失败

• 4: 证书加载失败

• 5: 连接服务器失败

• 6: 连接任务创建失败

示例

使用 8433 端口建立 wss 连接，并用 1 号证书套件的 CA 证书验证服务器：

AT+WSCONN=0,echo.websocket.org,/chat,8433,3,1
[$][WS][EVENT]:linkid:0, connected

OK

AT+WSSEND

功能说明

发送 WebSocket 数据

命令格式

AT+WSSEND=<link_id>,<length>[,<use_mask>][,<opcode>],<data>

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

<length>:

数据长度

• 最大值：AT+WSCFG 中<buffer_size>参数定义的大小

<use_mask>:

数据掩码

• 0: 禁用

• 1: 启用（默认）

<opcode>:

帧类型

• 0: CONTINUATION 帧

• 1: 文本帧 （默认）

• 2: 二进制帧

• 8: 关闭帧

• 9: PING 帧

• 10: PONG 帧

<data>:

待发送的数据

错误代码

• 1: 参数超出范围

• 2: 连接不可用

示例

发送文本消息：

AT+WSSEND=0,11,1,1,HelloWorld!

OK

AT+WSSENDRAW

功能说明

用 透传（TT）模式 发送 WebSocket 数据。

备注

该命令仅支持在 主控控制模式 下使用。

命令格式

AT+WSSENDRAW=<link_id>,<length>[,<use_mask>][,<opcode>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

<length>:

数据长度

• 无长度限制

<use_mask>:

数据掩码

• 0: 禁用

• 1: 启用（默认）

<opcode>:

帧类型

• 0: CONTINUATION 帧

• 1: 文本帧 （默认）

• 2: 二进制帧

• 8: 关闭帧

• 9: PING 帧

• 10: PONG 帧

错误代码

• 1: 参数超出范围

• 2: 连接不可用

• 3: 内存申请失败

• 4: 进入 TT 模式失败

示例

发送 10 个字节的文本消息：

AT+WSSENDRAW=0,10,1,1
>>>
1234567890

OK

AT+WSDISCONN

功能说明

主动关闭指定连接 ID 的 WebSocket 客户端连接

命令格式

AT+WSDISCONN=<link_id>

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

错误代码

• 1: 参数超出范围

• 2: 连接不可用

示例

关闭连接 ID 0 的连接：

AT+WSDISCONN=0

OK
[$][WS][EVENT]:linkid:0, disconnect

AT+WSQUERY

功能说明

查询 Websocket 客户端相关信息，包括全局配置信息或者指定连接 ID 的信息

命令格式

AT+WSQUERY=[<link_id>]

响应格式

成功响应：

Global config:
connect_timeout: <连接超时时间（秒）>
recv_timeout: <接收超时（毫秒）>
send_timeout: <发送超时（毫秒）>
send_blocktime: <发送阻塞时间（毫秒）>
keepalive_idle: <TCP 保活探测起始时间（秒）>
keepalive_interval: <保活探测间隔（秒）>
keepalive_count: <保活探测次数>
link_id: <连接 ID>
status: <连接状态，0：关闭中，1：已关闭，2，连接中，3，已连接>
ping_interval: <Ping 心跳间隔（秒）>
ping_timeout: <Ping 超时时间（秒）>
buffer_size: <数据缓冲区大小（字节）>
max_queue_size: <最大队列深度>
protocol: <子协议类型>
version: <协议版本>
stable_buf_num: <稳定缓冲区数量>
header:
<请求头信息 1>
<请求头信息 2>
...

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

• 缺省该参数将输出所有连接 ID 信息

错误代码

• 1: 参数超出范围

示例

查询连接 ID 0 的相关信息：

AT+WSQUERY=0
Global config:
connect_timeout: 3000
recv_timeout: 3000
send_timeout: 3000
send_blocktime: 4000
keepalive_idle: 0
keepalive_interval: 0
keepalive_count: 0
link_id: 0
status: 3
ping_interval: 20
ping_timeout: 60
buffer_size: 4096
max_queue_size: 12
protocol:
version: 13
stable_buf_num: 8
header:
Sec-WebSocket-Protocol: chat, superchat
Origin: http://example.com

OK

AT+WSTXQUEUECHECK

功能说明

检查指定连接 ID 的 tx 队列是否已满

命令格式

AT+WSTXQUEUECHECK=<link_id>

响应格式

成功响应:

OK

错误响应:

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

错误代码

• 1: 参数超出范围

• 2: 连接不可用

示例

检查连接 ID 0 的 tx 队列:

AT+WSTXQUEUECHECK=0

OK
Tx queue is not full

AT+WSSRVCFG

功能说明

配置 WebSocket 服务器参数

命令格式

AT+WSSRVCFG=[<max_conn>][,<ping_interval>][,<idle_timeout>][,<tx_size>][,<rx_size>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<max_conn>:

最大连接数量

• 范围[1,3]

• 默认值：3

<ping_interval>:

ping 包间隔（秒）

• 范围[1,7200]

• 默认值：30

<idle_timeout>:

空闲超时（秒）

• 连续没有任何报文通信的时间超过空闲超时将主动关闭连接

• 范围[0,7200]

• 默认值：0（无超时）

<tx_size>:

发送缓存（字节）

• 范围[1,16384]

• 默认值：4096

<rx_size>:

接收缓存（字节）

• 范围[1,16384]

• 默认值：4096

错误代码

• 1: 参数范围错误

示例

配置 Websocket 服务器参数：

AT+WSSRVCFG=2,30,90,16384,16384

OK

AT+WSSRVSTART

功能说明

启动 WebSocket 服务器

命令格式

AT+WSSRVSTART=[<port>],<conn_type>[,<cert_index>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

AT 消息

当有客户端成功连接时，会有如下提示消息

[$][WSSRV][EVENT]:linkid:<link_id>, connected

当连接断开时，会有如下提示消息

[$][WSSRV][EVENT]:linkid:<link_id>, disconnected, reason:<断开原因>

当收到数据包的时候，会如下提示消息

[$][WSSRV][DATA][<link_id>][<opcode>][<数据长度>]:<数据>

备注

断开原因列表

• 1: 创建连接失败

• 2: 连接初始化失败

• 3: 客户端主动断开

• 4: 服务器主动断开

• 5: TLS 握手失败

• 6: TLS 握手超时

• 7: Select 监听失败

• 9: Socket 设置失败

• 10: 读取失败

• 11: 发送失败

• 13: PING 响应超时

• 14: 空闲超时

参数

<port>:

端口

• 范围：[0,65535] （默认值 0）

• 0： WS 使用 80 端口， WSS 使用 443 端口

<conn_type>:

连接类型

• 1: Websocket Server over TCP

• 2: Websocket Server over TLS（提供服务器证书给客户端验证）

• 3: Websocket Server over TLS（提供服务器证书给客户端验证并且用 CA 证书验证客户端证书）

<cert_index>:

安全证书套件索引，参考 AT 安全证书

• [1-10]

• 仅<conn_type>是 2 和 3 时需要

错误代码

• 1: 参数范围错误

• 2: 服务器已运行

• 3: 获取证书套件失败

• 4: 内存申请失败

• 5: 设置证书失败

• 6: 启动服务器失败

示例

在端口 80 上启动 Websocket 服务器：

AT+WSSRVSTART=0,1

OK

在端口 8433 启动 TLS 的 Websocket 服务器，并使用服务器证书套件 2：

AT+WSSRVSTART=8433,2,2

OK

AT+WSSRVDISCONN

功能说明

断开指定连接 ID 的 WebSocket 客户端连接

命令格式

AT+WSSRVDISCONN=<link_id>

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 范围：[0,2]

错误代码

• 1: 参数范围错误

• 2: 连接不可用

示例

断开连接 ID 2 的客户端连接：

AT+WSSRVDISCONN=2

OK

AT+WSSRVSTOP

功能说明

关闭 WebSocket 服务器

命令格式

AT+WSSRVSTOP

响应格式

成功响应：

OK

参数

无

错误代码

无

AT+WSSRVSEND

功能说明

向指定连接 ID 发送 WebSocket 数据

命令格式

AT+WSSRVSEND=<link_id>,<length>[,<opcode>],<data>

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

<length>:

数据长度

• 最大值：AT+WSSRVCFG 中<tx_buff>参数定义的大小

<opcode>:

帧类型

• 0: CONTINUATION 帧

• 1: 文本帧 （默认）

• 2: 二进制帧

• 8: 关闭帧

• 9: PING 帧

• 10: PONG 帧

<data>:

待发送的数据

错误代码

• 1: 参数范围错误

• 2: 内存申请失败

示例

向连接 ID 1 发送发送文本消息：

AT+WSSRVSEND=1,11,1,HelloWorld!

OK

AT+WSSRVSENDRAW

功能说明

用 透传（TT）模式 向指定连接 ID 发送 WebSocket 数据。

备注

该命令仅支持在 主控控制模式 下使用。

命令格式

AT+WSSRVSENDRAW=<link_id>,<length>[,<opcode>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数

<link_id>:

连接 ID

• 有效范围：0-2

<length>:

数据长度

• 无长度限制

<opcode>:

帧类型

• 0: CONTINUATION 帧

• 1: 文本帧 （默认）

• 2: 二进制帧

• 8: 关闭帧

• 9: PING 帧

• 10: PONG 帧

错误代码

• 1: 参数范围错误

• 2: 内存申请失败

• 3: 进入 TT 模式失败

示例

向连接 ID 0 发送 10 个字节的文本消息：

AT+WSSRVSENDRAW=0,10,1
>>>
1234567890

OK

AT+WSSRVQUERY

功能说明

查询 Websocket 服务端相关信息，包括全局配置信息和所有连接 ID 的信息

命令格式

AT+WSSRVQUERY

响应格式

成功响应：

port:
max_conn: <端口>
ping_interval: <ping 包间隔（秒）>
idle_timeout: <空闲超时（秒）>
tx_size: <发送缓存（字节）>
rx_size: <接收缓存（字节）>
link_id: <连接 ID>
status: <连接状态，0：已关闭，1：连接中，2，已连接，3，已连接，且发送了 ping 包，暂未收到 pong 包，4：关闭中>
ip: <客户端 ipv4 地址>
link_id: <连接 ID>
status: <连接状态，0：已关闭，1：连接中，2，已连接，3，已连接，且发送了 ping 包，暂未收到 pong 包，4：关闭中>
ip: <客户端 ipv4 地址>
...

OK

参数

无

错误代码

无

示例

查询 Websocket 服务器的相关信息：

AT+WSSRVQUERY
port: 1000
max_conn: 3
ping_interval: 30
idle_timeout: 0
tx_size: 4096
rx_size: 4096
link_id: 0
status: 2
ip: 192.168.1.105

OK