WebSocket AT Commands

[中文]

Introduction

Important

The default AT firmware does not support the AT commands listed on this page. If you need ESP32-C5 to support WebSocket commands, you can compile the ESP-AT project by following the steps in Compile ESP-AT Project Locally documentation. In the project configuration during the fifth step, make the following selections:

  • Enable Component config > AT > AT WebSocket command support

AT+WSCFG: Set the WebSocket Configuration

Set Command

Command:

AT+WSCFG=<link_id>,<ping_intv_sec>,<ping_timeout_sec>[,<buffer_size>][,<auth_mode>,<pki_number>,<ca_number>]

Response:

OK

or

ERROR

Parameters

  • <link_id>: ID of the WebSocket connection. Range: [0,2], which means that AT can support up to three WebSocket connections.

  • <ping_intv_sec>: WebSocket Ping interval. Unit: second. Range: [1,7200]. Default: 10, which means that WebSocket Ping packets are sent every 10 seconds by default.

  • <ping_timeout_sec>: WebSocket Ping timeout. Unit: second. Range: [1,7200]. Default: 120, which means that by default, if the WebSocket Pong packet is not received within 120 seconds, the connection will be closed.

  • <buffer_size>: WebSocket buffer size. Unit: byte. Range: [1,16384]. Default: 1024.

  • <auth_mode>:

    • 0: no authentication. In this case <pki_number> and <ca_number> are not required.

    • 1: the client provides the client certificate for the server to verify.

    • 2: the client loads CA certificate to verify the server’s certificate.

    • 3: mutual authentication.

  • <pki_number>: the index of certificate and private key. If there is only one certificate and private key, the value should be 0.

  • <ca_number>: the index of CA. If there is only one CA, the value should be 0.

Notes

  • This command should be configured before AT+WSOPEN command. Otherwise, it will not take effect.

  • If you want to use your own certificate at runtime, use the AT+SYSMFG command to update the WebSocket certificate. If you want to pre-burn your own certificate, please refer to How to Update PKI Configuration.

  • If <auth_mode> is configured to 2 or 3, in order to check the server certificate validity period, please make sure ESP32-C5 has obtained the current time before sending the AT+WSOPEN command. (You can send AT+CIPSNTPCFG command to configure SNTP and obtain the current time, and send AT+CIPSNPTIME? command to query the current time.)

  • Mutual authentication example: WebSocket Connection over TLS (Mutual Authentication).

Example

// Set the ping interval to 30 seconds, ping timeout to 60 seconds, and buffer size to 4096 bytes for link_id: 0.
AT+WSCFG=0,30,60,4096

AT+WSHEAD: Set/Query WebSocket Request Headers

Query Command

Command:

AT+WSHEAD?

Response:

+WSHEAD:<index>,<"req_header">

OK

Set Command

Command:

AT+WSHEAD=<req_header_len>

Response:

OK

>

The > symbol indicates that AT is ready to receive AT command data. At this point, you can enter the WebSocket request header (in the format of key: value, no need to end with \r\n). When the data length reaches the value of parameter <req_header_len>, AT returns:

OK

Parameters

  • <index>: Index value of WebSocket request header.

  • <”req_header”>: WebSocket request header.

  • <req_header_len>: WebSocket request header length. Unit: byte.

    • 0: Clear all set WebSocket request headers.

    • Other values: Set a new WebSocket request header.

Notes

  • This command can only set one WebSocket request header at a time, but it can be set multiple times to support multiple different WebSocket request headers.

  • The WebSocket request headers configured by this command are global. Once set, all WebSocket commands will carry these request headers.

Example

// Set the request header
AT+WSHEAD=49

// After receiving the ">" symbol, enter the authorization request header below.
AUTHORIZATION: Basic QTIzMzIyMDE5OTk6MTIzNDU2Nzg=

// Open a WebSocket connection
AT+WSOPEN=0,"wss://demo.piesocket.com/v3/channel_123?api_key=VCXCEuvhGcBDP7XhiJJUDvR1e1D3eiVjgZ9VRiaV&notify_self"

AT+WSOPEN: Query/Open a WebSocket Connection

Query Command

Command:

AT+WSOPEN?

Response:

When there is a connection, AT returns:

+WSOPEN:<link_id>,<state>,<"uri">

OK

When there is no connection, AT returns:

OK

Set Command

Command:

AT+WSOPEN=<link_id>,<"uri">[,<"subprotocol">][,<timeout_ms>][,<"auth">]

Response:

+WS_CONNECTED:<link_id>

OK

or

ERROR

