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