1 /* 2 * Copyright (c) 2019, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file includes compile-time configurations for Parent Search. 32 */ 33 34 #ifndef CONFIG_PARENT_SEARCH_H_ 35 #define CONFIG_PARENT_SEARCH_H_ 36 37 /** 38 * @addtogroup config-parent-search 39 * 40 * @brief 41 * This module includes configuration variables for Parent Search. 42 * 43 * @{ 44 */ 45 46 /** 47 * @def OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE 48 * 49 * Define as 1 to enable the periodic parent search feature. 50 * 51 * 52 * When this feature is enabled, an end device/child (while staying attached) periodically searches for a potentially 53 * better parent and switches parents if a better one is found. 54 * 55 * The parent search mechanism depends on whether the device is an FTD child or an MTD child. 56 * 57 * FTD Child 58 * 59 * - An FTD child receives and processes MLE Advertisements from neighboring routers. It uses this information to track 60 * the one-way link quality to each, which is later used to compare and select potential new parents. 61 * - Every `OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL` seconds, an FTD child tries to select a better parent. 62 * The FTD child checks the list of neighboring routers and the tracked link quality information. A new parent is 63 * selected only if its average RSS exceeds the current parent's RSS by a margin specified by the configuration 64 * `OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN` configuration. 65 * - If the attach attempt to the selected router fails (e.g., the router already has the maximum number of children it 66 * can support), the FTD child ensures that the same router cannot be selected again until a "reselect timeout" 67 * expires. This avoids repeated attempts to the same router. This timeout is specified by the configuration 68 * `OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT`. 69 * 70 * MTD Child 71 * 72 * - Every `OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL` seconds, an MTD child checks its average RSS to its 73 * current parent. The child starts a parent search process only if the average RSS is below 74 * `OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD`. 75 * - This ensures that an MTD child already attached to a parent with good link quality does not waste energy 76 * searching for better parents. 77 * - The MTD child sends an MLE Parent Request to discover possible new parents. Because this process can be 78 * power-consuming (the child needs to stay in RX mode to collect parent responses), and to limit its impact on 79 * battery-powered devices, after a parent search is triggered on an MTD, the MTD child does not trigger another 80 * one before the specified backoff interval (`OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL`) expires. 81 * 82 * This feature is enabled by default on FTD builds. It is recommended that it also be enabled on MTD builds. This may 83 * require the platform integrator (device vendor) to select appropriate configuration values for this feature, 84 * particularly `OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL`, which can impact how often a (battery-powered) 85 * sleepy child may search for a parent, taking into account its impact on the device's battery life. 86 */ 87 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE 88 #define OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE OPENTHREAD_FTD 89 #endif 90 91 /** 92 * @def OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL 93 * 94 * Specifies the interval in seconds for a child to check the trigger condition to perform a parent search. 95 * 96 * Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`). 97 */ 98 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL 99 #define OPENTHREAD_CONFIG_PARENT_SEARCH_CHECK_INTERVAL (9 * 60) 100 #endif 101 102 /** 103 * @def OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL 104 * 105 * Specifies the backoff interval in seconds for a child to not perform a parent search after triggering one. This is 106 * used when device is an MTD child. 107 * 108 * Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`). 109 */ 110 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL 111 #define OPENTHREAD_CONFIG_PARENT_SEARCH_BACKOFF_INTERVAL (10 * 60 * 60) 112 #endif 113 114 /** 115 * @def OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD 116 * 117 * Specifies the RSS threshold used to trigger a parent search. 118 * 119 * Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`). 120 */ 121 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD 122 #define OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_THRESHOLD -65 123 #endif 124 125 /** 126 * @def OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT 127 * 128 * Specifies parent reselect timeout duration in seconds used on FTD child devices. When an attach attempt to a 129 * neighboring router selected as a potential new parent fails, the same router cannot be selected again until this 130 * timeout expires. 131 * 132 * Applicable only if periodic parent search feature is enabled (see `OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE`). 133 */ 134 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT 135 #define OPENTHREAD_CONFIG_PARENT_SEARCH_RESELECT_TIMEOUT (90 * 60) 136 #endif 137 138 /** 139 * @def OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN 140 * 141 * Specifies the RSS margin over the current parent RSS for allowing selection of a neighboring router as a potential 142 * new parent to attach to. Used on FTD child devices. 143 */ 144 #ifndef OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN 145 #define OPENTHREAD_CONFIG_PARENT_SEARCH_RSS_MARGIN 7 146 #endif 147 148 /* 149 * @} 150 */ 151 152 #endif // CONFIG_PARENT_SEARCH_H_ 153