Parameters

  • <link_id>: ID of the WebSocket connection. Range: [0,2], which means that AT can support up to three WebSocket connections.

  • <state>: The state of WebSocket connections.

    • 0: The WebSocket connection is closed.

    • 1: The WebSocket connection is reconnecting.

    • 2: The WebSocket connection is established.

    • 3: Receiving WebSocket Pong timeout or reading connection data error, waiting for reconnection.

    • 4: The WebSocket connection Received close frame from the server side and is sending close frame to the server.

  • <”uri”>: Uniform resource identifier of WebSocket server.

  • <”subprotocol”>: The subprotocol of WebSocket (refer to Section: RFC6455 1.9 for more details).

  • <timeout_ms>: Timeout for establishing a WebSocket connection. Unit: millisecond. Range: [0,180000]. Default: 15000.

  • <”auth”>: The authorization of WebSocket (refer to Section: RFC6455 4.1.12 for more details).

Example

// uri parameter comes from https://www.piesocket.com/websocket-tester
AT+WSOPEN=0,"wss://demo.piesocket.com/v3/channel_123?api_key=VCXCEuvhGcBDP7XhiJJUDvR1e1D3eiVjgZ9VRiaV&notify_self"

Detailed examples refer to: WebSocket Example.

AT+WSSEND: Send Data to a WebSocket Connection

Set Command

Command:

AT+WSSEND=<link_id>,<length>[,<opcode>][,<timeout_ms>][,<fin>]

Response:

OK

>

This response indicates that AT is ready for receiving data from AT port. You should enter the data, and when the data length reaches the <length> value, the transmission of data starts.

If the connection cannot be established or is disrupted during data transmission, the system returns:

ERROR

If data is transmitted successfully, the system returns:

SEND OK

Parameters

  • <link_id>: ID of the WebSocket connection. Range: [0,2].

  • <length>: Length of the data to be sent. Unit: byte. The maximum allowable length is the smaller of 16 KiB and the amount of heap memory currently available for allocation.

  • <opcode>: The opcode in the WebSocket frame sent. Range: [0,0xF]. Default: 1, which means text frame. For details about opcode, please refer to Section: RFC6455 5.2.

    • 0x0: continuation frame

    • 0x1: text frame

    • 0x2: binary frame

    • 0x3 - 0x7: reserved for further non-control frames

    • 0x8: connection close frame

    • 0x9: ping frame

    • 0xA: pong frame

    • 0xB - 0xF: reserved for further control frames

  • <timeout_ms>: Send timeout. Unit: millisecond. Range: [0,60000]. Default: 10000.

  • <fin>: Indicates whether the data frame is the last fragment. Default: 1.

    • 0: Indicates the data frame has subsequent fragments.

    • 1: Indicates the data frame is the last fragment.

AT+WSDATAFMT: Set WebSocket Received Data Format

Set Command

Function:

By default, when the ESP32-C5 receives WebSocket data, it will output the data in the format +WS_DATA:<link_id>,<data_len>,<data>\r\n. This command allows you to configure the metadata output format when receiving data to meet different application requirements. The complete output format is as follows:

+WS_DATA:<link_id>[,<opcode>][,<fin>][,<payload_len>][,<payload_offset>][,<data_len>],<data>[<\r\n>]

Command:

AT+WSDATAFMT=<link_id>[,<meta_data_level>][,<meta_data_mask>]

Response:

OK

or

ERROR

Parameters

  • <link_id>: ID of the WebSocket connection. Range: [0,2].

  • <meta_data_level>: Metadata output level. Default: 0. The meanings of each level are as follows:

    • 0: chunked level. Each time data is received from the transport layer, metadata prefixed with +WS_DATA is added.

    • 1: frame level. Metadata prefixed with +WS_DATA is only added before and after a complete WebSocket frame.

    • 2: message level. Metadata prefixed with +WS_DATA is only added before and after a complete WebSocket message.

  • <meta_data_mask>: A bitmask used to control the +WS_DATA output format. Setting a corresponding bit to 1 will include the field associated with that bit in the output. Default: 48 (in this case, only <data_len> and <\r\n> are output).

    • bit 0: <opcode>, WebSocket frame type

    • bit 1: <fin>, whether it is the last frame of the message

    • bit 2: <payload_len>, complete payload length

    • bit 3: <payload_offset>, offset of current data in the payload

    • bit 4: <data_len>, length of the current output data

    • bit 5: <\r\n>, newline at the end of data

Example

// Set the WebSocket connection with link_id 0 to use message level, only output payload_len.
AT+WSDATAFMT=0,2,4

AT+WSCLOSE: Close a WebSocket Connection

Set Command

Command:

AT+WSCLOSE=<link_id>

Response:

OK

Parameters

  • <link_id>: ID of the WebSocket connection. Range: [0,2].

Notes

  • This command triggers the TCP layer close process. Returning OK only indicates that the close instruction has been issued and does not guarantee that the peer has completely disconnected. To ensure the connection is fully closed, it is recommended to first send a WebSocket control frame with opcode 8 (Close Frame) using the AT+WSSEND command before executing this command, and wait for the server to respond before closing.

Example

// Close the WebSocket connection whose link_id is 0
AT+WSCLOSE=0

Provide feedback about this document