ESP WebSocket Client

Overview

The ESP WebSocket client is an implementation of WebSocket protocol client for ESP32

Features

  • supports WebSocket over TCP, SSL with mbedtls
  • Easy to setup with URI
  • Multiple instances (Multiple clients in one application)

Configuration

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:
const esp_websocket_client_config_t ws_cfg = {
    .uri = "ws://websocket.org",
};
  • 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:
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

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:
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

Application Example

Simple WebSocket example that uses esp_websocket_client to establish a websocket connection and send/receive data with the websocket.org Server: protocols/websocket.

API Reference

Functions

esp_websocket_client_handle_t esp_websocket_client_init(const esp_websocket_client_config_t *config)

Start a Websocket session This function must be the first function to call, and it returns a esp_websocket_client_handle_t that you must use as input to other functions in the interface. This call MUST have a corresponding call to esp_websocket_client_destroy when the operation is complete.

Return
  • esp_websocket_client_handle_t
  • NULL if any errors
Parameters
  • config: The configuration

esp_err_t esp_websocket_client_set_uri(esp_websocket_client_handle_t client, const char *uri)

Set URL for client, when performing this behavior, the options in the URL will replace the old ones Must stop the WebSocket client before set URI if the client has been connected.

Return
esp_err_t
Parameters
  • client: The client
  • uri: The uri

esp_err_t esp_websocket_client_start(esp_websocket_client_handle_t client)

Open the WebSocket connection.

Return
esp_err_t
Parameters
  • client: The client

esp_err_t esp_websocket_client_stop(esp_websocket_client_handle_t client)

Close the WebSocket connection.

Return
esp_err_t
Parameters
  • client: The client

esp_err_t esp_websocket_client_destroy(esp_websocket_client_handle_t client)

Destroy the WebSocket connection and free all resources. This function must be the last function to call for an session. It is the opposite of the esp_websocket_client_init function and must be called with the same handle as input that a esp_websocket_client_init call returned. This might close all connections this handle has used.

Return
esp_err_t
Parameters
  • client: The client

int esp_websocket_client_send(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout)

Generic write data to the WebSocket connection; defaults to binary send.

Return
  • Number of data was sent
  • (-1) if any errors
Parameters
  • client: The client
  • data: The data
  • len: The length
  • timeout: Write data timeout in RTOS ticks

int esp_websocket_client_send_bin(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout)

Write binary data to the WebSocket connection (data send with WS OPCODE=02, i.e. binary)

Return
  • Number of data was sent
  • (-1) if any errors
Parameters
  • client: The client
  • data: The data
  • len: The length
  • timeout: Write data timeout in RTOS ticks

int esp_websocket_client_send_text(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout)

Write textual data to the WebSocket connection (data send with WS OPCODE=01, i.e. text)

Return
  • Number of data was sent
  • (-1) if any errors
Parameters
  • client: The client
  • data: The data
  • len: The length
  • timeout: Write data timeout in RTOS ticks

bool esp_websocket_client_is_connected(esp_websocket_client_handle_t client)

Check the WebSocket client connection state.

Return
  • true
  • false
Parameters
  • client: The client handle

esp_err_t esp_websocket_register_events(esp_websocket_client_handle_t client, esp_websocket_event_id_t event, esp_event_handler_t event_handler, void *event_handler_arg)

Register the Websocket Events.

Return
esp_err_t
Parameters
  • client: The client handle
  • event: The event id
  • event_handler: The callback function
  • event_handler_arg: User context

Structures

struct esp_websocket_event_data_t

Websocket event data.

Public Members

const char *data_ptr

Data pointer

int data_len

Data length

uint8_t op_code

Received opcode

esp_websocket_client_handle_t client

esp_websocket_client_handle_t context

void *user_context

user_data context, from esp_websocket_client_config_t user_data

int payload_len

Total payload length, payloads exceeding buffer will be posted through multiple events

int payload_offset

Actual offset for the data associated with this event

struct esp_websocket_client_config_t

Websocket client setup configuration.

Public Members

const char *uri

Websocket URI, the information on the URI can be overrides the other fields below, if any

const char *host

Domain or IP as string

int port

Port to connect, default depend on esp_websocket_transport_t (80 or 443)

const char *username

Using for Http authentication - Not supported for now

const char *password

Using for Http authentication - Not supported for now

const char *path

HTTP Path, if not set, default is /

bool disable_auto_reconnect

Disable the automatic reconnect function when disconnected

void *user_context

HTTP user data context

int task_prio

Websocket task priority

int task_stack

Websocket task stack

int buffer_size

Websocket buffer size

const char *cert_pem

SSL Certification, PEM format as string, if the client requires to verify server

esp_websocket_transport_t transport

Websocket transport type, see `esp_websocket_transport_t

char *subprotocol

Websocket subprotocol

char *user_agent

Websocket user-agent

char *headers

Websocket additional headers

int pingpong_timeout_sec

Period before connection is aborted due to no PONGs received, disabled if value is 0

Type Definitions

typedef struct esp_websocket_client *esp_websocket_client_handle_t

Enumerations

enum esp_websocket_event_id_t

Websocket Client events id.

Values:

WEBSOCKET_EVENT_ANY = -1
WEBSOCKET_EVENT_ERROR = 0

This event occurs when there are any errors during execution

WEBSOCKET_EVENT_CONNECTED

Once the Websocket has been connected to the server, no data exchange has been performed

WEBSOCKET_EVENT_DISCONNECTED

The connection has been disconnected

WEBSOCKET_EVENT_DATA

When receiving data from the server, possibly multiple portions of the packet

WEBSOCKET_EVENT_MAX
enum esp_websocket_transport_t

Websocket Client transport.

Values:

WEBSOCKET_TRANSPORT_UNKNOWN = 0x0

Transport unknown

WEBSOCKET_TRANSPORT_OVER_TCP

Transport over tcp

WEBSOCKET_TRANSPORT_OVER_SSL

Transport over ssl