WebSocket AT Commands

Note

The WebSocket AT commands are disabled by default.

You can refer to Configuring SDK (menuconfig) to enter CONFIG AT CMD configuration and check Enable WebSocket to enable the WebSocket AT commands.

AT+WSGLCFG

Function Description

Configure WebSocket client global parameters

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <connect_timeout>: Connection timeout (milliseconds)

    • Non-negative integer

    • Default value: 0 (wait indefinitely)

  • <recv_timeout>: Receive timeout (milliseconds)

    • Non-negative integer

    • Default value: 0 (no timeout)

  • <send_timeout>: Send timeout (milliseconds)

    • Non-negative integer

    • Default value: 0 (no timeout)

  • <send_blocktime>: Send block time (milliseconds)

    • Non-negative integer

    • Special value 0 means return immediately

  • <keepalive_idle>: TCP keepalive probe start time (seconds)

    • Range [1,7200]

    • Default value: 0 (disabled)

  • <keepalive_interval>: Keepalive probe interval (seconds)

    • Range [1,75]

    • Default value: 0 (disabled)

  • <keepalive_count>: Number of keepalive probes

    • Range [1,10]

    • Default value: 0 (disabled)

Error Codes

  • 1: Parameter range error

Example

Configure global parameters:

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

OK

AT+WSCFG

Function Description

Configure WebSocket client parameters for a specified link ID

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

  • <ping_interval>: Ping heartbeat interval (seconds)

    • Range [1,7200]

    • Default value: 10

  • <ping_timeout>: Ping timeout (seconds)

    • Range [1,7200]

    • Default value: 120

  • <buffer_size>: Data buffer size (bytes)

    • Range [1,16384]

    • Default value: 1500

  • <max_queue_size>: Maximum queue depth

    • Range [1,50]

    • Default value: 3

  • <protocol>: Sub-protocol type

    • String format (e.g., “chat”, “superchat”)

    • Default value: empty

  • <version>: Protocol version

    • Currently only supports “13”

    • Default value: 13

  • <stable_buf_num>: Number of stable buffers

    • Range [1,<max_queue_size>]

    • Default value: 3

Error Codes

  • 1: Parameter range error

  • 2: Memory allocation failed

Example

Configure parameters for link ID 0:

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

OK

AT+WSHEAD

Function Description

Configure request headers for WebSocket client.

Some WebSocket servers require clients to provide headers such as Authorization, Cookie, or Origin during connection. This command can be used to add such headers.

Each link ID supports a maximum of 10 request headers.

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

  • <header_len>: Header length

    • The entire command is limited by Command Length

    • 0: Clear all headers

  • <header>: Header data

Error Codes

  • 1: Parameter range error

  • 2: Memory allocation failed

  • 3: Number of headers exceeds maximum

Example

Configure 2 request headers for link ID 1:

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

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

OK

AT+WSHEADRAW

Function Description

Configure request headers for WebSocket client using Transparent Transmission (TT) Mode.

Suitable for scenarios where a single header length exceeds 2000 bytes or contains escape characters.

Some WebSocket servers require clients to provide headers such as Authorization, Cookie, or Origin during connection. This command can be used to add such headers.

Each link ID supports a maximum of 10 request headers.

Note

This command is only supported in Master Control Mode.

Command Format

AT+WSHEADRAW=<link_id>,<header_len>

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

  • <header_len>: Header length

    • No length limit

    • 0: Clear all headers

Error Codes

  • 1: Parameter range error

  • 2: Memory allocation failed

  • 3: Failed to enter TT mode

  • 4: Number of headers exceeds maximum

Example

Configure 2 request headers for link ID 1:

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

OK

AT+WSCONN

Function Description

Establish a WebSocket client connection

Command Format

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

Response Format

Successful Response:

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

OK

Error Response:

ERROR:<error_no>

AT Messages

When a connection is successful, the following prompt message will appear:

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

When a connection is disconnected, the following prompt message will appear:

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

When a PONG message is received, the following prompt message will appear:

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

When a data packet is received, the following prompt message will appear:

[$][WS][DATA][<link_id>][<data packet length>]:<data>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

  • <host>: Target host, without ws:// or wss:// prefix

    • Supports domain name or IPv4 address

    • Maximum length: 128 characters

  • <path>: Resource path

    • Default value: “/”

    • Maximum length: 256 characters

  • <port>: Port

    • Range: [0,65535] (Default value 0)

    • 0: WS uses port 80, WSS uses port 443

  • <conn_type>: Connection type

    • 1: WebSocket over TCP

    • 2: WebSocket over TLS (no certificate verification)

    • 3: WebSocket over TLS (verify server certificate with CA certificate)

    • 4: WebSocket over TLS (provide client certificate to server for verification)

    • 5: WebSocket over TLS (mutual authentication, both 3 and 4)

  • <cert_index>: Security Certificate Suite index, refer to AT Security Certificates

    • [1-10]

    • Required only when <conn_type> is 3-5

