WebSocket AT Examples

This document shows how to use WebSocket AT Commands on ESP32 with detailed examples.

WebSocket Connection over TCP
WebSocket Connection over TLS (Mutual Authentication)

Important

The default AT firmware does not support the WebSocket functionality. If you need ESP32 to support WebSocket functionality, please refer to introduction.

WebSocket Connection over TCP 

Set the Wi-Fi mode to station.

Command:
```
AT+CWMODE=1
```
Response:
```
OK
```
Connect to the router.

Command:
```
AT+CWJAP="espressif","1234567890"
```
Response:
```
WIFI CONNECTED
WIFI GOT IP

OK
```
Note:
- The SSID and password you entered may be different from those in the above command. Please replace the SSID and password with those of your router settings.
Connect the PC to the same router which ESP32 is connected to.

Create a WebSocket server over TCP on PC using python. The example code is as follows:

#!/usr/bin/env python

import asyncio
from websockets.server import serve

host = "192.168.200.249"
port = 8765

async def echo(websocket):
    async for message in websocket:
        await websocket.send(message)

async def main():
    async with serve(echo, host, port):
        print(f"Server started at ws://{host}:{port}")
        await asyncio.get_running_loop().create_future()  # run forever

asyncio.run(main())

Please modify the code above by replacing the host with the IP address of your PC, and save it as ws-server.py file. Then run the program.

python ws-server.py

Note:

If you do not have the websockets library installed on your PC, please install it using pip install websockets.
The WebSocket server port is set to 8765 by default, but you can also set it to a different port.

Connect ESP32 device as a client to the WebSocket server.

Command:
```
AT+WSOPEN=0,"ws://192.168.200.249:8765"
```
Response:
```
+WS_CONNECTED:0

OK
```
Send 4 bytes of data.

Command:
```
AT+WSSEND=0,4
```
Response:
```
OK

>
```
Input 4 bytes (e.g., test), and then AT will respond with the following message.
```
SEND OK
```
Note:
- If the input exceeds the length (n) specified by AT+CIPSEND, the system will respond with busy p..., and send the first n bytes. Once those bytes are sent, the system will respond with SEND OK.
Receive 4 bytes of data.

Since the above WebSocket server is an echo server, after the data is sent, the server will also return the data as it is, so AT will output:
```
+WS_DATA:0,4,test
```

WebSocket Connection over TLS (Mutual Authentication)

Set the Wi-Fi mode to station.

Command:
```
AT+CWMODE=1
```
Response:
```
OK
```
Connect to the router.

Command:
```
AT+CWJAP="espressif","1234567890"
```
Response:
```
WIFI CONNECTED
WIFI GOT IP

OK
```
Note:
- The SSID and password you entered may be different from those in the above command. Please replace the SSID and password with those of your router settings.
Set the SNTP server.

Command:
```
AT+CIPSNTPCFG=1,8,"cn.ntp.org.cn","ntp.sjtu.edu.cn"
```
Response:
```
OK
```
Note:
- You can set the SNTP server according to your country’s time zone.
Query the SNTP time.

Command:
```
AT+CIPSNTPTIME?
```
Response:
```
+CIPSNTPTIME:Mon Oct 18 20:12:27 2021
OK
```
Note:
- You can verify if the SNTP server is functioning correctly by checking whether the SNTP-synchronized time matches the actual current time.
Connect the PC to the same router which ESP32 is connected to.

Get the CA, certificate, and private key of the WebSocket server.

You can use the openssl tool to generate the CA, certificate, and private key. If you encounter any difficulties, consider using the following configuration for testing:

server_ca.crt

server.crt

server.key

Create a WebSocket server over TLS on PC using python. The example code is as follows:

#!/usr/bin/env python

import asyncio
import ssl
import websockets

host = '192.168.200.249'
port = 8766
server_ca = '/your_path/server_ca.crt'
server_cert = '/your_path/server.crt'
server_key = '/your_path/server.key'

async def echo(websocket, path):
    async for message in websocket:
        await websocket.send(message)

ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ssl_context.load_cert_chain(certfile=server_cert, keyfile=server_key)
ssl_context.verify_mode = ssl.CERT_REQUIRED
ssl_context.load_verify_locations(server_ca)

start_server = websockets.serve(echo, host, port, ssl=ssl_context)

asyncio.get_event_loop().run_until_complete(start_server)
print(f"Server started at wss://{host}:{port}")

asyncio.get_event_loop().run_forever()

Please modify the code above by replacing the host with the IP address of your PC, and the server_ca, server_cert, and server_key with the paths to the CA, certificate, and private key of the server. Save the modified code as wss-server.py and run the program.

python wss-server.py

Note:

If you do not have the websockets library installed on your PC, please install it using pip install websockets.
The WebSocket server port is set to 8766, but you can also set it to a different port.

Configure the WebSocket connection for mutual authentication.

Command:
```
AT+WSCFG=0,30,60,4096,3,0,0
```
Response:
```
OK
```
Note:
- If you want to use your own certificate or use multiple sets of certificates, please refer to How to Update PKI Configuration.
Connect ESP32 device as a client to the WebSocket server.

Command:
```
AT+WSOPEN=0,"wss://192.168.200.249:8766"
```
Response:
```
+WS_CONNECTED:0

OK
```
Send 4 bytes of data.

Command:
```
AT+WSSEND=0,4
```
Response:
```
OK

>
```
Input 4 bytes, for example, test, then AT will respond the following message.
```
SEND OK
```
Note:
- If the number of bytes inputted are more than the length (n) set by AT+CIPSEND, the system will reply busy p..., and send the first n bytes. And after sending the first n bytes, the system will reply SEND OK.
Receive 4 bytes of data.

Since the above WebSocket server is an echo server, after the data is sent, the server will also return the data as it is, so AT will output:
```
+WS_DATA:0,4,test
```

Provide feedback about this document

WebSocket AT Examples

WebSocket Connection over TCP

WebSocket Connection over TLS (Mutual Authentication)

WebSocket Connection over TCP 