Skip to content

Commit ba2f186

Browse files
633k4hire633k4hire
authored
Merge pull request #4 from 633k4hire/codex/amend-documentation-for-websocket-features
docs(websocket): add feature showcase example and refresh websocket docs
2 parents 91892bd + 38ef5b6 commit ba2f186

File tree

9 files changed

+371
-6
lines changed

9 files changed

+371
-6
lines changed

‎components/esp_websocket_client/README.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,22 @@
22

33
[![Component Registry](https://components.espressif.com/components/espressif/esp_websocket_client/badge.svg)](https://components.espressif.com/components/espressif/esp_websocket_client)
44

5-
The `esp-websocket_client` component is a managed component for `esp-idf` that contains implementation of [WebSocket protocol client](https://datatracker.ietf.org/doc/html/rfc6455) for ESP32
5+
The `esp-websocket_client` component is a managed component for `esp-idf` that contains an implementation of the [WebSocket protocol client](https://datatracker.ietf.org/doc/html/rfc6455) for ESP targets.
6+
7+
## Highlights
8+
9+
- WebSocket over TCP (`ws`) and TLS (`wss`)
10+
- Optional header callback event (`WEBSOCKET_EVENT_HEADER_RECEIVED`, IDF 6+)
11+
- Fragmented message send helpers for text and binary payloads
12+
- Runtime ping/reconnect tuning APIs
13+
- Pause/resume support without destroying the websocket task
14+
- Automatic HTTP redirect handling during websocket upgrade
615

716
## Examples
817

9-
Get started with example test [example](https://github.com/espressif/esp-protocols/tree/master/components/esp_websocket_client/examples):
18+
- Component examples: <https://github.com/espressif/esp-protocols/tree/master/components/esp_websocket_client/examples>
19+
- Feature showcase example (comprehensive walkthrough): <https://github.com/espressif/esp-protocols/tree/master/examples/websocket_features>
1020

1121
## Documentation
1222

13-
* View the full [html documentation](https://docs.espressif.com/projects/esp-protocols/esp_websocket_client/docs/latest/index.html)
23+
- Full HTML documentation: <https://docs.espressif.com/projects/esp-protocols/esp_websocket_client/docs/latest/index.html>

‎docs/esp_websocket_client/en/index.rst‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,13 @@ The ESP WebSocket client is an implementation of `WebSocket protocol client <htt
77

88
Features
99
--------
10-
* Supports WebSocket over TCP, TLS with mbedtls
10+
* Supports WebSocket over TCP and TLS with mbedtls
11+
* Supports HTTP handshake header callback via ``WEBSOCKET_EVENT_HEADER_RECEIVED``
12+
* Supports automatic HTTP redirect handling during websocket upgrade
13+
* Supports pause/resume without destroying the websocket task
14+
* Supports fragmented text/binary transmission APIs
1115
* Easy to setup with URI
12-
* Multiple instances (Multiple clients in one application)
16+
* Multiple instances (multiple clients in one application)
1317

1418
Configuration
1519
-------------
@@ -124,6 +128,7 @@ Events
124128
* `WEBSOCKET_EVENT_BEGIN`: The client thread is running.
125129
* `WEBSOCKET_EVENT_BEFORE_CONNECT`: The client is about to connect.
126130
* `WEBSOCKET_EVENT_CONNECTED`: The client has successfully established a connection to the server. The client is now ready to send and receive data. Contains no event data.
131+
* `WEBSOCKET_EVENT_HEADER_RECEIVED`: Posted for each pre-upgrade HTTP response header (IDF 6.0+ builds).
127132
* `WEBSOCKET_EVENT_DATA`: The client has successfully received and parsed a WebSocket frame. The event data contains a pointer to the payload data, the length of the payload data as well as the opcode of the received frame. A message may be fragmented into multiple events if the length exceeds the buffer size. This event will also be posted for non-payload frames, e.g. pong or connection close frames.
128133
* `WEBSOCKET_EVENT_ERROR`: The client has experienced an error. Examples include transport write or read failures.
129134
* `WEBSOCKET_EVENT_DISCONNECTED`: The client has aborted the connection due to the transport layer failing to read data, e.g. because the server is unavailable. Contains no event data.
@@ -143,7 +148,9 @@ Limitations and Known Issues
143148

144149
Application Example
145150
-------------------
146-
A simple WebSocket example that uses esp_websocket_client to establish a websocket connection and send/receive data with the `websocket.org <https://websocket.org>`_ server can be found here: `example <https://github.com/espressif/esp-protocols/tree/master/components/esp_websocket_client/examples>`_
151+
A simple WebSocket example that uses esp_websocket_client to establish a websocket connection and send/receive data can be found in the component example directory: `examples <https://github.com/espressif/esp-protocols/tree/master/components/esp_websocket_client/examples>`_.
152+
153+
For a broader feature walkthrough (headers callback, fragmented frames, pause/resume, runtime ping/reconnect tuning), see: `websocket_features example <https://github.com/espressif/esp-protocols/tree/master/examples/websocket_features>`_.
147154

148155
Sending Text Data
149156
^^^^^^^^^^^^^^^^^

‎examples/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ This directory showcases a variety of examples, illustrating the use of differen
1515
3. **MQTT Demo on Linux**: A comprehensive demonstration of an MQTT (Message Queuing Telemetry Transport) application designed to run on a Linux environment.
1616
Location: [mqtt](mqtt)
1717

18+
4. **WebSocket Feature Showcase**: Demonstrates modern `esp_websocket_client` features such as header callbacks, custom headers, fragmented frames, pause/resume, and runtime ping/reconnect tuning.
19+
Location: [websocket_features](websocket_features)
20+
1821
## Additional Resources and Examples
1922

2023
For an extensive collection of additional examples, especially those related to specific components, please visit the upper layer directory and navigate to the respective component's example directory.

‎examples/websocket_features/CMakeLists.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
cmake_minimum_required(VERSION 3.16)
2+
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
3+
project(websocket_features)

‎examples/websocket_features/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# WebSocket Feature Showcase Example
2+
3+
## Overview
4+
5+
This example demonstrates the newest `esp_websocket_client` capabilities in one place, with verbose comments in code and runtime logs.
6+
7+
It is designed to be a **reference app** when you want to copy/paste a production-ready websocket control flow and then trim it for your use case.
8+
9+
### Features Demonstrated
10+
11+
1. Event-driven lifecycle handling (`BEGIN`, `BEFORE_CONNECT`, `CONNECTED`, `DATA`, `ERROR`, `DISCONNECTED`, `CLOSED`, `FINISH`)
12+
2. Header inspection via `WEBSOCKET_EVENT_HEADER_RECEIVED` (IDF 6+)
13+
3. Custom headers using both:
14+
- `esp_websocket_client_set_headers()`
15+
- `esp_websocket_client_append_header()`
16+
4. Fragmented transfer APIs:
17+
- `esp_websocket_client_send_text_partial()`
18+
- `esp_websocket_client_send_bin_partial()`
19+
- `esp_websocket_client_send_cont_msg()`
20+
- `esp_websocket_client_send_fin()`
21+
5. Runtime reconnect tuning:
22+
- `esp_websocket_client_get_reconnect_timeout()`
23+
- `esp_websocket_client_set_reconnect_timeout()`
24+
6. Runtime ping tuning:
25+
- `esp_websocket_client_get_ping_interval_sec()`
26+
- `esp_websocket_client_set_ping_interval_sec()`
27+
7. Task-preserving reconnect with:
28+
- `esp_websocket_client_pause()`
29+
- `esp_websocket_client_set_uri()`
30+
- `esp_websocket_client_resume()`
31+
8. Close handshake and clean teardown:
32+
- `esp_websocket_client_close()`
33+
- unregister events
34+
- `esp_websocket_client_destroy()`
35+
9. Heap/stability observability:
36+
- heap snapshots before init and after destroy
37+
- lifecycle summary logging for connect/error states
38+
- cleanup path that avoids hard-failing during recovery paths
39+
40+
## Project Layout
41+
42+
- `main/app_main.c` — fully commented example source.
43+
- `main/Kconfig.projbuild` — URI configuration in menuconfig.
44+
- `main/idf_component.yml` — dependencies.
45+
46+
## Configure
47+
48+
Set your endpoint in menuconfig:
49+
50+
```bash
51+
idf.py menuconfig
52+
```
53+
54+
Path:
55+
56+
```text
57+
WebSocket Feature Showcase Configuration --->
58+
WebSocket endpoint URI
59+
```
60+
61+
Default endpoint:
62+
63+
```text
64+
wss://echo.websocket.events
65+
```
66+
67+
## Build & Flash
68+
69+
```bash
70+
idf.py set-target esp32
71+
idf.py build
72+
idf.py -p /dev/ttyUSB0 flash monitor
73+
```
74+
75+
## What to look for in logs
76+
77+
- Upgrade headers printed by `WEBSOCKET_EVENT_HEADER_RECEIVED`.
78+
- Text + binary + fragmented send sequences.
79+
- Ping/reconnect values before and after runtime update.
80+
- Pause/resume flow reconnecting without destroying the task.
81+
- Heap snapshots and a final "Heap recovery" message after client destroy.
82+
83+
## Notes
84+
85+
- If your server uses TLS with a private CA, configure certificates as needed for your deployment.
86+
- Redirect handling is managed by the websocket transport layer; this example focuses on application-side controls and observability.

‎examples/websocket_features/main/CMakeLists.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
idf_component_register(SRCS "app_main.c"
2+
INCLUDE_DIRS ".")

‎examples/websocket_features/main/Kconfig.projbuild‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
menu "WebSocket Feature Showcase Configuration"
2+
3+
config WEBSOCKET_FEATURES_URI
4+
string "WebSocket endpoint URI"
5+
default "wss://echo.websocket.events"
6+
help
7+
URI used by the websocket_features example.
8+
9+
endmenu

0 commit comments

Comments
 (0)