doc/connectivity/networking/api/thread.rst

.. _thread_protocol_interface:

Thread protocol
###############

.. contents::
    :local:
    :depth: 2

Overview
********
Thread is a low-power mesh networking technology, designed specifically for home
automation applications. It is an IPv6-based standard, which uses 6LoWPAN
technology over IEEE 802.15.4 protocol. IP connectivity lets you easily connect
a Thread mesh network to the internet with a Thread Border Router.

The Thread specification provides a high level of network security. Mesh networks
built with Thread are secure - only authenticated devices can join the network
and all communications within the mesh are encrypted. More information about
Thread protocol can be found at
`Thread Group website <https://www.threadgroup.org>`_.

Zephyr integrates an open source Thread protocol implementation called OpenThread,
documented on the `OpenThread website <https://openthread.io/>`_.

Internet connectivity
*********************

A Thread Border Router is required to connect mesh network to the internet.
An open source implementation of Thread Border Router is provided by the OpenThread
community. See
`OpenThread Border Router guide <https://openthread.io/guides/border-router>`_
for instructions on how to set up a Border Router.

Sample usage
************

You can try using OpenThread with the Zephyr Echo server and Echo client samples,
which provide out-of-the-box configuration for OpenThread. To enable OpenThread
support in these samples, build them with ``overlay-ot.conf`` overlay config file.
See :zephyr:code-sample:`sockets-echo-server` and :zephyr:code-sample:`sockets-echo-client`
samples for details.

Zephyr also provides an :zephyr:code-sample:`openthread-shell`, which is useful for
testing and debugging Thread and its underlying IEEE 802.15.4 drivers.

Thread related APIs
*******************

OpenThread Driver API
========================

OpenThread L2 uses Zephyr's protocol agnostic IEEE 802.15.4 driver API
internally. This API is of interest to **driver developers** that want to
support OpenThread.

The driver API is part of the :ref:`ieee802154_driver_api` subsystem and
documented there.

OpenThread L2 Adaptation Layer API
==================================

Zephyr's OpenThread L2 platform adaptation layer glues the external OpenThread
stack together with Zephyr's IEEE 802.15.4 protocol agnostic driver API. This
API is of interest to OpenThread L2 **subsystem contributors** only.

OpenThread Platform API
=======================

The OpenThread platform API is defined by the OpenThread stack and implemented in Zephyr as an
OpenThread module. Applications can use this implementation directly, or access it through the
OpenThread L2 adaptation layer.

Using the OpenThread L2 Adaptation Layer API
--------------------------------------------

To use the OpenThread platform API via the OpenThread L2 adaptation layer, enable both the
:kconfig:option:`CONFIG_NET_L2_OPENTHREAD` and :kconfig:option:`CONFIG_NETWORKING` Kconfig options
by setting them to ``y``. The adaptation layer will use the OpenThread radio API implementation
found in :file:`modules/openthread/platform/radio.c`. In this setup, the OpenThread stack is
initialized and managed by the adaptation layer.

Using the OpenThread Platform API Directly
------------------------------------------

You can also use the OpenThread platform API directly, bypassing the OpenThread L2 adaptation
layer. However, this approach requires you to provide your own implementation of the OpenThread
radio API that is compatible with your specific radio driver.

To use the OpenThread platform API directly, set the :kconfig:option:`CONFIG_OPENTHREAD` Kconfig
option to ``y``, and do **not** set :kconfig:option:`CONFIG_NET_L2_OPENTHREAD`. In this case, you
must implement the following functions from the `OpenThread radio API
<https://openthread.io/reference/group/radio-config>`_ using your own radio driver:

* ``otPlatRadioGetPromiscuous``
* ``otPlatRadioGetCcaEnergyDetectThreshold``
* ``otPlatRadioGetTransmitPower``
* ``otPlatRadioGetIeeeEui64``
* ``otPlatRadioSetPromiscuous``
* ``otPlatRadioGetCaps``
* ``otPlatRadioGetTransmitBuffer``
* ``otPlatRadioSetPanId``
* ``otPlatRadioEnable``
* ``otPlatRadioDisable``
* ``otPlatRadioReceive``
* ``otPlatRadioGetRssi``
* ``otPlatRadioGetReceiveSensitivity``
* ``otPlatRadioEnergyScan``
* ``otPlatRadioSetExtendedAddress``
* ``otPlatRadioSetShortAddress``
* ``otPlatRadioAddSrcMatchExtEntry``
* ``otPlatRadioTransmit``
* ``otPlatRadioClearSrcMatchShortEntries``
* ``otPlatRadioClearSrcMatchExtEntries``
* ``otPlatRadioEnableSrcMatch``
* ``otPlatRadioAddSrcMatchShortEntry``
* ``otPlatRadioClearSrcMatchShortEntry``
* ``otPlatRadioClearSrcMatchExtEntry``

Additionally, you must implement the following functions from the OpenThread radio API (see
:zephyr_file:`include/zephyr/net/openthread.h`) to handle radio initialization and event processing:

* :c:func:`platformRadioInit`
* :c:func:`platformRadioProcess`

To initialize the OpenThread stack in this approach, either call the :c:func:`ot_platform_init`
function in your application, or enable the :kconfig:option:`CONFIG_OPENTHREAD_SYS_INIT` Kconfig
option to automatically initialize OpenThread during system startup. You can set the
initialization priority using the :kconfig:option:`CONFIG_OPENTHREAD_SYS_INIT_PRIORITY` Kconfig
option.

.. doxygengroup:: openthread