1 /* 2 * Copyright (c) 2016, 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 raw OpenThread IEEE 802.15.4 Link Layer API. 33 */ 34 35 #ifndef OPENTHREAD_LINK_RAW_H_ 36 #define OPENTHREAD_LINK_RAW_H_ 37 38 #include <openthread/platform/radio.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @addtogroup api-link-raw 46 * 47 * @brief 48 * This module includes functions that control the raw link-layer configuration. 49 * 50 * @{ 51 */ 52 53 /** 54 * Pointer on receipt of a IEEE 802.15.4 frame. 55 * 56 * @param[in] aInstance A pointer to an OpenThread instance. 57 * @param[in] aFrame A pointer to the received frame or NULL if the receive operation was aborted. 58 * @param[in] aError OT_ERROR_NONE when successfully received a frame. 59 * OT_ERROR_ABORT when reception was aborted and a frame was not received. 60 */ 61 typedef void (*otLinkRawReceiveDone)(otInstance *aInstance, otRadioFrame *aFrame, otError aError); 62 63 /** 64 * Enables/disables the raw link-layer. 65 * 66 * @param[in] aInstance A pointer to an OpenThread instance. 67 * @param[in] aCallback A pointer to a function called on receipt of a IEEE 802.15.4 frame. NULL to disable the 68 * raw-link layer. 69 * 70 * @retval OT_ERROR_FAILED The radio could not be enabled/disabled. 71 * @retval OT_ERROR_INVALID_STATE If the OpenThread IPv6 interface is already enabled. 72 * @retval OT_ERROR_NONE If the enable state was successfully set. 73 */ 74 otError otLinkRawSetReceiveDone(otInstance *aInstance, otLinkRawReceiveDone aCallback); 75 76 /** 77 * Indicates whether or not the raw link-layer is enabled. 78 * 79 * @param[in] aInstance A pointer to an OpenThread instance. 80 * 81 * @retval true The raw link-layer is enabled. 82 * @retval false The raw link-layer is disabled. 83 */ 84 bool otLinkRawIsEnabled(otInstance *aInstance); 85 86 /** 87 * Gets the status of promiscuous mode. 88 * 89 * @param[in] aInstance A pointer to an OpenThread instance. 90 * 91 * @retval true Promiscuous mode is enabled. 92 * @retval false Promiscuous mode is disabled. 93 */ 94 bool otLinkRawGetPromiscuous(otInstance *aInstance); 95 96 /** 97 * Enables or disables promiscuous mode. 98 * 99 * @param[in] aInstance A pointer to an OpenThread instance. 100 * @param[in] aEnable A value to enable or disable promiscuous mode. 101 * 102 * @retval OT_ERROR_NONE If successful. 103 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 104 */ 105 otError otLinkRawSetPromiscuous(otInstance *aInstance, bool aEnable); 106 107 /** 108 * Set the Short Address for address filtering. 109 * 110 * @param[in] aInstance A pointer to an OpenThread instance. 111 * @param[in] aShortAddress The IEEE 802.15.4 Short Address. 112 * 113 * @retval OT_ERROR_NONE If successful. 114 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 115 */ 116 otError otLinkRawSetShortAddress(otInstance *aInstance, uint16_t aShortAddress); 117 118 /** 119 * Set the alternate short address. 120 * 121 * This is an optional API. Support for this is indicated by including the capability `OT_RADIO_CAPS_ALT_SHORT_ADDR` in 122 * `otLinkRawGetCaps()`. 123 * 124 * When supported, the radio will accept received frames destined to the specified alternate short address in addition 125 * to the short address provided in `otLinkRawSetShortAddress()`. 126 * 127 * The @p aShortAddress can be set to `OT_RADIO_INVALID_SHORT_ADDR` (0xfffe) to clear any previously set alternate 128 * short address. 129 * 130 * @param[in] aInstance The OpenThread instance structure. 131 * @param[in] aShortAddress The alternate short address. `OT_RADIO_INVALID_SHORT_ADDR` to clear. 132 * 133 * @retval OT_ERROR_NONE Successfully set the alternate short address. 134 * @retval OT_ERROR_INVALID_STATE The raw link-layer is not enabled. 135 */ 136 otError otLinkRawSetAlternateShortAddress(otInstance *aInstance, otShortAddress aShortAddress); 137 138 /** 139 * Transition the radio from Receive to Sleep. 140 * Turn off the radio. 141 * 142 * @param[in] aInstance A pointer to an OpenThread instance. 143 * 144 * @retval OT_ERROR_NONE Successfully transitioned to Sleep. 145 * @retval OT_ERROR_BUSY The radio was transmitting 146 * @retval OT_ERROR_INVALID_STATE The radio was disabled 147 */ 148 otError otLinkRawSleep(otInstance *aInstance); 149 150 /** 151 * Transitioning the radio from Sleep to Receive. 152 * Turn on the radio. 153 * 154 * @param[in] aInstance A pointer to an OpenThread instance. 155 * 156 * @retval OT_ERROR_NONE Successfully transitioned to Receive. 157 * @retval OT_ERROR_INVALID_STATE The radio was disabled or transmitting. 158 */ 159 otError otLinkRawReceive(otInstance *aInstance); 160 161 /** 162 * The radio transitions from Transmit to Receive. 163 * Returns a pointer to the transmit buffer. 164 * 165 * The caller forms the IEEE 802.15.4 frame in this buffer then calls otLinkRawTransmit() 166 * to request transmission. 167 * 168 * @param[in] aInstance A pointer to an OpenThread instance. 169 * 170 * @returns A pointer to the transmit buffer or NULL if the raw link-layer isn't enabled. 171 */ 172 otRadioFrame *otLinkRawGetTransmitBuffer(otInstance *aInstance); 173 174 /** 175 * Pointer on receipt of a IEEE 802.15.4 frame. 176 * 177 * @param[in] aInstance A pointer to an OpenThread instance. 178 * @param[in] aFrame A pointer to the frame that was transmitted. 179 * @param[in] aAckFrame A pointer to the ACK frame. 180 * @param[in] aError OT_ERROR_NONE when the frame was transmitted. 181 * OT_ERROR_NO_ACK when the frame was transmitted but no ACK was received 182 * OT_ERROR_CHANNEL_ACCESS_FAILURE when the transmission could not take place 183 due to activity on the channel. 184 * OT_ERROR_ABORT when transmission was aborted for other reasons. 185 */ 186 typedef void (*otLinkRawTransmitDone)(otInstance *aInstance, 187 otRadioFrame *aFrame, 188 otRadioFrame *aAckFrame, 189 otError aError); 190 191 /** 192 * Begins the transmit sequence on the radio. 193 * 194 * The caller must form the IEEE 802.15.4 frame in the buffer provided by otLinkRawGetTransmitBuffer() before 195 * requesting transmission. The channel and transmit power are also included in the otRadioFrame structure. 196 * 197 * The transmit sequence consists of: 198 * 1. Transitioning the radio to Transmit from Receive. 199 * 2. Transmits the PSDU on the given channel and at the given transmit power. 200 * 201 * @param[in] aInstance A pointer to an OpenThread instance. 202 * @param[in] aCallback A pointer to a function called on completion of the transmission. 203 * 204 * @retval OT_ERROR_NONE Successfully transitioned to Transmit. 205 * @retval OT_ERROR_INVALID_STATE The radio was not in the Receive state. 206 */ 207 otError otLinkRawTransmit(otInstance *aInstance, otLinkRawTransmitDone aCallback); 208 209 /** 210 * Get the most recent RSSI measurement. 211 * 212 * @param[in] aInstance A pointer to an OpenThread instance. 213 * 214 * @returns The RSSI in dBm when it is valid. 127 when RSSI is invalid. 215 */ 216 int8_t otLinkRawGetRssi(otInstance *aInstance); 217 218 /** 219 * Get the radio capabilities. 220 * 221 * @param[in] aInstance A pointer to an OpenThread instance. 222 * 223 * @returns The radio capability bit vector. The stack enables or disables some functions based on this value. 224 */ 225 otRadioCaps otLinkRawGetCaps(otInstance *aInstance); 226 227 /** 228 * Pointer on receipt of a IEEE 802.15.4 frame. 229 * 230 * @param[in] aInstance A pointer to an OpenThread instance. 231 * @param[in] aEnergyScanMaxRssi The maximum RSSI encountered on the scanned channel. 232 */ 233 typedef void (*otLinkRawEnergyScanDone)(otInstance *aInstance, int8_t aEnergyScanMaxRssi); 234 235 /** 236 * Begins the energy scan sequence on the radio. 237 * 238 * @param[in] aInstance A pointer to an OpenThread instance. 239 * @param[in] aScanChannel The channel to perform the energy scan on. 240 * @param[in] aScanDuration The duration, in milliseconds, for the channel to be scanned. 241 * @param[in] aCallback A pointer to a function called on completion of a scanned channel. 242 * 243 * @retval OT_ERROR_NONE Successfully started scanning the channel. 244 * @retval OT_ERROR_BUSY The radio is performing energy scanning. 245 * @retval OT_ERROR_NOT_IMPLEMENTED The radio doesn't support energy scanning. 246 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 247 */ 248 otError otLinkRawEnergyScan(otInstance *aInstance, 249 uint8_t aScanChannel, 250 uint16_t aScanDuration, 251 otLinkRawEnergyScanDone aCallback); 252 253 /** 254 * Enable/Disable source match for frame pending. 255 * 256 * @param[in] aInstance A pointer to an OpenThread instance. 257 * @param[in] aEnable Enable/disable source match for frame pending. 258 * 259 * @retval OT_ERROR_NONE If successful. 260 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 261 */ 262 otError otLinkRawSrcMatchEnable(otInstance *aInstance, bool aEnable); 263 264 /** 265 * Adding short address to the source match table. 266 * 267 * @param[in] aInstance A pointer to an OpenThread instance. 268 * @param[in] aShortAddress The short address to be added. 269 * 270 * @retval OT_ERROR_NONE Successfully added short address to the source match table. 271 * @retval OT_ERROR_NO_BUFS No available entry in the source match table. 272 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 273 */ 274 otError otLinkRawSrcMatchAddShortEntry(otInstance *aInstance, uint16_t aShortAddress); 275 276 /** 277 * Adding extended address to the source match table. 278 * 279 * @param[in] aInstance A pointer to an OpenThread instance. 280 * @param[in] aExtAddress The extended address to be added. 281 * 282 * @retval OT_ERROR_NONE Successfully added extended address to the source match table. 283 * @retval OT_ERROR_NO_BUFS No available entry in the source match table. 284 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 285 */ 286 otError otLinkRawSrcMatchAddExtEntry(otInstance *aInstance, const otExtAddress *aExtAddress); 287 288 /** 289 * Removing short address to the source match table. 290 * 291 * @param[in] aInstance A pointer to an OpenThread instance. 292 * @param[in] aShortAddress The short address to be removed. 293 * 294 * @retval OT_ERROR_NONE Successfully removed short address from the source match table. 295 * @retval OT_ERROR_NO_ADDRESS The short address is not in source match table. 296 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 297 */ 298 otError otLinkRawSrcMatchClearShortEntry(otInstance *aInstance, uint16_t aShortAddress); 299 300 /** 301 * Removing extended address to the source match table of the radio. 302 * 303 * @param[in] aInstance A pointer to an OpenThread instance. 304 * @param[in] aExtAddress The extended address to be removed. 305 * 306 * @retval OT_ERROR_NONE Successfully removed the extended address from the source match table. 307 * @retval OT_ERROR_NO_ADDRESS The extended address is not in source match table. 308 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 309 */ 310 otError otLinkRawSrcMatchClearExtEntry(otInstance *aInstance, const otExtAddress *aExtAddress); 311 312 /** 313 * Removing all the short addresses from the source match table. 314 * 315 * @param[in] aInstance A pointer to an OpenThread instance. 316 * 317 * @retval OT_ERROR_NONE If successful. 318 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 319 */ 320 otError otLinkRawSrcMatchClearShortEntries(otInstance *aInstance); 321 322 /** 323 * Removing all the extended addresses from the source match table. 324 * 325 * @param[in] aInstance A pointer to an OpenThread instance. 326 * 327 * @retval OT_ERROR_NONE If successful. 328 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 329 */ 330 otError otLinkRawSrcMatchClearExtEntries(otInstance *aInstance); 331 332 /** 333 * Update MAC keys and key index. 334 * 335 * @param[in] aInstance A pointer to an OpenThread instance. 336 * @param[in] aKeyIdMode The key ID mode. 337 * @param[in] aKeyId The key index. 338 * @param[in] aPrevKey The previous MAC key. 339 * @param[in] aCurrKey The current MAC key. 340 * @param[in] aNextKey The next MAC key. 341 * 342 * @retval OT_ERROR_NONE If successful. 343 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 344 */ 345 otError otLinkRawSetMacKey(otInstance *aInstance, 346 uint8_t aKeyIdMode, 347 uint8_t aKeyId, 348 const otMacKey *aPrevKey, 349 const otMacKey *aCurrKey, 350 const otMacKey *aNextKey); 351 352 /** 353 * Sets the current MAC frame counter value. 354 * 355 * Always sets the MAC counter to the new given value @p aMacFrameCounter independent of the current 356 * value. 357 * 358 * @param[in] aInstance A pointer to an OpenThread instance. 359 * @param[in] aMacFrameCounter The MAC frame counter value. 360 * 361 * @retval OT_ERROR_NONE If successful. 362 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 363 */ 364 otError otLinkRawSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCounter); 365 366 /** 367 * Sets the current MAC frame counter value only if the new value is larger than the current one. 368 * 369 * @param[in] aInstance A pointer to an OpenThread instance. 370 * @param[in] aMacFrameCounter The MAC frame counter value. 371 * 372 * @retval OT_ERROR_NONE If successful. 373 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 374 */ 375 otError otLinkRawSetMacFrameCounterIfLarger(otInstance *aInstance, uint32_t aMacFrameCounter); 376 377 /** 378 * Get current platform time (64bits width) of the radio chip. 379 * 380 * @param[in] aInstance A pointer to an OpenThread instance. 381 * 382 * @returns The current radio time in microseconds. 383 */ 384 uint64_t otLinkRawGetRadioTime(otInstance *aInstance); 385 386 /** 387 * @} 388 */ 389 390 #ifdef __cplusplus 391 } // extern "C" 392 #endif 393 394 #endif // OPENTHREAD_LINK_RAW_H_ 395