Error Codes

  • 1: Parameter range error

  • 2: Memory allocation failed

  • 3: Socket creation failed

  • 4: Certificate loading failed

  • 5: Connection to server failed

  • 6: Connection task creation failed

Example

Establish a wss connection using port 8433 and verify the server with CA certificate from certificate suite 1:

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

OK

AT+WSSEND

Function Description

Send WebSocket data

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

  • <length>: Data length

    • Maximum value: size defined by <buffer_size> parameter in AT+WSCFG

  • <use_mask>: Data masking

    • 0: Disabled

    • 1: Enabled (default)

  • <opcode>: Frame type

    • 0: CONTINUATION frame

    • 1: Text frame (default)

    • 2: Binary frame

    • 8: Close frame

    • 9: PING frame

    • 10: PONG frame

  • <data>: Data to be sent

Error Codes

  • 1: Parameter range error

  • 2: Connection unavailable

Example

Send text message:

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

OK

AT+WSSENDRAW

Function Description

Send WebSocket data using Transparent Transmission (TT) Mode.

Note

This command is only supported in Master Control Mode.

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

  • <length>: Data length

    • No length limit

  • <use_mask>: Data masking

    • 0: Disabled

    • 1: Enabled (default)

  • <opcode>: Frame type

    • 0: CONTINUATION frame

    • 1: Text frame (default)

    • 2: Binary frame

    • 8: Close frame

    • 9: PING frame

    • 10: PONG frame

Error Codes

  • 1: Parameter range error

  • 2: Connection unavailable

  • 3: Memory allocation failed

  • 4: Failed to enter TT mode

Example

Send 10 bytes of text message:

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

OK

AT+WSDISCONN

Function Description

Actively close the WebSocket client connection for the specified link ID

Command Format

AT+WSDISCONN=<link_id>

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

Error Codes

  • 1: Parameter range error

  • 2: Connection unavailable

Example

Close connection with link id 0:

AT+WSDISCONN=0

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

AT+WSQUERY

Function Description

Query WebSocket client-related information, including global configuration information or information for a specified link ID

Command Format

AT+WSQUERY=[<link_id>]

Response Format

Successful Response:

Global config:
connect_timeout: <Connection timeout (seconds)>
recv_timeout: <Receive timeout (milliseconds)>
send_timeout: <Send timeout (milliseconds)>
send_blocktime: <Send block time (milliseconds)>
keepalive_idle: <TCP keepalive probe start time (seconds)>
keepalive_interval: <Keepalive probe interval (seconds)>
keepalive_count: <Number of keepalive probes>
link_id: <link ID>
status: <Connection status, 0: Closing, 1: Closed, 2: Connecting, 3: Connected>
ping_interval: <Ping heartbeat interval (seconds)>
ping_timeout: <Ping timeout (seconds)>
buffer_size: <Data buffer size (bytes)>
max_queue_size: <Maximum queue depth>
protocol: <Sub-protocol type>
version: <Protocol version>
stable_buf_num: <Number of stable buffers>
header:
<Request header info 1>
<Request header info 2>
...

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

    • If omitted, information for all link IDs will be output

Error Codes

  • 1: Parameter range error

Example

Query information for link 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

Function Description

Check if the tx queue is full for the specified link ID

Command Format

AT+WSTXQUEUECHECK=<link_id>

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

Error Codes

  • 1: Parameter range error

  • 2: Connection unavailable

Example

Check tx queue with link id 0:

AT+WSTXQUEUECHECK=0

OK
Tx queue is not full

AT+WSSRVCFG

Description

Configure WebSocket server parameters

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <max_conn>: Maximum number of connections

    • Range [1,3]

    • Default value: 3

  • <ping_interval>: Ping packet interval (seconds)

    • Range [1,7200]

    • Default value: 30

  • <idle_timeout>: Idle timeout (seconds)

    • Connection will be actively closed if no packet communication exceeds the idle timeout

    • Range [0,7200]

    • Default value: 0 (no timeout)

  • <tx_size>: Transmit buffer (bytes)

    • Range [1,16384]

    • Default value: 4096

  • <rx_size>: Receive buffer (bytes)

    • Range [1,16384]

    • Default value: 4096

Error Codes

  • 1: Parameter range error

