kopia lustrzana https://github.com/espressif/esp-idf
doc/websocket: updates the API reference for ESP WebSocket Client
Marius Vikhammer
rodzic
79a5b0b5af
commit
09f240c1e1
|
|
@ -3,11 +3,11 @@ ESP WebSocket Client
|
|||
|
||||
Overview
|
||||
--------
|
||||
The ESP WebSocket client is an implementation of `WebSocket protocol client <https://tools.ietf.org/html/rfc6455>`_ for ESP32
|
||||
The ESP WebSocket client is an implementation of `WebSocket protocol client <https://tools.ietf.org/html/rfc6455>`_ for {IDF_TARGET_NAME}
|
||||
|
||||
Features
|
||||
--------
|
||||
* supports WebSocket over TCP, SSL with mbedtls
|
||||
* Supports WebSocket over TCP, TLS with mbedtls
|
||||
* Easy to setup with URI
|
||||
* Multiple instances (Multiple clients in one application)
|
||||
|
||||
|
|
@ -19,48 +19,105 @@ URI
|
|||
- Supports ``ws``, ``wss`` schemes
|
||||
- WebSocket samples:
|
||||
|
||||
- ``ws://websocket.org``: WebSocket over TCP, default port 80
|
||||
- ``wss://websocket.org``: WebSocket over SSL, default port 443
|
||||
|
||||
- Minimal configurations:
|
||||
- ``ws://echo.websocket.org``: WebSocket over TCP, default port 80
|
||||
- ``wss://echo.websocket.org``: WebSocket over SSL, default port 443
|
||||
|
||||
Minimal configurations:
|
||||
|
||||
.. code:: c
|
||||
|
||||
const esp_websocket_client_config_t ws_cfg = {
|
||||
.uri = "ws://echo.websocket.org",
|
||||
};
|
||||
|
||||
The WebSocket client supports the use of both path and query in the URI. Sample:
|
||||
|
||||
.. code:: c
|
||||
|
||||
const esp_websocket_client_config_t ws_cfg = {
|
||||
.uri = "ws://echo.websocket.org/connectionhandler?id=104",
|
||||
};
|
||||
|
||||
|
||||
If there are any options related to the URI in
|
||||
:cpp:type:`esp_websocket_client_config_t`, the option defined by the URI will be
|
||||
overridden. Sample:
|
||||
|
||||
.. code:: c
|
||||
|
||||
const esp_websocket_client_config_t ws_cfg = {
|
||||
.uri = "ws://echo.websocket.org:123",
|
||||
.port = 4567,
|
||||
};
|
||||
//WebSocket client will connect to websocket.org using port 4567
|
||||
|
||||
TLS
|
||||
^^^
|
||||
|
||||
Configuration:
|
||||
|
||||
.. code:: c
|
||||
|
||||
const esp_websocket_client_config_t ws_cfg = {
|
||||
.uri = "wss://echo.websocket.org",
|
||||
.cert_pem = (const char *)websocket_org_pem_start,
|
||||
};
|
||||
|
||||
.. note:: If you want to verify the server, then you need to provide a certificate in PEM format, and provide to ``cert_pem`` in :cpp:type:`websocket_client_config_t`. If no certficate is provided then the TLS connection will to default not requiring verification.
|
||||
|
||||
PEM certificate for this example could be extracted from an openssl `s_client` command connecting to websocket.org.
|
||||
In case a host operating system has `openssl` and `sed` packages installed, one could execute the following command to download and save the root or intermediate root certificate to a file (Note for Windows users: Both Linux like environment or Windows native packages may be used).
|
||||
```
|
||||
echo "" | openssl s_client -showcerts -connect websocket.org:443 | sed -n "1,/Root/d; /BEGIN/,/END/p" | openssl x509 -outform PEM >websocket_org.pem
|
||||
```
|
||||
|
||||
This command will extract the second certificate in the chain and save it as a pem-file.
|
||||
|
||||
Subprotocol
|
||||
^^^^^^^^^^^
|
||||
|
||||
The subprotocol field in the config struct can be used to request a subprotocol
|
||||
|
||||
.. code:: c
|
||||
|
||||
const esp_websocket_client_config_t ws_cfg = {
|
||||
.uri = "ws://websocket.org",
|
||||
.subprotocol = "soap",
|
||||
};
|
||||
|
||||
- If there are any options related to the URI in
|
||||
``esp_websocket_client_config_t``, the option defined by the URI will be
|
||||
overridden. Sample:
|
||||
.. note:: The client is indifferent to the subprotocol field in the server response and will accept the connection no matter what the server replies.
|
||||
|
||||
For more options on :cpp:type:`esp_websocket_client_config_t`, please refer to API reference below
|
||||
|
||||
Events
|
||||
------
|
||||
* `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.
|
||||
* `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.
|
||||
* `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.
|
||||
* `WEBSOCKET_EVENT_ERROR`: Not used in the current implementation of the client.
|
||||
|
||||
If the client handle is needed in the event handler it can be accessed through the pointer passed to the event handler:
|
||||
|
||||
.. code:: c
|
||||
|
||||
const esp_websocket_client_config_t ws_cfg = {
|
||||
.uri = "ws://websocket.org:123",
|
||||
.port = 4567,
|
||||
};
|
||||
//WebSocket client will connect to websocket.org using port 4567
|
||||
esp_websocket_client_handle_t client = (esp_websocket_client_handle_t)handler_args;
|
||||
|
||||
SSL
|
||||
^^^
|
||||
|
||||
- Get certificate from server, example: ``websocket.org``
|
||||
``openssl s_client -showcerts -connect websocket.org:443 </dev/null 2>/dev/null|openssl x509 -outform PEM >websocket_org.pem``
|
||||
- Configuration:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
const esp_websocket_client_config_t ws_cfg = {
|
||||
.uri = "wss://websocket.org",
|
||||
.cert_pem = (const char *)websocket_org_pem_start,
|
||||
};
|
||||
|
||||
For more options on ``esp_websocket_client_config_t``, please refer to API reference below
|
||||
Limitations and Known Issues
|
||||
----------------------------
|
||||
* The client is able to request the use of a subprotocol from the server during the handshake, but does not do any subprotocol related checks on the response from the server.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
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: :example:`protocols/websocket`.
|
||||
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:`protocols/websocket`.
|
||||
|
||||
Sending Text Data
|
||||
^^^^^^^^^^^^^^^^^
|
||||
The WebSocket client supports sending data as a text data frame, which informs the application layer that the payload data is text data encoded as UTF-8. Example:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
esp_websocket_client_send_text(client, data, len, portMAX_DELAY);
|
||||
|
||||
|
||||
API Reference
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue