From 7b80c0b7558684dc8000ea7a7726d7f401936993 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotr=20Jasi=C5=84ski?= Date: Tue, 18 Apr 2023 16:37:23 +0200 Subject: [PATCH] doc: Thread: created types page, moved sed vs ssed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added dedicated pages for Thread device types, as well as SED and SSED comparison. Signed-off-by: Piotr Jasiński Signed-off-by: Wille Backman --- doc/nrf/links.txt | 6 + doc/nrf/protocols/thread/device_types.rst | 133 ++++++++++++++++++ doc/nrf/protocols/thread/index.rst | 2 + .../thread/overview/commissioning.rst | 21 +-- .../thread/overview/supported_features.rst | 2 + doc/nrf/protocols/thread/sed_ssed.rst | 64 +++++++++ doc/nrf/releases/release-notes-changelog.rst | 5 +- samples/matter/window_covering/README.rst | 16 ++- 8 files changed, 225 insertions(+), 24 deletions(-) create mode 100644 doc/nrf/protocols/thread/device_types.rst create mode 100644 doc/nrf/protocols/thread/sed_ssed.rst diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index 3dd7d868112..efd768f36e9 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -80,6 +80,8 @@ .. _`nRF52820 CMakeLists.txt`: https://github.com/zephyrproject-rtos/zephyr/blob/main/boards/arm/nrf52833dk_nrf52820/CMakeLists.txt .. _`OpenThread CLI Reference`: https://github.com/openthread/openthread/blob/main/src/cli/README.md +.. _`OpenThread CLI Reference - csl command`: https://github.com/openthread/openthread/blob/main/src/cli/README.md#csl +.. _`OpenThread CLI Reference - pollperiod command`: https://github.com/openthread/openthread/blob/main/src/cli/README.md#pollperiod .. _`Commissioner CLI commands`: https://github.com/openthread/openthread/blob/main/src/cli/README_COMMISSIONER.md .. _`Joiner CLI commands`: https://github.com/openthread/openthread/blob/main/src/cli/README_JOINER.md @@ -824,6 +826,10 @@ .. _`OpenThread CoAP API`: https://openthread.io/reference/group/api-coap +.. _`IPv6 multicast addressing`: https://openthread.io/guides/thread-primer/ipv6-addressing#multicast + +.. _`Joining an existing Thread network`: https://openthread.io/guides/thread-primer/network-discovery#join_an_existing_network + .. ### Source: threadgroup.* .. _`Thread Group`: https://www.threadgroup.org diff --git a/doc/nrf/protocols/thread/device_types.rst b/doc/nrf/protocols/thread/device_types.rst new file mode 100644 index 00000000000..fd9aa8164ee --- /dev/null +++ b/doc/nrf/protocols/thread/device_types.rst @@ -0,0 +1,133 @@ +.. _thread_device_types: + +Thread device types +################### + +.. contents:: + :local: + :depth: 2 + +Thread devices can be either Full Thread Devices (FTD) or Minimal Thread Devices (MTD). +The devices are divided based on their ability to exist in a network without a parent, determined by whether the device maintains a routing table (doesn't need a parent) or not (needs a parent). +FTDs are the devices that maintain a routing table, while MTDs do not, forwarding all their messages to a parent instead. + +Another type of Thread device classification is based on the device's ability to route messages: + +* Routers can route messages, and they can function as parents to other Thread devices. +* End Devices cannot route messages, and they cannot function as parents. + +Based on this classification, FTDs can be either Routers or End Devices, while MTDs can only be End Devices. + +For additional information about Thread device types, see the documentation for `Device Types on OpenThread portal`_. + +.. _thread_types_ftd: + +Full Thread Devices +******************* + +In order to maintain the routing table, FTDs keep their radio on at all times. +An important difference between FTDs and MTDs is that FTDs subscribe to special "all-routers" multicast addresses (``ff02::2`` and ``ff03::2``, see `IPv6 multicast addressing`_). +Because of these reasons, they typically consume more power than MTDs. + +Full Thread Devices can be further divided into three categories: + +* Router +* Full End Device (FED) +* Router Eligible End Device (REED) + +.. list-table:: Full Thread Device categories + :widths: 15 10 10 15 + :header-rows: 1 + + * - + - Router + - Full End Device + - Router Eligible End Device + * - Maintains a routing table + - Yes + - Yes + - Yes + * - Routes messages + - Yes + - No + - When working as a Router + * - Can extend the network + - Yes + - No + - When working as a Router + +Routers can be regarded as the backbone of a Thread network. +They maintain the routing table and forward messages to other devices. +Routers, unlike End Devices, can also be used to extend the network range and a Router is required for a Minimal End Device to join the network. +The maximum number of Routers in a single Thread network is 32. + +FEDs maintain a routing table, but they can't route messages. +This means they don't require a parent (Router) to function, but they cannot become parents themselves. + +REEDs maintain a routing table and, unlike FEDs, they can become Routers if needed. +If a REED is the only device in range of an End Device trying to join the network, it will promote itself to a Router (see `Joining an existing Thread network`_ in the OpenThread documentation for more information). +Conversely, when a Router has no children it can downgrade itself to a REED. + +.. _thread_types_mtd: + +Minimal Thread Devices +********************** + +Minimal Thread Devices (MTDs) are devices that do not maintain a routing table and are typically low-power devices that are not always on. +They can only be End Devices, and they always need a parent to function. +They forward all their messages to their parent. + +Minimal Thread Devices can be further divided into three categories: + +* Minimal End Device (MED) +* Sleepy End Device (SED) +* Synchronized Sleepy End Device (SSED) + +.. list-table:: Minimal Thread Device categories + :widths: 15 10 10 15 + :header-rows: 1 + + * - + - Minimal End Device + - Sleepy End Device + - Synchronized Sleepy End Device + * - Maintains a routing table + - No + - No + - No + * - Radio on + - Always + - Periodically + - Periodically + * - New messages + - Parent immediately forwards the messages + - The SED polls for new messages when it wakes up + - Parent forwards the messages during designated transmission window + * - No new messages + - No data transmission + - Parent indicates no pending messages + - No data transmission + +MEDs are the most basic MTDs, and their radio is always on. +They don't keep a routing table, but otherwise operate like :ref:`FEDs `. + +SEDs try to limit their power consumption by sleeping most of the time, waking up periodically to poll for messages from their parent. +After waking up, they send a data request to their parent. +If the parent has any pending messages, it will send them to the SED. +Otherwise, the parent will send a response indicating no pending messages. + +SSEDs operate similarly to Sleepy End Devices, but they are synchronized with their parent. +They wake up at the same time as their parent, eliminating the need for polling for messages. +If the parent has messages for the SSED, it sends them during the designated transmission window. +The SSED allows the transmission to finish if radio activity is detected during the transmission window. +Conversely, if there is no radio activity during the specified duration of transmission window, this indicates that the parent has no messages for the SSED and the SSED returns to sleep. +The SSED synchronization results in lower power consumption compared to an SED, primarily because the SSED doesn't need to poll for messages, keeping transmission windows short. + +For more information about SSED activity, see the :ref:`thread_sed_ssed` page. + +.. _thread_types_configuring: + +Type configuration +****************** + +See :ref:`thread_ug_device_type` for information about how to configure Thread device type. diff --git a/doc/nrf/protocols/thread/index.rst b/doc/nrf/protocols/thread/index.rst index a93555db6c7..3104d0b285c 100644 --- a/doc/nrf/protocols/thread/index.rst +++ b/doc/nrf/protocols/thread/index.rst @@ -31,3 +31,5 @@ You can find more information about Thread on the `Thread Group`_ pages. prebuilt_libs tools certification + device_types + sed_ssed diff --git a/doc/nrf/protocols/thread/overview/commissioning.rst b/doc/nrf/protocols/thread/overview/commissioning.rst index d91cd8bc4e4..e39f970d9a7 100644 --- a/doc/nrf/protocols/thread/overview/commissioning.rst +++ b/doc/nrf/protocols/thread/overview/commissioning.rst @@ -78,26 +78,7 @@ Minimal Thread Device (MTD) A SSED is an enhanced SED. It transmits less data than SED and relies on receiving messages from its parent only in specified time intervals. -For more information, see `Device Types on OpenThread portal`_. - -SED vs SSED activity --------------------- - -.. thread_ssed_description_start - -A Thread Synchronized Sleepy End Device (SSED) is synchronized with its parent router and uses the radio only at scheduled intervals, by using the Coordinated Sampled Listening (CSL) feature introduced as one of `Thread 1.2 Base Features`_. -During those intervals, the device waits for the router to send it any data related to the desired device activity. -The SSED does require sending packets occasionally to keep synchronization with the router. -However, unlike a regular SED, an SSED does not actively communicate with the router by polling and goes into the idle mode in-between the scheduled activity periods. -If there is no application-related traffic for a longer period of time, the SSED sends a data poll request packet to synchronize with the parent. -Overall, the SSED features further reduce energy consumption of the device and generate less data traffic compared to a standard Thread SED. - -.. figure:: images/thread_sed_ssed_comparison.svg - :alt: Comparison of Thread SED and Thread SSED radio activity - - Comparison of Thread SED and Thread SSED radio activity - -.. thread_ssed_description_end +For more information, see the :ref:`thread_device_types` page. .. _thread_ot_commissioning_types: diff --git a/doc/nrf/protocols/thread/overview/supported_features.rst b/doc/nrf/protocols/thread/overview/supported_features.rst index debbd556a99..4d80cfeb19c 100644 --- a/doc/nrf/protocols/thread/overview/supported_features.rst +++ b/doc/nrf/protocols/thread/overview/supported_features.rst @@ -49,6 +49,8 @@ For more information about this Thread version, see the official `Thread 1.2 in .. note:: See :ref:`thread_ug_thread_specification_options` for the list of 1.2 features that are currently available in |NCS|. +.. _thread_ug_supported_features_csl: + Coordinated Sampled Listening (CSL) =================================== diff --git a/doc/nrf/protocols/thread/sed_ssed.rst b/doc/nrf/protocols/thread/sed_ssed.rst new file mode 100644 index 00000000000..fa1f6b180e7 --- /dev/null +++ b/doc/nrf/protocols/thread/sed_ssed.rst @@ -0,0 +1,64 @@ +.. _thread_sed_ssed: + +Sleepy End Device types in Thread +################################# + +Sleepy End Devices (SEDs) and Synchronized Sleepy End Devices (SSEDs) are both Minimal Thread Devices (MTDs). +Unlike Full Thread Devices (FTDs), MTDs do not maintain a routing table and are typically low-power devices that are not always on. + +For more information, see the :ref:`thread_types_mtd` section in the :ref:`thread_device_types` documentation. + +Sleepy End Device +***************** + +SEDs are MTDs that sleep most of the time in order to minimize the power consumption. +They communicate with the Thread network by occasionally polling the parent Router for any pending data. + +The :kconfig:option:`CONFIG_OPENTHREAD_POLL_PERIOD` Kconfig handles the SED configuration by configuring the polling period. +A higher polling frequency results in lower latency (better responsiveness), but also higher power consumption. + +The polling period can also be configured in runtime. +See the ``pollperiod`` command in the OpenThread `CLI reference `_. + +Synchronized Sleepy End Device +****************************** + +SSEDs are MTDs that are further optimized for power consumption. +A Thread SSED is synchronized with its parent Router and uses the radio only at scheduled intervals. +It does this by using the :ref:`thread_ug_supported_features_csl` feature (introduced as one of the `Thread 1.2 Base Features`_). +During those intervals, the device waits for the Router to send it any data related to the desired device activity. +This reduces the network traffic (since there is no polling) and the power consumption (since the radio is off most of the time). + +An SSED does require sending packets occasionally to keep synchronization with the Router. +However, unlike a regular SED, an SSED does not actively communicate with the Router by polling and it goes into the idle mode between the scheduled activity periods. +If there is no application-related traffic for an extended period of time, the SSED sends a data poll request packet to synchronize with the parent. + +The |NCS| provides the following Kconfig options that let you enable CSL and specify the CSL parameters: + +* :kconfig:option:`CONFIG_OPENTHREAD_CSL_RECEIVER` - Enables SSED child mode. +* :kconfig:option:`CONFIG_OPENTHREAD_CSL_AUTO_SYNC` - Enables the CSL autosynchronization feature. +* :kconfig:option:`CONFIG_OPENTHREAD_CSL_TIMEOUT` - Sets the default CSL timeout in seconds. +* :kconfig:option:`CONFIG_OPENTHREAD_CSL_CHANNEL` - Sets the default CSL channel. + This option corresponds to the ``csl channel`` CLI parameter. + +The following Kconfig options affect the size of the receive window, and thus also affect the device's power consumption: + +* :kconfig:option:`CONFIG_OPENTHREAD_CSL_RECEIVE_TIME_AHEAD` - Sets the CSL receiver wake up margin in microseconds. +* :kconfig:option:`CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AHEAD` - Sets the minimum receiving time before start of MAC header. +* :kconfig:option:`CONFIG_OPENTHREAD_MIN_RECEIVE_ON_AFTER` - Sets the minimum receiving time after start of MAC header. +* :kconfig:option:`CONFIG_OPENTHREAD_PLATFORM_CSL_UNCERT` - Sets the fixed uncertainty of the device for scheduling CSL Transmissions in units of 10 microseconds. + +Additionally, you must configure the ``period`` CLI parameter to enable CSL. +For more information on using the CLI to configure parameters for CSL, see the ``csl`` command in the OpenThread `CLI reference `_. + +Comparison of SED and SSED +************************** + +Compared to an SED, an SSED has no drawbacks for transmission and provides reduced power consumption and network traffic. +This means you should configure your SED devices as SSEDs whenever possible. +You can see the difference in power consumption on the :ref:`Thread power consumption ` page. + +.. figure:: overview/images/thread_sed_ssed_comparison.svg + :alt: Comparison of Thread SED and Thread SSED radio activity + + Comparison of Thread SED and Thread SSED radio activity diff --git a/doc/nrf/releases/release-notes-changelog.rst b/doc/nrf/releases/release-notes-changelog.rst index b72d75beadb..c63f3ca3d83 100644 --- a/doc/nrf/releases/release-notes-changelog.rst +++ b/doc/nrf/releases/release-notes-changelog.rst @@ -427,4 +427,7 @@ cJSON Documentation ============= -* Added a page on :ref:`ug_wireless_coexistence` in :ref:`protocols`. +Added: + +* A page on :ref:`ug_wireless_coexistence` in :ref:`protocols`. +* Pages on :ref:`thread_device_types` and :ref:`thread_sed_ssed` to the :ref:`ug_thread` documentation. diff --git a/samples/matter/window_covering/README.rst b/samples/matter/window_covering/README.rst index 3af4dc86dbb..df231971682 100644 --- a/samples/matter/window_covering/README.rst +++ b/samples/matter/window_covering/README.rst @@ -45,9 +45,19 @@ SSED device type The SSED device type was created for the window covering devices to optimize the power usage of the device and communication pattern with the parent. -.. include:: /protocols/thread/overview/commissioning.rst - :start-after: thread_ssed_description_start - :end-before: thread_ssed_description_end +A Thread Synchronized Sleepy End Device (SSED) is synchronized with its parent router and uses the radio only at scheduled intervals, by using the :ref:`thread_ug_supported_features_csl` feature introduced as one of the `Thread 1.2 Base Features`_. +During those intervals, the device waits for the router to send it any data related to the desired device activity. +The SSED does require sending packets occasionally to keep synchronization with the router. +However, unlike a regular SED, an SSED does not actively communicate with the router by polling and goes into the idle mode between the scheduled activity periods. +If there is no application-related traffic for an extended period of time, the SSED sends a data poll request packet to synchronize with the parent. +Compared to a standard SED, the SSED features further reduce energy consumption of the device and generate less data traffic. + +.. figure:: ../../../doc/nrf/protocols/thread/overview/images/thread_sed_ssed_comparison.svg + :alt: Comparison of Thread SED and Thread SSED radio activity + + Comparison of Thread SED and Thread SSED radio activity + +See the :ref:`thread_sed_ssed` page for more information. Sample testing ==============