a669ba5623
Add an entry to the release note to inform about the new CONFIG_OPENTHREAD_SYS_INIT Kconfig option. Signed-off-by: Arkadiusz Balys <arkadiusz.balys@nordicsemi.no>
133 lines
5.3 KiB
ReStructuredText
133 lines
5.3 KiB
ReStructuredText
.. _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
|