Example

Configure WebSocket server parameters:

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

OK

AT+WSSRVSTART

Description

Start WebSocket server

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

AT Messages

When a client successfully connects, the following prompt message will appear:

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

When the connection is disconnected, the following prompt message will appear:

[$][WSSRV][EVENT]:linkid:<link_id>, disconnected, reason:<disconnect reason>

When data is received, the following prompt message will appear:

[$][WSSRV][DATA][<link_id>][<opcode>][<data_length>]:<data>

Note

List of disconnect reasons:

  • 1: Failed to create connection

  • 2: Connection initialization failed

  • 3: Client actively disconnected

  • 4: Server actively disconnected

  • 5: TLS handshake failed

  • 6: TLS handshake timeout

  • 7: Select listening failed

  • 9: Socket setup failed

  • 10: Read failed

  • 11: Send failed

  • 13: PING response timeout

  • 14: Idle timeout

Parameters

  • <port>: Port

    • Range: [0,65535] (Default value 0)

    • 0: WS uses port 80, WSS uses port 443

  • <conn_type>: Connection type

    • 1: WebSocket Server over TCP

    • 2: WebSocket Server over TLS (provides server certificate for client verification)

    • 3: WebSocket Server over TLS (provides server certificate for client verification and uses CA certificate to verify client certificate)

  • <cert_index>: Security certificate suite index, refer to AT Security Certificates

    • [1-10]

    • Only required when <conn_type> is 2 or 3

Error Codes

  • 1: Parameter range error

  • 2: Server already running

  • 3: Failed to get certificate suite

  • 4: Memory allocation failed

  • 5: Failed to set certificate

  • 6: Failed to start server

Example

Start WebSocket server on port 80:

AT+WSSRVSTART=0,1

OK

Start TLS WebSocket server on port 8433 using server certificate suite 2:

AT+WSSRVSTART=8433,2,2

OK

AT+WSSRVDISCONN

Description

Disconnect WebSocket client connection with specified link ID

Command Format

AT+WSSRVDISCONN=<link_id>

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Range: [0,2]

Error Codes

  • 1: Parameter range error

  • 2: Connection unavailable

Example

Disconnect client connection with link ID 2:

AT+WSSRVDISCONN=2

OK

AT+WSSRVSTOP

Description

Close WebSocket server

Command Format

AT+WSSRVSTOP

Response Format

Successful Response:

OK

Parameters

None

Error Codes

None

AT+WSSRVSEND

Description

Send WebSocket data to specified link ID

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

  • <length>: Data length

    • Maximum value: Size defined by <tx_buff> parameter in AT+WSSRVCFG

  • <opcode>: Frame type

    • 0: CONTINUATION frame

    • 1: Text frame (default)

    • 2: Binary frame

    • 8: Close frame

    • 9: PING frame

    • 10: PONG frame

  • <data>: Data to be sent

Error Codes

  • 1: Parameter range error

  • 2: Memory allocation failed

Example

Send text message to link ID 1:

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

OK

AT+WSSRVSENDRAW

Description

Send WebSocket data to specified link ID using Transparent Transmission (TT) Mode.

Note

This command is only supported in Host Control Mode.

Command Format

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

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

  • <link_id>: link ID

    • Valid range: 0-2

  • <length>: Data length

    • No length limit

  • <opcode>: Frame type

    • 0: CONTINUATION frame

    • 1: Text frame (default)

    • 2: Binary frame

    • 8: Close frame

    • 9: PING frame

    • 10: PONG frame

Error Codes

  • 1: Parameter range error

  • 2: Memory allocation failed

  • 3: Failed to enter TT mode

Example

Send 10 bytes of text message to link ID 0:

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

OK

AT+WSSRVQUERY

Description

Query WebSocket server related information, including global configuration information and information for all link IDs

Command Format

AT+WSSRVQUERY

Response Format

Successful Response:

port: <port>
max_conn: <maximum connections>
ping_interval: <ping interval (seconds)>
idle_timeout: <idle timeout (seconds)>
tx_size: <transmit buffer size (bytes)>
rx_size: <receive buffer size (bytes)>
link_id: <link ID>
status: <connection status, 0: closed, 1: connecting, 2: connected, 3: connected and sent ping packet, awaiting pong packet, 4: closing>
ip: <client IPv4 address>
link_id: <link ID>
status: <connection status, 0: closed, 1: connecting, 2: connected, 3: connected and sent ping packet, awaiting pong packet, 4: closing>
ip: <client IPv4 address>
...

OK

Parameters

None

Error Codes

None

Example

Query WebSocket server related information:

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