1.. zephyr:code-sample:: sockets-websocket-client
2   :name: WebSocket Client
3   :relevant-api: bsd_sockets websocket
4
5   Implement a Websocket client that connects to a Websocket server.
6
7Overview
8********
9
10This sample application implements a Websocket client that will do an HTTP
11or HTTPS handshake request to HTTP server, then start to send data and wait for
12the responses from the Websocket server.
13
14The source code for this sample application can be found at:
15:zephyr_file:`samples/net/sockets/websocket_client`.
16
17Requirements
18************
19
20- :ref:`networking_with_host`
21
22Building and Running
23********************
24
25You can use this application on a supported board, including
26running it inside QEMU as described in :ref:`networking_with_qemu`.
27
28Build websocket-client sample application like this:
29
30.. zephyr-app-commands::
31   :zephyr-app: samples/net/sockets/websocket_client
32   :board: <board to use>
33   :conf: <config file to use>
34   :goals: build
35   :compact:
36
37Enabling TLS support
38====================
39
40Enable TLS support in the sample by building the project with the
41``overlay-tls.conf`` overlay file enabled using these commands:
42
43.. zephyr-app-commands::
44   :zephyr-app: samples/net/sockets/websocket_client
45   :board: qemu_x86
46   :conf: "prj.conf overlay-tls.conf"
47   :goals: build
48   :compact:
49
50An alternative way is to specify ``-DEXTRA_CONF_FILE=overlay-tls.conf`` when
51running ``west build`` or ``cmake``.
52
53The certificate and private key used by the sample can be found in the sample's
54:zephyr_file:`samples/net/sockets/websocket_client/src/` directory.
55
56
57Running websocket-server in Linux Host
58======================================
59
60You can run this ``websocket-client`` sample application in QEMU
61and run the ``zephyr-websocket-server.py`` (from net-tools) on a Linux host.
62Other alternative is to install `websocketd <http://websocketd.com/>`_ and
63use that.
64
65To use QEMU for testing, follow the :ref:`networking_with_qemu` guide.
66
67In a terminal window you can do either:
68
69.. code-block:: console
70
71    $ ./zephyr-websocket-server.py
72
73or
74
75.. code-block:: console
76
77    $ websocketd --port=9001 cat
78
79Run ``websocket-client`` application in QEMU:
80
81.. zephyr-app-commands::
82   :zephyr-app: samples/net/sockets/websocket_client
83   :host-os: unix
84   :board: qemu_x86
85   :conf: prj.conf
86   :goals: run
87   :compact:
88
89Note that ``zephyr-websocket-server.py`` or ``websocketd`` must be running in
90the Linux host terminal window before you start the ``websocket-client``
91application in QEMU. Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
92
93Current version of ``zephyr-websocket-server.py`` found in
94`net-tools <https://github.com/zephyrproject-rtos/net-tools>`_ project, does
95not support TLS.
96