1.. _websocket_interface:
2
3Websocket Client API
4####################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13The Websocket client library allows Zephyr to connect to a Websocket server.
14The Websocket client API can be used directly by application to establish
15a Websocket connection to server, or it can be used as a transport for other
16network protocols like MQTT.
17
18See this
19`Websocket Wikipedia article <https://en.wikipedia.org/wiki/WebSocket>`_
20for a detailed overview of how Websocket works.
21
22For more information about the protocol itself, see
23`IETF RFC6455 The WebSocket Protocol <https://tools.ietf.org/html/rfc6455>`_.
24
25Websocket Transport
26*******************
27
28The Websocket API allows it to be used as a transport for other high level
29protocols like MQTT. The Zephyr MQTT client library can be configured to use
30Websocket transport by enabling :kconfig:option:`CONFIG_MQTT_LIB_WEBSOCKET` and
31:kconfig:option:`CONFIG_WEBSOCKET_CLIENT` Kconfig options.
32
33First a socket needs to be created and connected to the Websocket server:
34
35.. code-block:: c
36
37    sock = socket(family, SOCK_STREAM, IPPROTO_TCP);
38    ...
39    ret = connect(sock, addr, addr_len);
40    ...
41
42The Websocket transport socket is then created like this:
43
44.. code-block:: c
45
46    ws_sock = websocket_connect(sock, &config, timeout, user_data);
47
48The Websocket socket can then be used to send or receive data, and the
49Websocket client API will encapsulate the sent or received data to/from
50Websocket packet payload. Both the :c:func:`websocket_xxx()` API or normal
51BSD socket API functions can be used to send and receive application data.
52
53.. code-block:: c
54
55    ret = websocket_send_msg(ws_sock, buf_to_send, buf_len,
56                             WEBSOCKET_OPCODE_DATA_BINARY, true, true,
57			     K_FOREVER);
58    ...
59    ret = send(ws_sock, buf_to_send, buf_len, 0);
60
61If normal BSD socket functions are used, then currently only TEXT data
62is supported. In order to send BINARY data, the :c:func:`websocket_send_msg()`
63must be used.
64
65When done, the Websocket transport socket must be closed. User should handle
66the lifecycle(close/reuse) of tcp socket after websocket_disconnect.
67
68.. code-block:: c
69
70    ret = close(ws_sock);
71    or
72    ret = websocket_disconnect(ws_sock);
73
74
75API Reference
76*************
77
78.. doxygengroup:: websocket
79