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>[,<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

  • <buffer_size>：数据缓冲区大小（字节）

    • 范围[1,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,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