src/core/config/parent_search.h - third_party/openthread - Git at Google

 /*
  *  Copyright (c) 2019, The OpenThread Authors.
  *  All rights reserved.
  *
  *  Redistribution and use in source and binary forms, with or without
  *  modification, are permitted provided that the following conditions are met:
  *  1. Redistributions of source code must retain the above copyright
  *     notice, this list of conditions and the following disclaimer.
  *  2. Redistributions in binary form must reproduce the above copyright
  *     notice, this list of conditions and the following disclaimer in the
  *     documentation and/or other materials provided with the distribution.
  *  3. Neither the name of the copyright holder nor the
  *     names of its contributors may be used to endorse or promote products
  *     derived from this software without specific prior written permission.
  *
  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  *  POSSIBILITY OF SUCH DAMAGE.
  */

 /**
  * @file
  *   This file includes compile-time configurations for Parent Search.
  */

 #ifndef OT_CORE_CONFIG_PARENT_SEARCH_H_
 #define OT_CORE_CONFIG_PARENT_SEARCH_H_

 /**
  * @addtogroup config-parent-search
  *
  * @brief
  *   This module includes configuration variables for Parent Search.
  *
  * @{
  */

 /**
  * @def OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE
  *
  * Define as 1 to enable the periodic parent search feature.
  *
  *
  * When this feature is enabled, an end device/child (while staying attached) periodically searches for a potentially
  * better parent and switches parents if a better one is found.
  *
  * The parent search mechanism depends on whether the device is an FTD child or an MTD child.
  *
  * FTD Child
  *
  * - An FTD child receives and processes MLE Advertisements from neighboring routers. It uses this information to track
  *   the one-way link quality to each, which is later used to compare and select potential new parents.
  * - Every `OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL` seconds, an FTD child tries to select a better parent.
  *   The FTD child checks the list of neighboring routers and the tracked link quality information. A new parent is
  *   selected only if its average RSS exceeds the current parent's RSS by a margin specified by the configuration
  *  `OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN` configuration.
  * - If the attach attempt to the selected router fails (e.g., the router already has the maximum number of children it
  *   can support), the FTD child ensures that the same router cannot be selected again until a "reselect timeout"
  *   expires. This avoids repeated attempts to the same router. This timeout is specified by the configuration
  *   `OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT`.
  *
  * MTD Child
  *
  * - Every `OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL` seconds, an MTD child checks its average RSS to its
  *   current parent. The child starts a parent search process only if the average RSS is below
  *   `OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD`.
  * - This ensures that an MTD child already attached to a parent with good link quality does not waste energy
  *   searching for better parents.
  * - The MTD child sends an MLE Parent Request to discover possible new parents. Because this process can be
  *   power-consuming (the child needs to stay in RX mode to collect parent responses), and to limit its impact on
  *   battery-powered devices, after a parent search is triggered on an MTD, the MTD child does not trigger another
  *   one before the specified backoff interval (`OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL`) expires.
  *
  * This feature is enabled by default on FTD builds. It is recommended that it also be enabled on MTD builds. This may
  * require the platform integrator (device vendor) to select appropriate configuration values for this feature,
  * particularly `OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL`, which can impact how often a (battery-powered)
  * sleepy child may search for a parent, taking into account its impact on the device's battery life.
  */
 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE
 #define OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE OPENTHREAD_FTD
 #endif

 /**
  * @def OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL
  *
  * Specifies the interval in seconds for a child to check the trigger condition to perform a parent search.
  *
  * Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`).
  */
 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL
 #define OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL (9 * 60)
 #endif

 /**
  * @def OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL
  *
  * Specifies the backoff interval in seconds for a child to not perform a parent search after triggering one. This is
  * used when device is an MTD child.
  *
  * Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`).
  */
 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL
 #define OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL (10 * 60 * 60)
 #endif

 /**
  * @def OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD
  *
  * Specifies the RSS threshold used to trigger a parent search.
  *
  * Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`).
  */
 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD
 #define OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD -65
 #endif

 /**
  * @def OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT
  *
  * Specifies parent reselect timeout duration in seconds used on FTD child devices. When an attach attempt to a
  * neighboring router selected as a potential new parent fails, the same router cannot be selected again until this
  * timeout expires.
  *
  * Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`).
  */
 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT
 #define OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT (90 * 60)
 #endif

 /**
  * @def OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN
  *
  * Specifies the RSS margin over the current parent RSS for allowing selection of a neighboring router as a potential
  * new parent to attach to. Used on FTD child devices.
  */
 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN
 #define OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN 7
 #endif

 /*
  * @}
  */

 #endif // OT_CORE_CONFIG_PARENT_SEARCH_H_
	/*
	* Copyright (c) 2019, The OpenThread Authors.
	* All rights reserved.
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions are met:
	* 1. Redistributions of source code must retain the above copyright
	* notice, this list of conditions and the following disclaimer.
	* 2. Redistributions in binary form must reproduce the above copyright
	* notice, this list of conditions and the following disclaimer in the
	* documentation and/or other materials provided with the distribution.
	* 3. Neither the name of the copyright holder nor the
	* names of its contributors may be used to endorse or promote products
	* derived from this software without specific prior written permission.
	*
	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
	* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
	* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	* POSSIBILITY OF SUCH DAMAGE.
	*/

	/**
	* @file
	* This file includes compile-time configurations for Parent Search.
	*/

	#ifndef OT_CORE_CONFIG_PARENT_SEARCH_H_
	#define OT_CORE_CONFIG_PARENT_SEARCH_H_

	/**
	* @addtogroup config-parent-search
	*
	* @brief
	* This module includes configuration variables for Parent Search.
	*
	* @{
	*/

	/**
	* @def OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE
	*
	* Define as 1 to enable the periodic parent search feature.
	*
	*
	* When this feature is enabled, an end device/child (while staying attached) periodically searches for a potentially
	* better parent and switches parents if a better one is found.
	*
	* The parent search mechanism depends on whether the device is an FTD child or an MTD child.
	*
	* FTD Child
	*
	* - An FTD child receives and processes MLE Advertisements from neighboring routers. It uses this information to track
	* the one-way link quality to each, which is later used to compare and select potential new parents.
	* - Every `OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL` seconds, an FTD child tries to select a better parent.
	* The FTD child checks the list of neighboring routers and the tracked link quality information. A new parent is
	* selected only if its average RSS exceeds the current parent's RSS by a margin specified by the configuration
	* `OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN` configuration.
	* - If the attach attempt to the selected router fails (e.g., the router already has the maximum number of children it
	* can support), the FTD child ensures that the same router cannot be selected again until a "reselect timeout"
	* expires. This avoids repeated attempts to the same router. This timeout is specified by the configuration
	* `OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT`.
	*
	* MTD Child
	*
	* - Every `OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL` seconds, an MTD child checks its average RSS to its
	* current parent. The child starts a parent search process only if the average RSS is below
	* `OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD`.
	* - This ensures that an MTD child already attached to a parent with good link quality does not waste energy
	* searching for better parents.
	* - The MTD child sends an MLE Parent Request to discover possible new parents. Because this process can be
	* power-consuming (the child needs to stay in RX mode to collect parent responses), and to limit its impact on
	* battery-powered devices, after a parent search is triggered on an MTD, the MTD child does not trigger another
	* one before the specified backoff interval (`OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL`) expires.
	*
	* This feature is enabled by default on FTD builds. It is recommended that it also be enabled on MTD builds. This may
	* require the platform integrator (device vendor) to select appropriate configuration values for this feature,
	* particularly `OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL`, which can impact how often a (battery-powered)
	* sleepy child may search for a parent, taking into account its impact on the device's battery life.
	*/
	#ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE
	#define OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE OPENTHREAD_FTD
	#endif

	/**
	* @def OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL
	*
	* Specifies the interval in seconds for a child to check the trigger condition to perform a parent search.
	*
	* Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`).
	*/
	#ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL
	#define OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL (9 * 60)
	#endif

	/**
	* @def OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL
	*
	* Specifies the backoff interval in seconds for a child to not perform a parent search after triggering one. This is
	* used when device is an MTD child.
	*
	* Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`).
	*/
	#ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL
	#define OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL (10 * 60 * 60)
	#endif

	/**
	* @def OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD
	*
	* Specifies the RSS threshold used to trigger a parent search.
	*
	* Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`).
	*/
	#ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD
	#define OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD -65
	#endif

	/**
	* @def OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT
	*
	* Specifies parent reselect timeout duration in seconds used on FTD child devices. When an attach attempt to a
	* neighboring router selected as a potential new parent fails, the same router cannot be selected again until this
	* timeout expires.
	*
	* Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`).
	*/
	#ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT
	#define OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT (90 * 60)
	#endif

	/**
	* @def OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN
	*
	* Specifies the RSS margin over the current parent RSS for allowing selection of a neighboring router as a potential
	* new parent to attach to. Used on FTD child devices.
	*/
	#ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN
	#define OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN 7
	#endif

	/*
	* @}
	*/

	#endif // OT_CORE_CONFIG_PARENT_SEARCH_H_