1 /* 2 * Copyright (c) 2020, 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 * @brief 32 * This file defines the OpenThread Link Metrics API. 33 */ 34 35 #ifndef LINK_METRICS_H_ 36 #define LINK_METRICS_H_ 37 38 #include <openthread/ip6.h> 39 #include <openthread/message.h> 40 #include <openthread/platform/radio.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-link-metrics 48 * 49 * @brief 50 * This module includes functions that control the Link Metrics protocol. 51 * 52 * @{ 53 */ 54 55 /** 56 * Represents the result (value) for a Link Metrics query. 57 */ 58 typedef struct otLinkMetricsValues 59 { 60 otLinkMetrics mMetrics; ///< Specifies which metrics values are present/included. 61 62 uint32_t mPduCountValue; ///< The value of Pdu Count. 63 uint8_t mLqiValue; ///< The value LQI. 64 uint8_t mLinkMarginValue; ///< The value of Link Margin. 65 int8_t mRssiValue; ///< The value of Rssi. 66 } otLinkMetricsValues; 67 68 /** 69 * Represents which frames are accounted in a Forward Tracking Series. 70 */ 71 typedef struct otLinkMetricsSeriesFlags 72 { 73 bool mLinkProbe : 1; ///< MLE Link Probe. 74 bool mMacData : 1; ///< MAC Data frame. 75 bool mMacDataRequest : 1; ///< MAC Data Request. 76 bool mMacAck : 1; ///< MAC Ack. 77 } otLinkMetricsSeriesFlags; 78 79 /** 80 * Enhanced-ACK Flags. 81 * 82 * These are used in Enhanced-ACK Based Probing to indicate whether to register or clear the probing. 83 */ 84 typedef enum otLinkMetricsEnhAckFlags 85 { 86 OT_LINK_METRICS_ENH_ACK_CLEAR = 0, ///< Clear. 87 OT_LINK_METRICS_ENH_ACK_REGISTER = 1, ///< Register. 88 } otLinkMetricsEnhAckFlags; 89 90 /** 91 * Link Metrics Status values. 92 */ 93 typedef enum otLinkMetricsStatus 94 { 95 OT_LINK_METRICS_STATUS_SUCCESS = 0, 96 OT_LINK_METRICS_STATUS_CANNOT_SUPPORT_NEW_SERIES = 1, 97 OT_LINK_METRICS_STATUS_SERIESID_ALREADY_REGISTERED = 2, 98 OT_LINK_METRICS_STATUS_SERIESID_NOT_RECOGNIZED = 3, 99 OT_LINK_METRICS_STATUS_NO_MATCHING_FRAMES_RECEIVED = 4, 100 OT_LINK_METRICS_STATUS_OTHER_ERROR = 254, 101 } otLinkMetricsStatus; 102 103 /** 104 * Pointer is called when a Link Metrics report is received. 105 * 106 * @param[in] aSource A pointer to the source address. 107 * @param[in] aMetricsValues A pointer to the Link Metrics values (the query result). 108 * @param[in] aStatus The status code in the report (only useful when @p aMetricsValues is NULL). 109 * @param[in] aContext A pointer to application-specific context. 110 */ 111 typedef void (*otLinkMetricsReportCallback)(const otIp6Address *aSource, 112 const otLinkMetricsValues *aMetricsValues, 113 otLinkMetricsStatus aStatus, 114 void *aContext); 115 /** 116 * Pointer is called when a Link Metrics Management Response is received. 117 * 118 * @param[in] aSource A pointer to the source address. 119 * @param[in] aStatus The status code in the response. 120 * @param[in] aContext A pointer to application-specific context. 121 */ 122 typedef void (*otLinkMetricsMgmtResponseCallback)(const otIp6Address *aSource, 123 otLinkMetricsStatus aStatus, 124 void *aContext); 125 126 /** 127 * Pointer is called when Enh-ACK Probing IE is received. 128 * 129 * @param[in] aShortAddress The Mac short address of the Probing Subject. 130 * @param[in] aExtAddress A pointer to the Mac extended address of the Probing Subject. 131 * @param[in] aMetricsValues A pointer to the Link Metrics values obtained from the IE. 132 * @param[in] aContext A pointer to application-specific context. 133 */ 134 typedef void (*otLinkMetricsEnhAckProbingIeReportCallback)(otShortAddress aShortAddress, 135 const otExtAddress *aExtAddress, 136 const otLinkMetricsValues *aMetricsValues, 137 void *aContext); 138 139 /** 140 * Sends an MLE Data Request to query Link Metrics. 141 * 142 * It could be either Single Probe or Forward Tracking Series. 143 * 144 * @param[in] aInstance A pointer to an OpenThread instance. 145 * @param[in] aDestination A pointer to the destination address. 146 * @param[in] aSeriesId The Series ID to query about, 0 for Single Probe. 147 * @param[in] aLinkMetricsFlags A pointer to flags specifying what metrics to query. 148 * @param[in] aCallback A pointer to a function that is called when Link Metrics report is received. 149 * @param[in] aCallbackContext A pointer to application-specific context. 150 * 151 * @retval OT_ERROR_NONE Successfully sent a Link Metrics query message. 152 * @retval OT_ERROR_NO_BUFS Insufficient buffers to generate the MLE Data Request message. 153 * @retval OT_ERROR_UNKNOWN_NEIGHBOR @p aDestination is not link-local or the neighbor is not found. 154 * @retval OT_ERROR_NOT_CAPABLE The neighbor is not a Thread 1.2 device and does not support Link Metrics. 155 */ 156 otError otLinkMetricsQuery(otInstance *aInstance, 157 const otIp6Address *aDestination, 158 uint8_t aSeriesId, 159 const otLinkMetrics *aLinkMetricsFlags, 160 otLinkMetricsReportCallback aCallback, 161 void *aCallbackContext); 162 163 /** 164 * Sends an MLE Link Metrics Management Request to configure or clear a Forward Tracking Series. 165 * 166 * @param[in] aInstance A pointer to an OpenThread instance. 167 * @param[in] aDestination A pointer to the destination address. 168 * @param[in] aSeriesId The Series ID to operate with. 169 * @param[in] aSeriesFlags The Series Flags that specifies which frames are to be accounted. 170 * @param[in] aLinkMetricsFlags A pointer to flags specifying what metrics to query. Should be `NULL` when 171 * `aSeriesFlags` is `0`. 172 * @param[in] aCallback A pointer to a function that is called when Link Metrics Management Response is 173 * received. 174 * @param[in] aCallbackContext A pointer to application-specific context. 175 * 176 * @retval OT_ERROR_NONE Successfully sent a Link Metrics Management Request message. 177 * @retval OT_ERROR_NO_BUFS Insufficient buffers to generate the MLE Link Metrics Management Request message. 178 * @retval OT_ERROR_INVALID_ARGS @p aSeriesId is not within the valid range. 179 * @retval OT_ERROR_UNKNOWN_NEIGHBOR @p aDestination is not link-local or the neighbor is not found. 180 * @retval OT_ERROR_NOT_CAPABLE The neighbor is not a Thread 1.2 device and does not support Link Metrics. 181 */ 182 otError otLinkMetricsConfigForwardTrackingSeries(otInstance *aInstance, 183 const otIp6Address *aDestination, 184 uint8_t aSeriesId, 185 otLinkMetricsSeriesFlags aSeriesFlags, 186 const otLinkMetrics *aLinkMetricsFlags, 187 otLinkMetricsMgmtResponseCallback aCallback, 188 void *aCallbackContext); 189 190 /** 191 * Sends an MLE Link Metrics Management Request to configure/clear an Enhanced-ACK Based Probing. 192 * This functionality requires OT_LINK_METRICS_INITIATOR feature enabled. 193 * 194 * @param[in] aInstance A pointer to an OpenThread instance. 195 * @param[in] aDestination A pointer to the destination address. 196 * @param[in] aEnhAckFlags Enh-ACK Flags to indicate whether to register or clear the probing. `0` to clear and 197 * `1` to register. Other values are reserved. 198 * @param[in] aLinkMetricsFlags A pointer to flags specifying what metrics to query. Should be `NULL` when 199 * `aEnhAckFlags` is `0`. 200 * @param[in] aCallback A pointer to a function that is called when an Enhanced Ack with Link Metrics is 201 * received. 202 * @param[in] aCallbackContext A pointer to application-specific context. 203 * 204 * @retval OT_ERROR_NONE Successfully sent a Link Metrics Management Request message. 205 * @retval OT_ERROR_NO_BUFS Insufficient buffers to generate the MLE Link Metrics Management Request message. 206 * @retval OT_ERROR_INVALID_ARGS @p aEnhAckFlags is not a valid value or @p aLinkMetricsFlags isn't correct. 207 * @retval OT_ERROR_UNKNOWN_NEIGHBOR @p aDestination is not link-local or the neighbor is not found. 208 * @retval OT_ERROR_NOT_CAPABLE The neighbor is not a Thread 1.2 device and does not support Link Metrics. 209 */ 210 otError otLinkMetricsConfigEnhAckProbing(otInstance *aInstance, 211 const otIp6Address *aDestination, 212 otLinkMetricsEnhAckFlags aEnhAckFlags, 213 const otLinkMetrics *aLinkMetricsFlags, 214 otLinkMetricsMgmtResponseCallback aCallback, 215 void *aCallbackContext, 216 otLinkMetricsEnhAckProbingIeReportCallback aEnhAckCallback, 217 void *aEnhAckCallbackContext); 218 219 /** 220 * Sends an MLE Link Probe message. 221 * 222 * @param[in] aInstance A pointer to an OpenThread instance. 223 * @param[in] aDestination A pointer to the destination address. 224 * @param[in] aSeriesId The Series ID [1, 254] which the Probe message aims at. 225 * @param[in] aLength The length of the data payload in Link Probe TLV, [0, 64] (per Thread 1.2 spec, 4.4.37). 226 * 227 * @retval OT_ERROR_NONE Successfully sent a Link Probe message. 228 * @retval OT_ERROR_NO_BUFS Insufficient buffers to generate the MLE Link Probe message. 229 * @retval OT_ERROR_INVALID_ARGS @p aSeriesId or @p aLength is not within the valid range. 230 * @retval OT_ERROR_UNKNOWN_NEIGHBOR @p aDestination is not link-local or the neighbor is not found. 231 * @retval OT_ERROR_NOT_CAPABLE The neighbor is not a Thread 1.2 device and does not support Link Metrics. 232 */ 233 otError otLinkMetricsSendLinkProbe(otInstance *aInstance, 234 const otIp6Address *aDestination, 235 uint8_t aSeriesId, 236 uint8_t aLength); 237 238 /** 239 * If Link Metrics Manager is enabled. 240 * 241 * @param[in] aInstance A pointer to an OpenThread instance. 242 * 243 * @retval TRUE Link Metrics Manager is enabled. 244 * @retval FALSE Link Metrics Manager is not enabled. 245 */ 246 bool otLinkMetricsManagerIsEnabled(otInstance *aInstance); 247 248 /** 249 * Enable or disable Link Metrics Manager. 250 * 251 * @param[in] aInstance A pointer to an OpenThread instance. 252 * @param[in] aEnable A boolean indicating to enable or disable. 253 */ 254 void otLinkMetricsManagerSetEnabled(otInstance *aInstance, bool aEnable); 255 256 /** 257 * Get Link Metrics data of a neighbor by its extended address. 258 * 259 * @param[in] aInstance A pointer to an OpenThread instance. 260 * @param[in] aExtAddress A pointer to the Mac extended address of the Probing Subject. 261 * @param[out] aLinkMetricsValues A pointer to the Link Metrics values of the subject. 262 * 263 * @retval OT_ERROR_NONE Successfully got the Link Metrics data. 264 * @retval OT_ERROR_INVALID_ARGS The arguments are invalid. 265 * @retval OT_ERROR_NOT_FOUND No neighbor with the given extended address is found. 266 */ 267 otError otLinkMetricsManagerGetMetricsValueByExtAddr(otInstance *aInstance, 268 const otExtAddress *aExtAddress, 269 otLinkMetricsValues *aLinkMetricsValues); 270 271 /** 272 * @} 273 */ 274 275 #ifdef __cplusplus 276 } // extern "C" 277 #endif 278 279 #endif // LINK_METRICS_H_ 280