Skip to content

Commit f5e62e8

Browse files
gabsurengabsuren
authored
Merge pull request espressif#902 from gabsuren/docs/readme_update
[examples]: enhance example with docs, pytest setup, and standalone test server(IDFGH-16585)
2 parents 16cc2dc + cad527d commit f5e62e8

File tree

5 files changed

+492
-83
lines changed

5 files changed

+492
-83
lines changed

‎components/esp_websocket_client/examples/target/README.md‎

Lines changed: 249 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,42 @@
11
# Websocket Sample application
22

3-
This example will shows how to set up and communicate over a websocket.
3+
This example shows how to set up and communicate over a websocket.
4+
5+
## Table of Contents
6+
7+
- [Hardware Required](#hardware-required)
8+
- [Configure the project](#configure-the-project)
9+
- [Pre-configured SDK Configurations](#pre-configured-sdk-configurations)
10+
- [Server Certificate Verification](#server-certificate-verification)
11+
- [Generating Self-signed Certificates](#generating-a-self-signed-certificates-with-openssl)
12+
- [Build and Flash](#build-and-flash)
13+
- [Testing with pytest](#testing-with-pytest)
14+
- [Example Output](#example-output)
15+
- [WebSocket Test Server](#websocket-test-server)
16+
- [Python Flask Echo Server](#alternative-python-flask-echo-server)
17+
18+
## Quick Start
19+
20+
1. **Install dependencies:**
21+
```bash
22+
pip install -r esp-protocols/ci/requirements.txt
23+
```
24+
25+
2. **Configure and build:**
26+
```bash
27+
idf.py menuconfig # Configure WiFi/Ethernet and WebSocket URI
28+
idf.py build
29+
```
30+
31+
3. **Flash and monitor:**
32+
```bash
33+
idf.py -p PORT flash monitor
34+
```
35+
36+
4. **Run tests:**
37+
```bash
38+
pytest .
39+
```
440

541
## How to Use Example
642

@@ -15,6 +51,20 @@ This example can be executed on any ESP32 board, the only required interface is
1551
* Configure the websocket endpoint URI under "Example Configuration", if "WEBSOCKET_URI_FROM_STDIN" is selected then the example application will connect to the URI it reads from stdin (used for testing)
1652
* To test a WebSocket client example over TLS, please enable one of the following configurations: `CONFIG_WS_OVER_TLS_MUTUAL_AUTH` or `CONFIG_WS_OVER_TLS_SERVER_AUTH`. See the sections below for more details.
1753

54+
### Pre-configured SDK Configurations
55+
56+
This example includes several pre-configured `sdkconfig.ci.*` files for different testing scenarios:
57+
58+
* **sdkconfig.ci** - Default configuration with WebSocket over Ethernet (IP101 PHY, ESP32, IPv6) and hardcoded URI.
59+
* **sdkconfig.ci.plain_tcp** - WebSocket over plain TCP (no TLS, URI from stdin) using Ethernet (IP101 PHY, ESP32, IPv6).
60+
* **sdkconfig.ci.mutual_auth** - WebSocket with mutual TLS authentication (client/server certificate verification, skips CN check) and URI from stdin.
61+
* **sdkconfig.ci.dynamic_buffer** - WebSocket with dynamic buffer allocation, Ethernet (IP101 PHY, ESP32, IPv6), and hardcoded URI.
62+
63+
Example:
64+
```
65+
idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.ci.plain_tcp" build
66+
```
67+
1868
### Server Certificate Verification
1969

2070
* Mutual Authentication: When `CONFIG_WS_OVER_TLS_MUTUAL_AUTH=y` is enabled, it's essential to provide valid certificates for both the server and client.
@@ -26,7 +76,7 @@ This example can be executed on any ESP32 board, the only required interface is
2676
Please note: This example represents an extremely simplified approach to generating self-signed certificates/keys with a single common CA, devoid of CN checks, lacking password protection, and featuring hardcoded key sizes and types. It is intended solely for testing purposes.
2777
In the outlined steps, we are omitting the configuration of the CN (Common Name) field due to the context of a testing environment. However, it's important to recognize that the CN field is a critical element of SSL/TLS certificates, significantly influencing the security and efficacy of HTTPS communications. This field facilitates the verification of a website's identity, enhancing trust and security in web interactions. In practical deployments beyond testing scenarios, ensuring the CN field is accurately set is paramount for maintaining the integrity and reliability of secure communications
2878

29-
### Generating a self signed Certificates with OpenSSL
79+
### Generating a self signed Certificates with OpenSSL manually
3080
* The example below outlines the process for creating new certificates for both the server and client using OpenSSL, a widely-used command line tool for implementing TLS protocol:
3181

3282
```
@@ -63,6 +113,46 @@ Please see the openssl man pages (man openssl) for more details.
63113
It is **strongly recommended** to not reuse the example certificate in your application;
64114
it is included only for demonstration.
65115

116+
### Certificate Generation Options
117+
118+
#### Option 1: Manual OpenSSL Commands
119+
Follow the step-by-step process in the section above to understand certificate generation.
120+
121+
#### Option 2: Automated Script
122+
**Note:** Test certificates are already available in the example. If you want to regenerate them or create new ones, use the provided `generate_certs.sh` script:
123+
124+
```bash
125+
# Auto-detect local IP address (recommended for network testing)
126+
./generate_certs.sh
127+
128+
# Specify custom hostname or IP address
129+
./generate_certs.sh 192.168.1.100
130+
131+
# Use localhost (for local-only testing)
132+
./generate_certs.sh localhost
133+
```
134+
135+
This script automatically generates all required certificates in the correct directories and cleans up temporary files.
136+
137+
**Important:** The server certificate's Common Name (CN) must match the hostname or IP address that ESP32 clients use to connect. If not specified, the script attempts to auto-detect your local IP address. Certificate verification will fail if there's a mismatch between the CN and the actual connection address.
138+
139+
**CN Mismatch Handling:**
140+
If you encounter certificate verification failures due to CN mismatch, you have two options:
141+
142+
1. **Recommended (Secure):** Regenerate certificates with the correct CN:
143+
```bash
144+
./generate_certs.sh <actual_hostname_or_ip>
145+
```
146+
147+
2. **Testing Only (Less Secure):** Skip CN verification by enabling `CONFIG_WS_OVER_TLS_SKIP_COMMON_NAME_CHECK=y` in `idf.py menuconfig`.
148+
149+
⚠️ **WARNING:** This option disables an important security check and should **NEVER** be used in production environments. It makes your application vulnerable to man-in-the-middle attacks.
150+
151+
#### Option 3: Online Certificate Generators
152+
- **mkcert**: `install mkcert` then `mkcert -install` and `mkcert localhost`
153+
- **Let's Encrypt**: For production certificates (free, automated renewal)
154+
- **Online generators**: Search for "self-signed certificate generator" online
155+
66156
### Build and Flash
67157

68158
Build the project and flash it to the board, then run monitor tool to view serial output:
@@ -73,7 +163,36 @@ idf.py -p PORT flash monitor
73163

74164
(To exit the serial monitor, type ``Ctrl-]``.)
75165

76-
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
166+
See the [ESP-IDF Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
167+
168+
## Testing with pytest
169+
170+
### Install Dependencies
171+
172+
Before running the pytest tests, you need to install the required Python packages:
173+
174+
```
175+
pip install -r esp-protocols/ci/requirements.txt
176+
```
177+
178+
### Run pytest
179+
180+
After installing the dependencies, you can run the pytest tests:
181+
182+
Run all tests in current directory:
183+
```
184+
pytest .
185+
```
186+
187+
Run specific test file:
188+
```
189+
pytest pytest_websocket.py
190+
```
191+
192+
To specify the target device or serial port, use:
193+
```
194+
pytest --target esp32 --port /dev/ttyUSB0
195+
```
77196

78197
## Example Output
79198

@@ -105,9 +224,101 @@ W (9162) WEBSOCKET: Received=hello 0003
105224
```
106225

107226

108-
## Python Flask echo server
227+
## WebSocket Test Server
228+
229+
### Standalone Test Server
230+
231+
This example includes a standalone WebSocket test server (`websocket_server.py`) that can be used for testing your ESP32 WebSocket client:
232+
233+
#### Quick Start
234+
235+
**Plain WebSocket (No TLS):**
236+
```bash
237+
# Plain WebSocket server (no encryption)
238+
python websocket_server.py
239+
240+
# Custom port
241+
python websocket_server.py --port 9000
242+
```
243+
244+
**Server-Only Authentication:**
245+
```bash
246+
# TLS WebSocket server (ESP32 verifies server)
247+
python websocket_server.py --tls
248+
249+
# Custom port with TLS
250+
python websocket_server.py --port 9000 --tls
251+
```
252+
253+
**Mutual Authentication:**
254+
```bash
255+
# TLS with client certificate verification (both verify each other)
256+
python websocket_server.py --tls --client-verify
257+
258+
# Custom port with mutual authentication
259+
python websocket_server.py --port 9000 --tls --client-verify
260+
```
261+
262+
#### Server Features
263+
- **Echo functionality** - Automatically echoes back received messages
264+
- **TLS support** - Secure WebSocket (WSS) connections
265+
- **Client certificate verification** - Mutual authentication support
266+
- **Binary and text messages** - Handles both data types
267+
- **Auto IP detection** - Shows connection URL with your local IP
268+
269+
#### Verification Modes
270+
271+
**Plain WebSocket (No TLS):**
272+
- No certificate verification on either side
273+
- Use for local testing or trusted networks
274+
- Configuration: `CONFIG_WS_OVER_TLS_MUTUAL_AUTH=n` and `CONFIG_WS_OVER_TLS_SERVER_AUTH=n`
275+
276+
**Server-Only Authentication (`--tls` without `--client-verify`):**
277+
- ESP32 verifies the server's certificate
278+
- Server does NOT verify the ESP32's certificate
279+
- Use when you trust the client but want to verify the server
280+
- Configuration: `CONFIG_WS_OVER_TLS_SERVER_AUTH=y`
281+
282+
**Mutual Authentication (`--tls --client-verify`):**
283+
- ESP32 verifies the server's certificate
284+
- Server verifies the ESP32's certificate
285+
- Use when both parties need to authenticate each other
286+
- Configuration: `CONFIG_WS_OVER_TLS_MUTUAL_AUTH=y`
287+
288+
#### Usage Examples
289+
290+
**Plain WebSocket (No TLS or Client Verification):**
291+
```bash
292+
# Basic server (port 8080)
293+
python websocket_server.py
294+
295+
# Custom port
296+
python websocket_server.py --port 9000
297+
```
109298

110-
By default, the `wss://echo.websocket.org` endpoint is used. You can setup a Python websocket echo server locally and try the `ws://<your-ip>:5000` endpoint. To do this, install Flask-sock Python package
299+
**Server-Only Authentication (ESP32 verifies server, server doesn't verify ESP32):**
300+
```bash
301+
# TLS server without client verification
302+
python websocket_server.py --tls
303+
304+
# Custom port with TLS
305+
python websocket_server.py --port 9000 --tls
306+
```
307+
308+
**Mutual Authentication (Both ESP32 and server verify each other's certificates):**
309+
```bash
310+
# TLS server with client certificate verification
311+
python websocket_server.py --tls --client-verify
312+
313+
# Custom port with mutual authentication
314+
python websocket_server.py --port 9000 --tls --client-verify
315+
```
316+
317+
The server will display the connection URL (e.g., `wss://192.168.1.100:8080`) that you can use in your ESP32 configuration.
318+
319+
### Alternative: Python Flask Echo Server
320+
321+
By default, the `wss://echo.websocket.org` endpoint is used. You can also setup a Python Flask websocket echo server locally and try the `ws://<your-ip>:5000` endpoint. To do this, install Flask-sock Python package
111322

112323
```
113324
pip install flask-sock
@@ -135,3 +346,36 @@ if __name__ == '__main__':
135346
# gunicorn -b 0.0.0.0:5000 --workers 4 --threads 100 module:app
136347
app.run(host="0.0.0.0", debug=True)
137348
```
349+
350+
## Troubleshooting
351+
352+
### Common Issues
353+
354+
**Connection failed:**
355+
- Verify WiFi/Ethernet configuration in `idf.py menuconfig`
356+
- Check if the WebSocket server is running and accessible
357+
- Ensure the URI is correct (use `wss://` for TLS, `ws://` for plain TCP)
358+
359+
**TLS certificate errors:**
360+
- **Certificate verification failed:** The most common cause is CN mismatch. Ensure the server certificate's Common Name matches the hostname/IP you're connecting to:
361+
- Check your connection URI (e.g., if connecting to `wss://192.168.1.100:8080`, the certificate CN must be `192.168.1.100`)
362+
- Regenerate certificates with the correct CN: `./generate_certs.sh <your_hostname_or_ip>`
363+
- For testing only, you can bypass CN check with `CONFIG_WS_OVER_TLS_SKIP_COMMON_NAME_CHECK=y` (NOT recommended for production)
364+
- Verify certificate files are properly formatted and accessible
365+
- Ensure the CA certificate used to sign the server certificate is loaded on the ESP32
366+
367+
**Build errors:**
368+
- Clean build: `idf.py fullclean`
369+
- Check ESP-IDF version compatibility
370+
- Verify all dependencies are installed
371+
372+
**Test failures:**
373+
- Ensure the device is connected and accessible via the specified port
374+
- Check that the target device matches the configuration (`--target esp32`)
375+
- Verify pytest dependencies are installed correctly
376+
377+
### Getting Help
378+
379+
- Check the [ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/)
380+
- Review the [WebSocket client component documentation](../../README.md)
381+
- Report issues on the [ESP Protocols repository](https://github.com/espressif/esp-protocols)

‎components/esp_websocket_client/examples/target/generate_certs.sh‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
#!/bin/bash
2+
# Generate CA, Server, and Client certificates automatically
3+
#
4+
# Usage: ./generate_certs.sh [SERVER_CN]
5+
# SERVER_CN: The Common Name (hostname or IP) for the server certificate.
6+
# This should match the hostname/IP that ESP32 clients will use to connect.
7+
# If not provided, the script will attempt to auto-detect the local IP address.
8+
# Falls back to "localhost" if auto-detection fails.
9+
#
10+
# IMPORTANT: The server certificate's Common Name (CN) must match the hostname or IP address
11+
# that ESP32 clients use to connect. If there's a mismatch, certificate verification will fail
12+
# during the TLS handshake. For production use, always specify the correct hostname/IP.
13+
14+
# Get server hostname/IP from command line argument or auto-detect
15+
if [ -n "$1" ]; then
16+
SERVER_CN="$1"
17+
echo "Using provided SERVER_CN: $SERVER_CN"
18+
else
19+
# Attempt to auto-detect local IP address
20+
# Try multiple methods for better compatibility across different systems
21+
if command -v hostname >/dev/null 2>&1; then
22+
# Try to get IP from hostname command (works on most Unix systems)
23+
SERVER_CN=$(hostname -I 2>/dev/null | awk '{print $1}')
24+
fi
25+
26+
# If the above failed, try ifconfig (macOS and some Linux systems)
27+
if [ -z "$SERVER_CN" ] && command -v ifconfig >/dev/null 2>&1; then
28+
SERVER_CN=$(ifconfig | grep "inet " | grep -v 127.0.0.1 | awk '{print $2}' | head -n1)
29+
fi
30+
31+
# If still empty, try ip command (modern Linux systems)
32+
if [ -z "$SERVER_CN" ] && command -v ip >/dev/null 2>&1; then
33+
SERVER_CN=$(ip -4 addr show | grep -oP '(?<=inet\s)\d+(\.\d+){3}' | grep -v 127.0.0.1 | head -n1)
34+
fi
35+
36+
# Fall back to localhost if auto-detection failed
37+
if [ -z "$SERVER_CN" ]; then
38+
SERVER_CN="localhost"
39+
echo "Warning: Could not auto-detect IP address. Using 'localhost' as SERVER_CN."
40+
echo " If your server runs on a different machine or IP, re-run with: ./generate_certs.sh <hostname_or_ip>"
41+
else
42+
echo "Auto-detected SERVER_CN: $SERVER_CN"
43+
fi
44+
fi
45+
46+
echo "Note: ESP32 clients must connect using: $SERVER_CN"
47+
echo ""
48+
49+
# Create directories if they don't exist
50+
mkdir -p main/certs/server
51+
52+
echo "Generating CA certificate..."
53+
openssl genrsa -out main/certs/ca_key.pem 2048
54+
openssl req -new -x509 -days 3650 -key main/certs/ca_key.pem -out main/certs/ca_cert.pem -subj "/C=US/ST=State/L=City/O=Organization/CN=TestCA"
55+
56+
echo "Generating Server certificate with CN=$SERVER_CN..."
57+
openssl genrsa -out main/certs/server/server_key.pem 2048
58+
openssl req -new -key main/certs/server/server_key.pem -out server_csr.pem -subj "/C=US/ST=State/L=City/O=Organization/CN=$SERVER_CN"
59+
openssl x509 -req -days 3650 -in server_csr.pem -CA main/certs/ca_cert.pem -CAkey main/certs/ca_key.pem -CAcreateserial -out main/certs/server/server_cert.pem
60+
61+
echo "Generating Client certificate..."
62+
openssl genrsa -out main/certs/client_key.pem 2048
63+
openssl req -new -key main/certs/client_key.pem -out client_csr.pem -subj "/C=US/ST=State/L=City/O=Organization/CN=TestClient"
64+
openssl x509 -req -days 3650 -in client_csr.pem -CA main/certs/ca_cert.pem -CAkey main/certs/ca_key.pem -CAcreateserial -out main/certs/client_cert.pem
65+
66+
# Clean up CSR files
67+
rm server_csr.pem client_csr.pem
68+
69+
echo "Certificates generated successfully!"
70+
echo ""
71+
echo "Generated files:"
72+
echo " - main/certs/ca_cert.pem (CA certificate)"
73+
echo " - main/certs/ca_key.pem (CA private key)"
74+
echo " - main/certs/client_cert.pem (Client certificate)"
75+
echo " - main/certs/client_key.pem (Client private key)"
76+
echo " - main/certs/server/server_cert.pem (Server certificate with CN=$SERVER_CN)"
77+
echo " - main/certs/server/server_key.pem (Server private key)"
78+
echo ""
79+
echo "IMPORTANT: Configure ESP32 clients to connect to: $SERVER_CN"
80+
echo " The server certificate is valid for this hostname/IP only."
81+
echo ""
82+
echo "Note: If the CN doesn't match your connection hostname/IP, you have two options:"
83+
echo " 1. Regenerate certificates with correct CN: ./generate_certs.sh <correct_hostname_or_ip>"
84+
echo " 2. Skip CN verification (TESTING ONLY): Enable CONFIG_WS_OVER_TLS_SKIP_COMMON_NAME_CHECK=y"
85+
echo " WARNING: Option 2 reduces security and should NOT be used in production!"

0 commit comments

Comments
 (0)