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