Skip to content

Commit 5f66f35

Browse files
glmfeglmfe
committed
feat(lws): Add initial support libwebsockets component
1 parent 936e43f commit 5f66f35

27 files changed

+1397
-2
lines changed

‎.github/workflows/lws_build.yml

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
name: "lws: build-tests"
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
pull_request:
8+
types: [opened, synchronize, reopened, labeled]
9+
10+
jobs:
11+
build_lws:
12+
if: contains(github.event.pull_request.labels.*.name, 'lws') || github.event_name == 'push'
13+
name: Libwebsockets build
14+
strategy:
15+
matrix:
16+
idf_ver: ["latest", "release-v5.3", "release-v5.4"]
17+
test: [ { app: example, path: "examples/client" }]
18+
runs-on: ubuntu-22.04
19+
container: espressif/idf:${{ matrix.idf_ver }}
20+
env:
21+
TEST_DIR: components/libwebsockets/${{ matrix.test.path }}
22+
steps:
23+
- name: Checkout esp-protocols
24+
uses: actions/checkout@v4
25+
with:
26+
submodules: recursive
27+
- name: Build ${{ matrix.example }} with IDF-${{ matrix.idf_ver }}
28+
shell: bash
29+
run: |
30+
. ${IDF_PATH}/export.sh
31+
python -m pip install idf-build-apps
32+
python ./ci/build_apps.py ${TEST_DIR}
33+
cd ${TEST_DIR}
34+
for dir in `ls -d build_esp32_*`; do
35+
$GITHUB_WORKSPACE/ci/clean_build_artifacts.sh `pwd`/$dir
36+
zip -qur artifacts.zip $dir
37+
done
38+
- uses: actions/upload-artifact@v4
39+
with:
40+
name: lws_target_esp32_${{ matrix.idf_ver }}_${{ matrix.test.app }}
41+
path: ${{ env.TEST_DIR }}/artifacts.zip
42+
if-no-files-found: error
43+
44+
run-target-lws:
45+
# Skip running on forks since it won't have access to secrets
46+
if: |
47+
github.repository == 'espressif/esp-protocols' &&
48+
( contains(github.event.pull_request.labels.*.name, 'lws') || github.event_name == 'push' )
49+
name: Target test
50+
needs: build_lws
51+
strategy:
52+
fail-fast: false
53+
matrix:
54+
idf_ver: ["latest", "release-v5.3", "release-v5.4"]
55+
idf_target: ["esp32"]
56+
test: [ { app: example, path: "examples/client" }]
57+
runs-on:
58+
- self-hosted
59+
- ESP32-ETHERNET-KIT
60+
env:
61+
TEST_DIR: components/libwebsockets/${{ matrix.test.path }}
62+
steps:
63+
- uses: actions/checkout@v4
64+
- uses: actions/download-artifact@v4
65+
with:
66+
name: lws_target_esp32_${{ matrix.idf_ver }}_${{ matrix.test.app }}
67+
path: ${{ env.TEST_DIR }}/ci/
68+
- name: Install Python packages
69+
env:
70+
PIP_EXTRA_INDEX_URL: "https://www.piwheels.org/simple"
71+
run: |
72+
pip install --only-binary cryptography --extra-index-url https://dl.espressif.com/pypi/ -r $GITHUB_WORKSPACE/ci/requirements.txt
73+
- name: Run Example Test on target
74+
working-directory: ${{ env.TEST_DIR }}
75+
run: |
76+
unzip ci/artifacts.zip -d ci
77+
for dir in `ls -d ci/build_*`; do
78+
rm -rf build sdkconfig.defaults
79+
mv $dir build
80+
python -m pytest --log-cli-level DEBUG --junit-xml=./results_${{ matrix.test.app }}_${{ matrix.idf_target }}_${{ matrix.idf_ver }}_${dir#"ci/build_"}.xml --target=${{ matrix.idf_target }}
81+
done
82+
- uses: actions/upload-artifact@v4
83+
if: always()
84+
with:
85+
name: results_${{ matrix.test.app }}_${{ matrix.idf_target }}_${{ matrix.idf_ver }}.xml
86+
path: components/libwebsockets/${{ matrix.test.path }}/*.xml

‎.github/workflows/publish-docs-component.yml

+1
Original file line numberDiff line numberDiff line change
@@ -102,5 +102,6 @@ jobs:
102102
components/mbedtls_cxx;
103103
components/mosquitto;
104104
components/sock_utils;
105+
components/libwebsockets;
105106
namespace: "espressif"
106107
api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }}

‎.gitmodules

+3
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,6 @@
44
[submodule "components/mosquitto/mosquitto"]
55
path = components/mosquitto/mosquitto
66
url = https://github.com/eclipse/mosquitto
7+
[submodule "components/libwebsockets/libwebsockets"]
8+
path = components/libwebsockets/libwebsockets
9+
url = https://github.com/warmcat/libwebsockets.git

‎.pre-commit-config.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ repos:
6161
- repo: local
6262
hooks:
6363
- id: commit message scopes
64-
name: "commit message must be scoped with: mdns, modem, websocket, asio, mqtt_cxx, console, common, eppp, tls_cxx, mosq, sockutls"
65-
entry: '\A(?!(feat|fix|ci|bump|test|docs|chore)\((mdns|modem|common|console|websocket|asio|mqtt_cxx|examples|eppp|tls_cxx|mosq|sockutls)\)\:)'
64+
name: "commit message must be scoped with: mdns, modem, websocket, asio, mqtt_cxx, console, common, eppp, tls_cxx, mosq, sockutls, lws"
65+
entry: '\A(?!(feat|fix|ci|bump|test|docs|chore)\((mdns|modem|common|console|websocket|asio|mqtt_cxx|examples|eppp|tls_cxx|mosq|sockutls|lws)\)\:)'
6666
language: pygrep
6767
args: [--multiline]
6868
stages: [commit-msg]

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,7 @@ Please refer to instructions in [ESP-IDF](https://github.com/espressif/esp-idf)
6666
### Socket helpers (sock-utils)
6767

6868
* Brief introduction [README](components/sock_utils/README.md)
69+
70+
### libwebsockets
71+
72+
* Brief introduction [README](components/libwebsockets/README.md)

‎components/libwebsockets/CMakeLists.txt

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
idf_component_register(REQUIRES mbedtls)
2+
3+
set(LWS_WITH_EXPORT_LWSTARGETS OFF CACHE BOOL "Export libwebsockets CMake targets. Disable if they conflict with an outer cmake project.")
4+
set(LWS_WITH_MBEDTLS ON CACHE BOOL "Use mbedTLS (>=2.0) replacement for OpenSSL.")
5+
set(LWS_WITH_JPEG OFF CACHE BOOL "Enable stateful JPEG stream decoder")
6+
7+
8+
set(WRAP_FUNCTIONS mbedtls_ssl_handshake_step
9+
lws_adopt_descriptor_vhost)
10+
11+
foreach(wrap ${WRAP_FUNCTIONS})
12+
target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--wrap=${wrap}")
13+
endforeach()
14+
15+
target_link_libraries(${COMPONENT_LIB} INTERFACE websockets)
16+
17+
target_sources(${COMPONENT_LIB} INTERFACE "port/lws_port.c")
18+
19+
20+
add_subdirectory(libwebsockets)

‎components/libwebsockets/README.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# ESP32 libwebsockets Port
2+
3+
This is a lightweight port of the libwebsockets library designed to run on the ESP32. It provides WebSocket client functionalities.
4+
5+
## Supported Options
6+
7+
The ESP-IDF port of libwebsockets supports a set of common WebSocket configurations for clients. These options can be configured through a structure passed to the `lws_create_context()` function.
8+
9+
Key features supported:
10+
- WebSocket with optional SSL/TLS
11+
- HTTP/1.1 client support
12+
13+
## Memory Footprint Considerations
14+
15+
The memory consumption primarily depends on the number of concurrent connections and the selected options for WebSocket frames, protocol handling, and SSL/TLS features. It consumes approximately 300 kB of program memory.
16+
17+
### Client:
18+
The values bellow were extracted from the client example (./examples/client/main/lws-client.c)
19+
- **Initial Memory Usage**: ~8 kB of heap on startup
20+
- **Connected Memory Usage Over TLS**: ~35.3 kB of heap after connected to a server
21+
- **Connected Memory Usage Over TCP (Plain)**: ~4.5 kB of heap after connected to a server
22+
23+
#### When configuring a WebSocket client, ensure that you have enough heap space to handle the desired number of concurrent client connections.
24+
#### SSL/TLS configurations may require additional memory overhead, depending on the certificate size and cryptographic settings.

‎components/libwebsockets/examples/client/CMakeLists.txt

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# The following lines of boilerplate have to be in your project's CMakeLists
2+
# in this exact order for cmake to work correctly
3+
cmake_minimum_required(VERSION 3.16)
4+
5+
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
6+
project(client_example)

0 commit comments

Comments
 (0)