1.. _thread_protocol_interface:
2
3Thread protocol
4###############
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12Thread is a low-power mesh networking technology, designed specifically for home
13automation applications. It is an IPv6-based standard, which uses 6LoWPAN
14technology over IEEE 802.15.4 protocol. IP connectivity lets you easily connect
15a Thread mesh network to the internet with a Thread Border Router.
16
17The Thread specification provides a high level of network security. Mesh networks
18built with Thread are secure - only authenticated devices can join the network
19and all communications within the mesh are encrypted. More information about
20Thread protocol can be found at
21`Thread Group website <https://www.threadgroup.org>`_.
22
23Zephyr integrates an open source Thread protocol implementation called OpenThread,
24documented on the `OpenThread website <https://openthread.io/>`_.
25
26Internet connectivity
27*********************
28
29A Thread Border Router is required to connect mesh network to the internet.
30An open source implementation of Thread Border Router is provided by the OpenThread
31community. See
32`OpenThread Border Router guide <https://openthread.io/guides/border-router>`_
33for instructions on how to set up a Border Router.
34
35Sample usage
36************
37
38You can try using OpenThread with the Zephyr Echo server and Echo client samples,
39which provide out-of-the-box configuration for OpenThread. To enable OpenThread
40support in these samples, build them with ``overlay-ot.conf`` overlay config file.
41See :zephyr:code-sample:`sockets-echo-server` and :zephyr:code-sample:`sockets-echo-client`
42samples for details.
43
44Zephyr also provides an :zephyr:code-sample:`openthread-shell`, which is useful for
45testing and debugging Thread and its underlying IEEE 802.15.4 drivers.
46
47Thread related APIs
48*******************
49
50OpenThread Driver API
51========================
52
53OpenThread L2 uses Zephyr's protocol agnostic IEEE 802.15.4 driver API
54internally. This API is of interest to **driver developers** that want to
55support OpenThread.
56
57The driver API is part of the :ref:`ieee802154_driver_api` subsystem and
58documented there.
59
60OpenThread L2 Adaptation Layer API
61==================================
62
63Zephyr's OpenThread L2 platform adaptation layer glues the external OpenThread
64stack together with Zephyr's IEEE 802.15.4 protocol agnostic driver API. This
65API is of interest to OpenThread L2 **subsystem contributors** only.
66
67OpenThread Platform API
68=======================
69
70The OpenThread platform API is defined by the OpenThread stack and implemented in Zephyr as an
71OpenThread module. Applications can use this implementation directly, or access it through the
72OpenThread L2 adaptation layer.
73
74Using the OpenThread L2 Adaptation Layer API
75--------------------------------------------
76
77To use the OpenThread platform API via the OpenThread L2 adaptation layer, enable both the
78:kconfig:option:`CONFIG_NET_L2_OPENTHREAD` and :kconfig:option:`CONFIG_NETWORKING` Kconfig options
79by setting them to ``y``. The adaptation layer will use the OpenThread radio API implementation
80found in :file:`modules/openthread/platform/radio.c`. In this setup, the OpenThread stack is
81initialized and managed by the adaptation layer.
82
83Using the OpenThread Platform API Directly
84------------------------------------------
85
86You can also use the OpenThread platform API directly, bypassing the OpenThread L2 adaptation
87layer. However, this approach requires you to provide your own implementation of the OpenThread
88radio API that is compatible with your specific radio driver.
89
90To use the OpenThread platform API directly, set the :kconfig:option:`CONFIG_OPENTHREAD` Kconfig
91option to ``y``, and do **not** set :kconfig:option:`CONFIG_NET_L2_OPENTHREAD`. In this case, you
92must implement the following functions from the `OpenThread radio API
93<https://openthread.io/reference/group/radio-config>`_ using your own radio driver:
94
95* ``otPlatRadioGetPromiscuous``
96* ``otPlatRadioGetCcaEnergyDetectThreshold``
97* ``otPlatRadioGetTransmitPower``
98* ``otPlatRadioGetIeeeEui64``
99* ``otPlatRadioSetPromiscuous``
100* ``otPlatRadioGetCaps``
101* ``otPlatRadioGetTransmitBuffer``
102* ``otPlatRadioSetPanId``
103* ``otPlatRadioEnable``
104* ``otPlatRadioDisable``
105* ``otPlatRadioReceive``
106* ``otPlatRadioGetRssi``
107* ``otPlatRadioGetReceiveSensitivity``
108* ``otPlatRadioEnergyScan``
109* ``otPlatRadioSetExtendedAddress``
110* ``otPlatRadioSetShortAddress``
111* ``otPlatRadioAddSrcMatchExtEntry``
112* ``otPlatRadioTransmit``
113* ``otPlatRadioClearSrcMatchShortEntries``
114* ``otPlatRadioClearSrcMatchExtEntries``
115* ``otPlatRadioEnableSrcMatch``
116* ``otPlatRadioAddSrcMatchShortEntry``
117* ``otPlatRadioClearSrcMatchShortEntry``
118* ``otPlatRadioClearSrcMatchExtEntry``
119
120Additionally, you must implement the following functions from the OpenThread radio API (see
121:zephyr_file:`include/zephyr/net/openthread.h`) to handle radio initialization and event processing:
122
123* :c:func:`platformRadioInit`
124* :c:func:`platformRadioProcess`
125
126To initialize the OpenThread stack in this approach, either call the :c:func:`ot_platform_init`
127function in your application, or enable the :kconfig:option:`CONFIG_OPENTHREAD_SYS_INIT` Kconfig
128option to automatically initialize OpenThread during system startup. You can set the
129initialization priority using the :kconfig:option:`CONFIG_OPENTHREAD_SYS_INIT_PRIORITY` Kconfig
130option.
131
132.. doxygengroup:: openthread
133