1 /* 2 * Copyright (c) 2017, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions are met: 9 * 10 * 1. Redistributions of source code must retain the above copyright notice, this 11 * list of conditions and the following disclaimer. 12 * 13 * 2. Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 17 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 * IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE 24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31 * POSSIBILITY OF SUCH DAMAGE. 32 * 33 */ 34 35 /** 36 * @defgroup nrf_802154 802.15.4 radio driver 37 * @{ 38 * 39 */ 40 41 #ifndef NRF_802154_H_ 42 #define NRF_802154_H_ 43 44 #include <stdbool.h> 45 #include <stdint.h> 46 47 #include "nrf_802154_callouts.h" 48 #include "nrf_802154_config.h" 49 #include "nrf_802154_types.h" 50 #include "nrf_802154_common_utils.h" 51 52 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 53 #include "nrf_802154_irq_handlers.h" 54 #include "nrf_802154_sl_ant_div.h" 55 #endif // !NRF_802154_SERIALIZATION_HOST 56 57 #ifdef __cplusplus 58 extern "C" { 59 #endif 60 61 /** 62 * @brief Timestamp value indicating that the timestamp is inaccurate. 63 */ 64 #define NRF_802154_NO_TIMESTAMP 0 65 66 /** 67 * @brief Invalid delayed timeslot identifier. 68 */ 69 #define NRF_802154_RESERVED_INVALID_ID UINT32_MAX 70 71 /** 72 * @brief Reception window identifier reserved for immediate reception. 73 */ 74 #define NRF_802154_RESERVED_IMM_RX_WINDOW_ID (UINT32_MAX - 1) 75 76 /** 77 * @brief Upper bound for delayed reception window identifiers used by the application. 78 * 79 * All integers ranging from 0 to @ref NRF_802154_RESERVED_DRX_ID_UPPER_BOUND (inclusive) 80 * can be used by the application as identifiers of delayed reception windows. 81 */ 82 #define NRF_802154_RESERVED_DRX_ID_UPPER_BOUND (UINT32_MAX - 4) 83 84 /** 85 * @brief Maximum number of simultaneously pending notifications the driver can issue. 86 * 87 * This parameter allows to determine the correct size for structures that process notifications 88 * issued by the driver. It accumulates the maximum number of simultaneously pending notifications 89 * that can result from successfully received frames, disregardable notifications, all supported 90 * delayed operations and the latest requested immediate operation. 91 */ 92 #define NRF_802154_MAX_PENDING_NOTIFICATIONS \ 93 (NRF_802154_RX_BUFFERS + NRF_802154_MAX_DISREGARDABLE_NOTIFICATIONS + 4 + 1) 94 95 /** 96 * @brief Initializes the 802.15.4 driver. 97 * 98 * This function initializes the RADIO peripheral in the @ref RADIO_STATE_SLEEP state. 99 * 100 * @note This function is to be called once, before any other functions from this module. 101 * Only the functions setting the configuration can be called before this call. 102 */ 103 void nrf_802154_init(void); 104 105 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 106 /** 107 * @brief Deinitializes the 802.15.4 driver. 108 * 109 * This function deinitializes the RADIO peripheral and resets it to the default state. 110 */ 111 void nrf_802154_deinit(void); 112 #endif // !NRF_802154_SERIALIZATION_HOST 113 114 /** 115 * @brief Sets the channel on which the radio is to operate. 116 * 117 * @param[in] channel Channel number (11-26). 118 */ 119 void nrf_802154_channel_set(uint8_t channel); 120 121 /** 122 * @brief Gets the channel on which the radio operates. 123 * 124 * @returns Channel number (11-26). 125 */ 126 uint8_t nrf_802154_channel_get(void); 127 128 /** 129 * @brief Sets the transmit power. 130 * 131 * @note The driver recalculates the requested value to the nearest value accepted by the hardware. 132 * The calculation result is rounded up. 133 * 134 * @param[in] power Transmit power in dBm. 135 */ 136 void nrf_802154_tx_power_set(int8_t power); 137 138 /** 139 * @brief Gets the currently set transmit power. 140 * 141 * @returns Currently used real total transmit power, in dBm. 142 */ 143 int8_t nrf_802154_tx_power_get(void); 144 145 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 146 147 /** 148 * @brief Sets the antenna diversity rx mode. 149 * 150 * @note This function should not be called while reception or transmission are currently ongoing. 151 * 152 * @param[in] mode Antenna diversity rx mode to be set. 153 * 154 * @retval true Antenna diversity rx mode set successfully. 155 * @retval false Invalid mode passed as argument. 156 */ 157 bool nrf_802154_antenna_diversity_rx_mode_set(nrf_802154_sl_ant_div_mode_t mode); 158 159 /** 160 * @brief Gets current antenna diversity rx mode. 161 * 162 * @return Current antenna diversity mode for rx. 163 */ 164 nrf_802154_sl_ant_div_mode_t nrf_802154_antenna_diversity_rx_mode_get(void); 165 166 /** 167 * @brief Sets the antenna diversity tx mode. 168 * 169 * @note This function should not be called while reception or transmission are currently ongoing. 170 * @note NRF_802154_SL_ANT_DIV_MODE_AUTO is not supported for transmission. 171 * 172 * @param[in] mode Antenna diversity tx mode to be set. 173 * 174 * @retval true Antenna diversity tx mode set successfully. 175 * @retval false Invalid mode passed as argument. 176 */ 177 bool nrf_802154_antenna_diversity_tx_mode_set(nrf_802154_sl_ant_div_mode_t mode); 178 179 /** 180 * @brief Gets current antenna diversity tx mode. 181 * 182 * @return Current antenna diversity mode for tx. 183 */ 184 nrf_802154_sl_ant_div_mode_t nrf_802154_antenna_diversity_tx_mode_get(void); 185 186 /** 187 * @brief Manually selects the antenna to be used for rx. 188 * 189 * For antenna to be switched, antenna diversity rx mode needs 190 * to be @c NRF_802154_SL_ANT_DIV_MODE_MANUAL. Otherwise, antenna will 191 * be only switched after @c NRF_802154_SL_ANT_DIV_MODE_MANUAL is set. 192 * 193 * @param[in] antenna Antenna to be used. 194 * 195 * @retval true Antenna set successfully. 196 * @retval false Invalid antenna passed as argument. 197 */ 198 bool nrf_802154_antenna_diversity_rx_antenna_set(nrf_802154_sl_ant_div_antenna_t antenna); 199 200 /** 201 * @brief Gets antenna currently used for rx. 202 * 203 * @note The antenna read by this function is currently used rx antenna only if 204 * antenna diversity rx mode is set to @c NRF_802154_SL_ANT_DIV_MODE_MANUAL. Otherwise, 205 * currently used antenna may be different. 206 * 207 * @return Currently used antenna. 208 */ 209 nrf_802154_sl_ant_div_antenna_t nrf_802154_antenna_diversity_rx_antenna_get(void); 210 211 /** 212 * @brief Manually selects the antenna to be used for tx. 213 * 214 * For antenna to be switched, antenna diversity tx mode needs 215 * to be @c NRF_802154_SL_ANT_DIV_MODE_MANUAL. Otherwise, antenna will 216 * be only switched after @c NRF_802154_SL_ANT_DIV_MODE_MANUAL is set. 217 * 218 * @param[in] antenna Antenna to be used. 219 * 220 * @retval true Antenna set successfully. 221 * @retval false Invalid antenna passed as argument. 222 */ 223 bool nrf_802154_antenna_diversity_tx_antenna_set(nrf_802154_sl_ant_div_antenna_t antenna); 224 225 /** 226 * @brief Gets antenna currently used for tx. 227 * 228 * @note The antenna read by this function is currently used tx antenna only if 229 * antenna diversity tx mode is set to @c NRF_802154_SL_ANT_DIV_MODE_MANUAL. Otherwise, 230 * currently used antenna may be different. 231 * 232 * @return Currently used antenna. 233 */ 234 nrf_802154_sl_ant_div_antenna_t nrf_802154_antenna_diversity_tx_antenna_get(void); 235 236 /** 237 * @brief Gets which antenna was selected as best for the last reception. 238 * 239 * @note In three cases @c NRF_802154_SL_ANT_DIV_ANTENNA_NONE may be returned: 240 * - No frame was received yet. 241 * - Last frame was received with antenna diversity auto mode disabled. 242 * - RSSI measurements didn't have enough time to finish during last frame reception 243 * and it is unspecified which antenna was selected. 244 * 245 * @return Antenna selected during last successful reception in automatic mode. 246 */ 247 nrf_802154_sl_ant_div_antenna_t nrf_802154_antenna_diversity_last_rx_best_antenna_get(void); 248 249 /** 250 * @brief Sets antenna diversity configuration. 251 * 252 * @note If antenna diversity feature is to be used, this function must be called before 253 * @ref nrf_802154_antenna_diversity_init. 254 * 255 * @note This function must be called only once. 256 * 257 * @param[in] p_cfg Pointer to antenna diversity interface configuration. 258 */ 259 void nrf_802154_antenna_diversity_config_set(const nrf_802154_sl_ant_div_cfg_t * p_cfg); 260 261 /** 262 * @brief Gets the antenna diversity interface configuration. 263 * 264 * @param[out] p_cfg Antenna diversity interface configuration. 265 * 266 * @retval true The configuration was retrieved successfully. 267 * @retval false The configuration could not be retrieved. 268 */ 269 bool nrf_802154_antenna_diversity_config_get(nrf_802154_sl_ant_div_cfg_t * p_cfg); 270 271 /** 272 * @brief Initializes antenna diversity module. 273 * 274 * This function should be called before starting radio operations, but at any time 275 * after driver initialization. In order for it to succeed, antenna diversity interface 276 * configuration must be provided before it's called with 277 * @ref nrf_802154_antenna_diversity_config_set. Example usage: 278 * 279 * @code 280 * nrf_802154_init(); 281 * 282 * nrf_802154_sl_ant_div_cfg_t cfg = 283 * { 284 * // Set the configuration parameters accordingly 285 * }; 286 * 287 * nrf_802154_antenna_config_set(&cfg); 288 * nrf_802154_antenna_diversity_init(); 289 * 290 * // At any later time 291 * nrf_802154_receive(); 292 * @endcode 293 * 294 * @retval true Initialization was successful. 295 * @retval false Initialization could not be performed due to unconfigured interface. 296 */ 297 bool nrf_802154_antenna_diversity_init(void); 298 299 /** 300 * @brief Handles TIMER IRQ of the antenna diversity interface. 301 * 302 * This function should be called when the timer instance provided to the antenna diversity 303 * interface reports an interrupt. 304 */ 305 void nrf_802154_antenna_diversity_timer_irq_handler(void); 306 307 #endif // !NRF_802154_SERIALIZATION_HOST 308 309 /** 310 * @brief Gets the current time. 311 * 312 * The time returned by this function is to be used to calculate timing parameters for 313 * @ref nrf_802154_transmit_raw_at and @ref nrf_802154_receive_at functions. 314 * 315 * @returns Current time in microseconds. 316 */ 317 uint64_t nrf_802154_time_get(void); 318 319 /** 320 * @defgroup nrf_802154_addresses Setting addresses and PAN ID of the device 321 * @{ 322 */ 323 324 /** 325 * @brief Sets the PAN ID used by the device. 326 * 327 * @param[in] p_pan_id Pointer to the PAN ID (2 bytes, little-endian). 328 * 329 * This function makes a copy of the PAN ID. 330 */ 331 void nrf_802154_pan_id_set(const uint8_t * p_pan_id); 332 333 /** 334 * @brief Sets the extended address of the device. 335 * 336 * @param[in] p_extended_address Pointer to the extended address (8 bytes, little-endian). 337 * 338 * This function makes a copy of the address. 339 */ 340 void nrf_802154_extended_address_set(const uint8_t * p_extended_address); 341 342 /** 343 * @brief Sets the short address of the device. 344 * 345 * @param[in] p_short_address Pointer to the short address (2 bytes, little-endian). 346 * 347 * This function makes a copy of the address. 348 */ 349 void nrf_802154_short_address_set(const uint8_t * p_short_address); 350 351 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 352 /** 353 * @} 354 * @defgroup nrf_802154_transitions Functions to request FSM transitions and check current state 355 * @{ 356 */ 357 358 /** 359 * @brief Gets the current state of the radio. 360 */ 361 nrf_802154_state_t nrf_802154_state_get(void); 362 #endif // !NRF_802154_SERIALIZATION_HOST 363 364 /** 365 * @brief Changes the radio state to the @ref RADIO_STATE_SLEEP state. 366 * 367 * The sleep state is the lowest power state. In this state, the radio cannot transmit or receive 368 * frames. It is the only state in which the driver releases the high-frequency clock and does not 369 * request timeslots from a radio arbiter. 370 * 371 * @note If another module requests it, the high-frequency clock may be enabled even in the radio 372 * sleep state. 373 * 374 * @retval true The radio changes its state to the low power mode. 375 * @retval false The driver could not schedule changing state. 376 */ 377 bool nrf_802154_sleep(void); 378 379 /** 380 * @brief Changes the radio state to the @ref RADIO_STATE_SLEEP state if the radio is idle. 381 * 382 * The sleep state is the lowest power state. In this state, the radio cannot transmit or receive 383 * frames. It is the only state in which the driver releases the high-frequency clock and does not 384 * request timeslots from a radio arbiter. 385 * 386 * @note If another module requests it, the high-frequency clock may be enabled even in the radio 387 * sleep state. 388 * 389 * @retval NRF_802154_SLEEP_ERROR_NONE The radio changes its state to the low power mode. 390 * @retval NRF_802154_SLEEP_ERROR_BUSY The driver could not schedule changing state. 391 */ 392 nrf_802154_sleep_error_t nrf_802154_sleep_if_idle(void); 393 394 /** 395 * @brief Changes the radio state to @ref RADIO_STATE_RX. 396 * 397 * In the receive state, the radio receives frames and may automatically send ACK frames when 398 * appropriate. The received frame is reported to the higher layer by a call to 399 * @ref nrf_802154_received_raw or @ref nrf_802154_received_timestamp_raw . 400 * 401 * @retval true The radio enters the receive state. 402 * @retval false The driver could not enter the receive state. 403 */ 404 bool nrf_802154_receive(void); 405 406 /** 407 * @brief Requests reception at the specified time. 408 * 409 * This function works as a delayed version of @ref nrf_802154_receive. It is asynchronous. 410 * It queues the delayed reception using the Radio Scheduler module. 411 * If the delayed reception cannot be performed (@ref nrf_802154_receive_at would return false) 412 * or the requested reception timeslot is denied, @ref nrf_802154_receive_failed is called 413 * with the @ref NRF_802154_RX_ERROR_DELAYED_TIMESLOT_DENIED argument. 414 * 415 * If the requested reception time is in the past, the function returns false and does not 416 * schedule reception. 417 * 418 * A scheduled reception can be cancelled by a call to @ref nrf_802154_receive_at_cancel. 419 * 420 * @note The identifier @p id must be unique. It must not have the same value as identifiers 421 * of other delayed timeslots active at the moment, so that it can be mapped unambiguously 422 * to an active delayed operation if the request is successful. In particular, none of the reserved 423 * identifiers can be used. 424 * 425 * @param[in] rx_time Absolute time used by the SL Timer, in microseconds (us). 426 * @param[in] timeout Reception timeout (counted from @p rx_time), in microseconds (us). 427 * @param[in] channel Radio channel on which the frame is to be received. 428 * @param[in] id Identifier of the scheduled reception window. If the reception has been 429 * scheduled successfully, the value of this parameter can be used in 430 * @ref nrf_802154_receive_at_cancel to cancel it. 431 * 432 * @retval true The reception procedure was scheduled. 433 * @retval false The driver could not schedule the reception procedure. 434 */ 435 bool nrf_802154_receive_at(uint64_t rx_time, 436 uint32_t timeout, 437 uint8_t channel, 438 uint32_t id); 439 440 /** 441 * @brief Cancels a delayed reception scheduled by a call to @ref nrf_802154_receive_at. 442 * 443 * If the receive window has been scheduled but has not started yet, this function prevents 444 * entering the receive window. If the receive window has been scheduled and has already started, 445 * the radio remains in the receive state, but a window timeout will not be reported. 446 * 447 * @param[in] id Identifier of the delayed reception window to be cancelled. If the provided 448 * value does not refer to any scheduled or active receive window, the function 449 * returns false. 450 * 451 * @retval true The delayed reception was scheduled and successfully cancelled. 452 * @retval false No delayed reception was scheduled. 453 */ 454 bool nrf_802154_receive_at_cancel(uint32_t id); 455 456 /** 457 * @brief Changes the radio state to @ref RADIO_STATE_TX. 458 * 459 * @note If the CPU is halted or interrupted while this function is executed, 460 * @ref nrf_802154_transmitted_raw or @ref nrf_802154_transmit_failed can be called before this 461 * function returns a result. 462 * 463 * @note This function is implemented in zero-copy fashion. It passes the given buffer pointer to 464 * the RADIO peripheral. 465 * 466 * In the transmit state, the radio transmits a given frame. If requested, it waits for 467 * an ACK frame. Depending on @ref NRF_802154_ACK_TIMEOUT_ENABLED, the radio driver automatically 468 * stops waiting for an ACK frame or waits indefinitely for an ACK frame. If it is configured to 469 * wait, the MAC layer is responsible for calling @ref nrf_802154_receive or 470 * @ref nrf_802154_sleep after the ACK timeout. 471 * The transmission result is reported to the higher layer by calls to @ref nrf_802154_transmitted_raw 472 * or @ref nrf_802154_transmit_failed. 473 * 474 * @verbatim 475 * p_data 476 * v 477 * +-----+-----------------------------------------------------------+------------+ 478 * | PHR | MAC header and payload | FCS | 479 * +-----+-----------------------------------------------------------+------------+ 480 * | | 481 * | <---------------------------- PHR -----------------------------------> | 482 * @endverbatim 483 * 484 * @param[in] p_data Pointer to the array with data to transmit. The first byte must contain 485 * frame length (including FCS). The following bytes contain data. 486 * The CRC is computed automatically by the radio hardware. Therefore, 487 * the FCS field can contain any bytes. 488 * @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data 489 * to transmit. If @c NULL following metadata are used: 490 * Field | Value 491 * ----------------|----------------------------------------------------- 492 * @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT 493 * @c cca | @c true 494 * 495 * @retval true The transmission procedure was scheduled. 496 * @retval false The driver could not schedule the transmission procedure. 497 */ 498 bool nrf_802154_transmit_raw(uint8_t * p_data, 499 const nrf_802154_transmit_metadata_t * p_metadata); 500 501 /** 502 * @brief Requests transmission at the specified time. 503 * 504 * @note This function is implemented in a zero-copy fashion. It passes the given buffer pointer to 505 * the RADIO peripheral. 506 * 507 * 508 * This function works as a delayed version of @ref nrf_802154_transmit_raw. It is asynchronous. 509 * It queues the delayed transmission using the Radio Scheduler module and performs it 510 * at the specified time. 511 * 512 * If the delayed transmission is successfully performed, @ref nrf_802154_transmitted_raw is called. 513 * If the delayed transmission cannot be performed ( @ref nrf_802154_transmit_raw would return @c false) 514 * or the requested transmission timeslot is denied, @ref nrf_802154_transmit_failed with the 515 * @ref NRF_802154_TX_ERROR_TIMESLOT_DENIED argument is called. 516 * 517 * Additional CCA attempts can be requested by the caller through @p p_metadata. In that case CCA 518 * procedure is repeated back-to-back either until it returns idle channel and the transmission 519 * starts, or until 1 + @p p_metadata->extra_cca_attempts CCA attempts are performed. The maximum 520 * allowed number of additional CCA attempts is 254 so that the total number of CCA attempts doesn't 521 * exceed 255. 522 * 523 * This function is designed to transmit the first symbol of SHR at @p tx_time provided that 524 * the number of CCA attempts that will be performed is deterministic, which is only the case when 525 * no attempts are performed or when a single attempt is performed. Otherwise, the function assumes 526 * that @p tx_time points to a moment where the transmission would start if the first CCA attempt 527 * detected idle channel. If the first CCA detects busy channel and additional CCA attempts follow, 528 * the moment of transmission (first symbol of SHR) is delayed by the time taken by additional CCA 529 * attempts, which is a multiple of the duration of a single CCA attempt. 530 * 531 * The below diagram shows an example sequence where two additional CCA attempts are performed. 532 * TT denotes turnaround time necessary to switch from CCA to Tx. @p tx_time points to a moment in 533 * time that occurs TT after the first CCA finishes. 534 * 535 * @verbatim 536 * tx_time frame start 537 * | | 538 * | | 539 * v v 540 * +---------+---------+---------+--+----------+-----+-------------------------+ 541 * | CCA | CCA | CCA |TT| SHR | PHR | MAC Header and payload | 542 * +---------+---------+---------+--+----------+-----+-------------------------+ 543 * | | | 544 * v v v 545 * BUSY BUSY IDLE 546 * @endverbatim 547 * 548 * If the requested transmission time is in the past, the function returns @c false and does not 549 * schedule transmission. 550 * 551 * A successfully scheduled transmission can be cancelled by a call 552 * to @ref nrf_802154_transmit_at_cancel. 553 * 554 * @param[in] p_data Pointer to the array with data to transmit. The first byte must contain 555 * the frame length (including FCS). The following bytes contain data. 556 * The CRC is computed automatically by the radio hardware. Therefore, 557 * the FCS field can contain any bytes. 558 * @param[in] tx_time Absolute time used by the SL Timer, in microseconds (us). 559 * @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data 560 * to transmit. If @c NULL following metadata are used: 561 * Field | Value 562 * ----------------------|----------------------------------------------------- 563 * @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT 564 * @c cca | @c true 565 * @c channel | As returned by @ref nrf_802154_channel_get 566 * @c tx_power | As set with @ref nrf_802154_tx_power_set 567 * @c extra_cca_attempts | @c 0 568 * 569 * @retval true The transmission procedure was scheduled. 570 * @retval false The driver could not schedule the transmission procedure. 571 */ 572 bool nrf_802154_transmit_raw_at(uint8_t * p_data, 573 uint64_t tx_time, 574 const nrf_802154_transmit_at_metadata_t * p_metadata); 575 576 /** 577 * @brief Cancels a delayed transmission scheduled by a call to @ref nrf_802154_transmit_raw_at. 578 * 579 * If a delayed transmission has been scheduled but the transmission has not been started yet, 580 * a call to this function prevents the transmission. If the transmission is ongoing, 581 * it will not be aborted. 582 * 583 * If a delayed transmission has not been scheduled (or has already finished), this function does 584 * not change state and returns false. 585 * 586 * @retval true The delayed transmission was scheduled and successfully cancelled. 587 * @retval false No delayed transmission was scheduled. 588 */ 589 bool nrf_802154_transmit_at_cancel(void); 590 591 /** 592 * @brief Changes the radio state to energy detection. 593 * 594 * In the energy detection state, the radio detects the maximum energy for a given time. 595 * The result of the detection is reported to the higher layer by @ref nrf_802154_energy_detected. 596 * 597 * @note @ref nrf_802154_energy_detected can be called before this function returns a result. 598 * @note Performing the energy detection procedure can take longer than requested in @p time_us. 599 * The procedure is performed only during the timeslots granted by a radio arbiter. 600 * It can be interrupted by other protocols using the radio hardware. If the procedure is 601 * interrupted, it is automatically continued and the sum of time periods during which the 602 * procedure is carried out is not less than the requested @p time_us. 603 * 604 * @param[in] time_us Duration of energy detection procedure. The given value is rounded up to 605 * multiplication of 8 symbols (128 us). 606 * 607 * @retval true The energy detection procedure was scheduled. 608 * @retval false The driver could not schedule the energy detection procedure. 609 */ 610 bool nrf_802154_energy_detection(uint32_t time_us); 611 612 /** 613 * @brief Changes the radio state to @ref RADIO_STATE_CCA. 614 * 615 * @note @ref nrf_802154_cca_done can be called before this function returns a result. 616 * 617 * In the CCA state, the radio verifies if the channel is clear. The result of the verification is 618 * reported to the higher layer by @ref nrf_802154_cca_done. 619 * 620 * @retval true The CCA procedure was scheduled. 621 * @retval false The driver could not schedule the CCA procedure. 622 */ 623 bool nrf_802154_cca(void); 624 625 #if NRF_802154_CARRIER_FUNCTIONS_ENABLED 626 627 /** 628 * @brief Changes the radio state to continuous carrier. 629 * 630 * @note When the radio is emitting continuous carrier signals, it blocks all transmissions on the 631 * selected channel. This function is to be called only during radio tests. Do not 632 * use it during normal device operation. 633 * 634 * @retval true The continuous carrier procedure was scheduled. 635 * @retval false The driver could not schedule the continuous carrier procedure. 636 */ 637 bool nrf_802154_continuous_carrier(void); 638 639 /** 640 * @brief Changes the radio state to modulated carrier. 641 * 642 * @note When the radio is emitting modulated carrier signals, it blocks all transmissions on the 643 * selected channel. This function is to be called only during radio tests. Do not 644 * use it during normal device operation. 645 * 646 * @param[in] p_data Pointer to a buffer to modulate the carrier with. The first byte is the data length. 647 * 648 * @retval true The modulated carrier procedure was scheduled. 649 * @retval false The driver could not schedule the modulated carrier procedure. 650 */ 651 bool nrf_802154_modulated_carrier(const uint8_t * p_data); 652 653 #endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED 654 655 /** 656 * @} 657 * @defgroup nrf_802154_memman Driver memory management 658 * @{ 659 */ 660 661 /** 662 * @brief Notifies the driver that the buffer containing the received frame is not used anymore. 663 * 664 * @note The buffer pointed to by @p p_data may be modified by this function. 665 * @note This function can be safely called only from the main context. To free the buffer from 666 * a callback or the IRQ context, use @ref nrf_802154_buffer_free_immediately_raw. 667 * 668 * @param[in] p_data Pointer to the buffer containing the received data that is no longer needed 669 * by the higher layer. 670 */ 671 void nrf_802154_buffer_free_raw(uint8_t * p_data); 672 673 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 674 /** 675 * @brief Notifies the driver that the buffer containing the received frame is not used anymore. 676 * 677 * @note The buffer pointed to by @p p_data may be modified by this function. 678 * @note This function can be safely called from any context. If the driver is busy processing 679 * a request called from a context with lower priority, this function returns false and 680 * the caller should free the buffer later. 681 * 682 * @param[in] p_data Pointer to the buffer containing the received data that is no longer needed 683 * by the higher layer. 684 * 685 * @retval true Buffer was freed successfully. 686 * @retval false Buffer cannot be freed right now due to ongoing operation. 687 */ 688 bool nrf_802154_buffer_free_immediately_raw(uint8_t * p_data); 689 #endif // !NRF_802154_SERIALIZATION_HOST 690 691 /** 692 * @} 693 * @defgroup nrf_802154_rssi RSSI measurement function 694 * @{ 695 */ 696 697 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 698 /** 699 * @brief Begins the RSSI measurement. 700 * 701 * @note This function is to be called in the @ref RADIO_STATE_RX state. 702 * 703 * The result will be available after the measurement process is finished. The result can be read by 704 * @ref nrf_802154_rssi_last_get. Check the documentation of the RADIO peripheral to check 705 * the duration of the RSSI measurement procedure. 706 * 707 * @retval true RSSI measurement successfully requested. 708 * @retval false RSSI measurement cannot be scheduled at the moment. 709 */ 710 bool nrf_802154_rssi_measure_begin(void); 711 712 /** 713 * @brief Gets the result of the last RSSI measurement. 714 * 715 * @returns RSSI measurement result, in dBm. 716 */ 717 int8_t nrf_802154_rssi_last_get(void); 718 719 #endif // !NRF_802154_SERIALIZATION_HOST 720 721 /** 722 * @} 723 * @defgroup nrf_802154_prom Promiscuous mode 724 * @{ 725 */ 726 727 /** 728 * @brief Enables or disables the promiscuous radio mode. 729 * 730 * @note The promiscuous mode is disabled by default. 731 * 732 * In the promiscuous mode, the driver notifies the higher layer that it received any frame 733 * (regardless frame type or destination address). 734 * In normal mode (not promiscuous), the higher layer is not notified about ACK frames and frames 735 * with unknown type. Also, frames with a destination address not matching the device address are 736 * ignored. 737 * 738 * @param[in] enabled If the promiscuous mode is to be enabled. 739 */ 740 void nrf_802154_promiscuous_set(bool enabled); 741 742 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 743 /** 744 * @brief Checks if the radio is in the promiscuous mode. 745 * 746 * @retval True Radio is in the promiscuous mode. 747 * @retval False Radio is not in the promiscuous mode. 748 */ 749 bool nrf_802154_promiscuous_get(void); 750 751 /** 752 * @} 753 * @defgroup nrf_802154_autoack Auto ACK management 754 * @{ 755 */ 756 757 /** 758 * @brief Enables or disables the automatic acknowledgments (auto ACK). 759 * 760 * @note The auto ACK is enabled by default. 761 * 762 * If the auto ACK is enabled, the driver prepares and sends ACK frames automatically 763 * aTurnaroundTime (192 us) after the proper frame is received. The driver prepares an ACK frame 764 * according to the data provided by @ref nrf_802154_ack_data_set. 765 * When the auto ACK is enabled, the driver notifies the next higher layer about the received frame 766 * after the ACK frame is transmitted. 767 * If the auto ACK is disabled, the driver does not transmit ACK frames. It notifies the next higher 768 * layer about the received frames when a frame is received. In this mode, the next higher layer is 769 * responsible for sending the ACK frame. ACK frames should be sent using @ref nrf_802154_transmit_raw. 770 * 771 * @param[in] enabled If the auto ACK should be enabled. 772 */ 773 void nrf_802154_auto_ack_set(bool enabled); 774 775 /** 776 * @brief Checks if the auto ACK is enabled. 777 * 778 * @retval True Auto ACK is enabled. 779 * @retval False Auto ACK is disabled. 780 */ 781 bool nrf_802154_auto_ack_get(void); 782 783 #endif // !NRF_802154_SERIALIZATION_HOST 784 785 /** 786 * @brief Configures the device as the PAN coordinator. 787 * 788 * @note That information is used for packet filtering. 789 * 790 * @param[in] enabled The radio is configured as the PAN coordinator. 791 */ 792 void nrf_802154_pan_coord_set(bool enabled); 793 794 #if NRF_802154_PAN_COORD_GET_ENABLED || defined(DOXYGEN) 795 /** 796 * @brief Checks if the radio is configured as the PAN coordinator. 797 * 798 * @retval true The radio is configured as the PAN coordinator. 799 * @retval false The radio is not configured as the PAN coordinator. 800 */ 801 bool nrf_802154_pan_coord_get(void); 802 803 #endif // NRF_802154_PAN_COORD_GET_ENABLED 804 805 /** 806 * @brief Select the source matching algorithm. 807 * 808 * @note This method should be called after driver initialization, but before transceiver is enabled. 809 * 810 * When calling @ref nrf_802154_ack_data_pending_bit_should_be_set, one of several algorithms 811 * for source address matching will be chosen. To ensure a specific algorithm is selected, 812 * call this function before @ref nrf_802154_ack_data_pending_bit_should_be_set. 813 * 814 * @param[in] match_method Source address matching method to be used. 815 */ 816 void nrf_802154_src_addr_matching_method_set(nrf_802154_src_addr_match_t match_method); 817 818 /** 819 * @brief Adds the address of a peer node for which the provided ACK data 820 * is to be injected into generated ACKs. 821 * 822 * Data passed to this function can be either pending bit data or Header IE data. 823 * 824 * The pending bit list works differently, depending on the upper layer for which the source 825 * address matching method is selected: 826 * - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD 827 * - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE 828 * - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 829 * For more information, see @ref nrf_802154_src_addr_match_t. 830 * 831 * For IE data, specific cases are supported, where additional data will be injected into the IE on pre-transmission: 832 * - CSL IE - CSL phase will be injected if IE ID is set to @ref IE_CSL_ID 833 * - Thread link metrics - Link metrics will be injected if 834 * - IE ID is set to IE_VENDOR_ID 835 * - OUI is set to IE_VENDOR_THREAD_OUI 836 * - Thread IE subtype is set to IE_VENDOR_THREAD_ACK_PROBING_ID 837 * 838 * For Link metrics to be injected, additional preparation is required. Each byte of injected link metrics needs to be filled 839 * with a token, indicating what type of data is to be injected pre-transmission. Supported tokens are: 840 * - @ref IE_VENDOR_THREAD_RSSI_TOKEN - RSSI of the last received frame will be injected, 841 * - @ref IE_VENDOR_THREAD_MARGIN_TOKEN - RSSI above sensitivity margin of the last received frame will be injected, 842 * - @ref IE_VENDOR_THREAD_LQI_TOKEN - LQI of the last received frame will be injected. 843 * Additionally, tokens must be unique in given IE, all bytes prepared for link metrics must be filled with tokens and no more 844 * than two bytes must be prepared for link metrics. 845 * If any of those conditions is not met, no data will be injected into the ACK pre-transmission. 846 * 847 * To better illustrate, if RSSI is to be inserted into ACKs for specific address, 848 * following ie data needs to be prepared: 849 * 850 * @verbatim 851 * +------------+----------------------+---------------------------------+-----------------------------+ 852 * | Bytes: 0-1 | 2-4 | 5 | 6 | 853 * +------------+----------------------+---------------------------------+-----------------------------+ 854 * | IE header | IE_VENDOR_THREAD_OUI | IE_VENDOR_THREAD_ACK_PROBING_ID | IE_VENDOR_THREAD_RSSI_TOKEN | 855 * +------------+----------------------+---------------------------------+-----------------------------+ 856 * | | 857 * | <------------------IE Vendor-specific data------------------> | 858 * @endverbatim 859 * 860 * When sending ACK with this data, before transmission, RSSI of the last received frame 861 * will be written into byte 6. 862 * 863 * The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set. 864 * 865 * @param[in] p_addr Array of bytes containing the address of the node (little-endian). 866 * @param[in] extended If the given address is an extended MAC address or a short MAC address. 867 * @param[in] p_data Pointer to the buffer containing data to be set. 868 * @param[in] length Length of @p p_data. 869 * @param[in] data_type Type of data to be set. Refer to the @ref nrf_802154_ack_data_t type. 870 * 871 * @retval True Address successfully added to the list. 872 * @retval False Not enough memory to store this address in the list. 873 */ 874 bool nrf_802154_ack_data_set(const uint8_t * p_addr, 875 bool extended, 876 const void * p_data, 877 uint16_t length, 878 nrf_802154_ack_data_t data_type); 879 880 /** 881 * @brief Removes the address of a peer node for which the ACK data is set from the pending bit list. 882 * 883 * The ACK data that was previously set for the given address is automatically removed. 884 * 885 * The pending bit list works differently, depending on the upper layer for which the source 886 * address matching method is selected: 887 * - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD 888 * - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE 889 * - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 890 * For more information, see @ref nrf_802154_src_addr_match_t. 891 * 892 * The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set. 893 * 894 * @param[in] p_addr Array of bytes containing the address of the node (little-endian). 895 * @param[in] extended If the given address is an extended MAC address or a short MAC address. 896 * @param[in] data_type Type of data to be removed. Refer to the @ref nrf_802154_ack_data_t type. 897 * 898 * @retval True Address removed from the list. 899 * @retval False Address not found in the list. 900 */ 901 bool nrf_802154_ack_data_clear(const uint8_t * p_addr, 902 bool extended, 903 nrf_802154_ack_data_t data_type); 904 905 /** 906 * @brief Removes all addresses of a given length from the ACK data list. 907 * 908 * @param[in] extended Indication if all extended addresses or all short addresses are 909 * to be removed from the list. 910 * @param[in] data_type Type of data that is to be cleared for all addresses of a given length. 911 */ 912 void nrf_802154_ack_data_remove_all(bool extended, nrf_802154_ack_data_t data_type); 913 914 /** 915 * @brief Enables or disables setting a pending bit in automatically transmitted ACK frames. 916 * 917 * @note Setting a pending bit in automatically transmitted ACK frames is enabled by default. 918 * 919 * The radio driver automatically sends ACK frames in response frames destined for this node with 920 * the ACK Request bit set. The pending bit in the ACK frame can be set or cleared regarding data 921 * in the indirect queue destined for the ACK destination. 922 * 923 * If setting a pending bit in ACK frames is disabled, the pending bit in every ACK frame is set. 924 * If setting a pending bit in ACK frames is enabled, the radio driver checks if there is data 925 * in the indirect queue destined for the ACK destination. If there is no such data, 926 * the pending bit is cleared. 927 * 928 * @note Due to the ISR latency, the radio driver might not be able to verify if there is data 929 * in the indirect queue before ACK is sent. In this case, the pending bit is set. 930 * 931 * @param[in] enabled If setting a pending bit in ACK frames is enabled. 932 */ 933 void nrf_802154_auto_pending_bit_set(bool enabled); 934 935 /** 936 * @brief Adds the address of a peer node to the pending bit list. 937 * 938 * The pending bit list works differently, depending on the upper layer for which the source 939 * address matching method is selected: 940 * - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD 941 * - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE 942 * - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 943 * For more information, see @ref nrf_802154_src_addr_match_t. 944 * 945 * The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set. 946 * 947 * @note This function makes a copy of the given address. 948 * 949 * @param[in] p_addr Array of bytes containing the address of the node (little-endian). 950 * @param[in] extended If the given address is an extended MAC address or a short MAC address. 951 * 952 * @retval True The address is successfully added to the list. 953 * @retval False Not enough memory to store the address in the list. 954 */ 955 bool nrf_802154_pending_bit_for_addr_set(const uint8_t * p_addr, bool extended); 956 957 /** 958 * @brief Removes address of a peer node from the pending bit list. 959 * 960 * The pending bit list works differently, depending on the upper layer for which the source 961 * address matching method is selected: 962 * - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD 963 * - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE 964 * - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 965 * For more information, see @ref nrf_802154_src_addr_match_t. 966 * 967 * The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set. 968 * 969 * @param[in] p_addr Array of bytes containing the address of the node (little-endian). 970 * @param[in] extended If the given address is an extended MAC address or a short MAC address. 971 * 972 * @retval True The address is successfully removed from the list. 973 * @retval False No such address in the list. 974 */ 975 bool nrf_802154_pending_bit_for_addr_clear(const uint8_t * p_addr, bool extended); 976 977 /** 978 * @brief Removes all addresses of a given type from the pending bit list. 979 * 980 * The pending bit list works differently, depending on the upper layer for which the source 981 * address matching method is selected: 982 * - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD 983 * - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE 984 * - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 985 * For more information, see @ref nrf_802154_src_addr_match_t. 986 * 987 * The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set. 988 * 989 * @param[in] extended If the function is to remove all extended MAC addresses or all short 990 * addresses. 991 */ 992 void nrf_802154_pending_bit_for_addr_reset(bool extended); 993 994 /** 995 * @} 996 * @defgroup nrf_802154_cca CCA configuration management 997 * @{ 998 */ 999 1000 /** 1001 * @brief Configures the radio CCA mode and threshold. 1002 * 1003 * @param[in] p_cca_cfg Pointer to the CCA configuration structure. Only fields relevant to 1004 * the selected mode are updated. 1005 */ 1006 void nrf_802154_cca_cfg_set(const nrf_802154_cca_cfg_t * p_cca_cfg); 1007 1008 /** 1009 * @brief Gets the current radio CCA configuration. 1010 * 1011 * @param[out] p_cca_cfg Pointer to the structure for the current CCA configuration. 1012 */ 1013 void nrf_802154_cca_cfg_get(nrf_802154_cca_cfg_t * p_cca_cfg); 1014 1015 /** 1016 * @} 1017 * @defgroup nrf_802154_csma CSMA-CA procedure 1018 * @{ 1019 */ 1020 #if NRF_802154_CSMA_CA_ENABLED || defined(DOXYGEN) 1021 1022 /** 1023 * @brief Performs the CSMA-CA procedure and transmits a frame in case of success. 1024 * 1025 * The end of the CSMA-CA procedure is notified by @ref nrf_802154_transmitted_raw or 1026 * @ref nrf_802154_transmit_failed. 1027 * 1028 * @note The driver may be configured to automatically time out waiting for an ACK frame depending 1029 * on @ref NRF_802154_ACK_TIMEOUT_ENABLED. If the automatic ACK timeout is disabled, 1030 * the CSMA-CA procedure does not time out waiting for an ACK frame if a frame 1031 * with the ACK request bit set was transmitted. The MAC layer is expected to manage the timer 1032 * to time out waiting for the ACK frame. This timer can be started 1033 * by @ref nrf_802154_tx_started. When the timer expires, the MAC layer is expected 1034 * to call @ref nrf_802154_receive or @ref nrf_802154_sleep to stop waiting for the ACK frame. 1035 * @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled. 1036 * 1037 * @param[in] p_data Pointer to the frame to transmit. See also @ref nrf_802154_transmit_raw. 1038 * @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data 1039 * to transmit. If @c NULL following metadata are used: 1040 * Field | Value 1041 * ----------------|----------------------------------------------------- 1042 * @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT 1043 * 1044 * @retval true The chain of CSMA-CA and transmission procedure was scheduled. 1045 * @retval false The driver could not schedule the procedure chain. 1046 */ 1047 bool nrf_802154_transmit_csma_ca_raw(uint8_t * p_data, 1048 const nrf_802154_transmit_csma_ca_metadata_t * p_metadata); 1049 1050 /** 1051 * @brief Sets the minimum value of the backoff exponent (BE) in the CSMA-CA algorithm. 1052 * 1053 * @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled. 1054 * 1055 * @param[in] min_be Minimum value of the backoff exponent. 1056 * 1057 * @retval true When value provided by @p min_be has been set successfully. 1058 * @retval false Otherwise. 1059 */ 1060 bool nrf_802154_csma_ca_min_be_set(uint8_t min_be); 1061 1062 /** 1063 * @brief Gets the minimum value of the backoff exponent (BE) in the CSMA-CA algorithm. 1064 * 1065 * @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled. 1066 * 1067 * @return Current minimum value of the backoff exponent. 1068 */ 1069 uint8_t nrf_802154_csma_ca_min_be_get(void); 1070 1071 /** 1072 * @brief Sets the maximum value of the backoff exponent (BE) in the CSMA-CA algorithm. 1073 * 1074 * @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled. 1075 * 1076 * @param[in] max_be Maximum value of the backoff exponent. 1077 * 1078 * @retval true When value provided by @p max_be has been set successfully. 1079 * @retval false Otherwise. 1080 */ 1081 bool nrf_802154_csma_ca_max_be_set(uint8_t max_be); 1082 1083 /** 1084 * @brief Gets the maximum value of the backoff exponent (BE) in the CSMA-CA algorithm. 1085 * 1086 * @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled. 1087 * 1088 * @return Current maximum value of the backoff exponent. 1089 */ 1090 uint8_t nrf_802154_csma_ca_max_be_get(void); 1091 1092 /** 1093 * @brief Sets the maximum number of backoffs the CSMA-CA algorithm will attempt before declaring 1094 * a channel access failure. 1095 * 1096 * @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled. 1097 * 1098 * @param[in] max_backoffs Maximum number of backoffs. 1099 */ 1100 void nrf_802154_csma_ca_max_backoffs_set(uint8_t max_backoffs); 1101 1102 /** 1103 * @brief Gets the maximum number of backoffs the CSMA-CA algorithm will attempt before declaring 1104 * a channel access failure. 1105 * 1106 * @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled. 1107 * 1108 * @return Current maximum number of backoffs. 1109 */ 1110 uint8_t nrf_802154_csma_ca_max_backoffs_get(void); 1111 1112 #endif // NRF_802154_CSMA_CA_ENABLED 1113 1114 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 1115 /** 1116 * @} 1117 * @defgroup nrf_802154_timeout ACK timeout procedure 1118 * @{ 1119 */ 1120 #if NRF_802154_ACK_TIMEOUT_ENABLED || defined(DOXYGEN) 1121 1122 /** 1123 * @brief Sets timeout for the ACK timeout feature. 1124 * 1125 * A timeout is notified by @ref nrf_802154_transmit_failed. 1126 * 1127 * @note This function is available if @ref NRF_802154_ACK_TIMEOUT_ENABLED is enabled. 1128 * 1129 * @param[in] time Timeout in microseconds (us). 1130 * A default value is defined in nrf_802154_config.h. 1131 */ 1132 void nrf_802154_ack_timeout_set(uint32_t time); 1133 1134 #endif // !NRF_802154_SERIALIZATION_HOST 1135 1136 #endif // NRF_802154_ACK_TIMEOUT_ENABLED 1137 1138 /** 1139 * @} 1140 * @defgroup nrf_802154_coex Wifi Coex feature 1141 * @{ 1142 */ 1143 1144 1145 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 1146 /** 1147 * @brief Checks if wifi coex signaling is enabled. 1148 * 1149 * @retval true Wifi coex signaling is enabled. 1150 * @retval false Wifi coex signaling is disabled. 1151 */ 1152 bool nrf_802154_wifi_coex_is_enabled(void); 1153 1154 /** 1155 * @brief Sets Coex request mode used in receive operations. 1156 * 1157 * @param[in] mode Coex receive request mode. For allowed values see @ref nrf_802154_coex_rx_request_mode_t type. 1158 * 1159 * @retval true Operation succeeded. 1160 * @retval false Requested mode is not supported. 1161 */ 1162 bool nrf_802154_coex_rx_request_mode_set(nrf_802154_coex_rx_request_mode_t mode); 1163 1164 /** 1165 * @brief Gets Coex request mode used in receive operations. 1166 * 1167 * @return Current Coex receive request mode. For allowed values see @ref nrf_802154_coex_rx_request_mode_t type. 1168 */ 1169 nrf_802154_coex_rx_request_mode_t nrf_802154_coex_rx_request_mode_get(void); 1170 1171 /** 1172 * @brief Sets Coex request mode used in transmit operations. 1173 * 1174 * @param[in] mode Coex transmit request mode. For allowed values see @ref nrf_802154_coex_tx_request_mode_t type. 1175 * 1176 * @retval true Operation succeeded. 1177 * @retval false Requested mode is not supported. 1178 */ 1179 bool nrf_802154_coex_tx_request_mode_set(nrf_802154_coex_tx_request_mode_t mode); 1180 1181 /** 1182 * @brief Gets Coex request mode used in transmit operations. 1183 * 1184 * @return Current Coex transmit request mode. For allowed values see @ref nrf_802154_coex_tx_request_mode_t type. 1185 */ 1186 nrf_802154_coex_tx_request_mode_t nrf_802154_coex_tx_request_mode_get(void); 1187 1188 #endif // !NRF_802154_SERIALIZATION_HOST 1189 1190 /** 1191 * @} 1192 * @defgroup nrf_802154_stats Statistics and measurements 1193 * @{ 1194 */ 1195 1196 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 1197 /** 1198 * @brief Gets current statistics. 1199 * 1200 * @param[out] p_stats Structure that will be filled with current stats values. 1201 */ 1202 void nrf_802154_stats_get(nrf_802154_stats_t * p_stats); 1203 1204 /** 1205 * @brief Get current statistics. 1206 * 1207 * @note This returns part of information returned by @ref nrf_802154_stats_get 1208 * 1209 * @param[out] p_stat_counters Structure that will be filled with current stats counter values. 1210 */ 1211 void nrf_802154_stat_counters_get(nrf_802154_stat_counters_t * p_stat_counters); 1212 1213 /** 1214 * @brief Decreases current statistic counter values by the provided ones. 1215 * 1216 * This function is intended to be called together with @ref nrf_802154_stats_get 1217 * to avoid missing any counted events. 1218 * 1219 * @param[in] p_stat_counters Current stat counter values will be decreased by values provided 1220 * behind this pointer. 1221 */ 1222 void nrf_802154_stat_counters_subtract(const nrf_802154_stat_counters_t * p_stat_counters); 1223 1224 #endif // !NRF_802154_SERIALIZATION_HOST 1225 1226 /** 1227 * @brief Get time stamps of events gathered by the last operation. 1228 * 1229 * @param[out] p_stat_timestamps Structure that will be filled with current time stamps of events. 1230 */ 1231 void nrf_802154_stat_timestamps_get(nrf_802154_stat_timestamps_t * p_stat_timestamps); 1232 1233 #if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) 1234 /** 1235 * @brief Resets current stat counters to 0. 1236 * 1237 * @note @ref nrf_802154_stat_counters_get and @ref nrf_802154_stat_counters_reset may lead to 1238 * missing events if an counted event occurs between these calls. Use 1239 * @ref nrf_802154_stat_counters_subtract to avoid such condition if necessary. 1240 */ 1241 void nrf_802154_stat_counters_reset(void); 1242 1243 #endif // !NRF_802154_SERIALIZATION_HOST 1244 1245 /** 1246 * @} 1247 * @defgroup nrf_802154_ifs Inter-frame spacing feature 1248 * @{ 1249 */ 1250 #if NRF_802154_IFS_ENABLED || defined(DOXYGEN) 1251 1252 /** 1253 * @brief Gets IFS operation mode. 1254 * 1255 * @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled. 1256 * 1257 * @return Current IFS operation mode. Refer to @ref nrf_802154_ifs_mode_t for details. 1258 */ 1259 nrf_802154_ifs_mode_t nrf_802154_ifs_mode_get(void); 1260 1261 /** 1262 * @brief Sets IFS operation mode. 1263 * 1264 * @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled. 1265 * 1266 * @param[in] mode IFS operation mode. Refer to @ref nrf_802154_ifs_mode_t for details. 1267 * 1268 * @retval true The update of IFS operation mode was successful. 1269 * @retval false The update of IFS operation mode failed. Provided mode is unsupported 1270 */ 1271 bool nrf_802154_ifs_mode_set(nrf_802154_ifs_mode_t mode); 1272 1273 /** 1274 * @brief Gets Short IFS period in microseconds. 1275 * 1276 * @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled. 1277 * 1278 * @return Current Short IFS period in microseconds. 1279 */ 1280 uint16_t nrf_802154_ifs_min_sifs_period_get(void); 1281 1282 /** 1283 * @brief Sets Short IFS period in microseconds. 1284 * 1285 * @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled. 1286 * 1287 * @param[in] period Short IFS period in microseconds. 1288 */ 1289 void nrf_802154_ifs_min_sifs_period_set(uint16_t period); 1290 1291 /** 1292 * @brief Gets Long IFS period in microseconds. 1293 * 1294 * @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled. 1295 * 1296 * @return Current Long IFS period in microseconds. 1297 */ 1298 uint16_t nrf_802154_ifs_min_lifs_period_get(void); 1299 1300 /** 1301 * @brief Sets Long IFS period in microseconds. 1302 * 1303 * @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled. 1304 * 1305 * @param[in] period Long IFS period in microseconds. 1306 */ 1307 void nrf_802154_ifs_min_lifs_period_set(uint16_t period); 1308 1309 #endif // NRF_802154_IFS_ENABLED 1310 1311 /** 1312 * @} 1313 * @defgroup nrf_802154_capabilities Radio driver run-time capabilities feature. 1314 * @{ 1315 */ 1316 1317 /** 1318 * @brief Gets nRF 802.15.4 Radio Driver Capabilities. 1319 * 1320 * @return Capabilities of the radio driver. 1321 */ 1322 nrf_802154_capabilities_t nrf_802154_capabilities_get(void); 1323 1324 /** 1325 * @} 1326 * @defgroup nrf_802154_security Radio driver MAC security feature. 1327 * @{ 1328 */ 1329 1330 /** 1331 * @brief Sets nRF 802.15.4 Radio Driver Global MAC Frame Counter. 1332 * 1333 * The driver automatically increments the counter in every outgoing frame 1334 * which uses the Global MAC Frame Counter. 1335 * This call is meant to set the initial value of the frame counter. 1336 * 1337 * @param[in] frame_counter Global MAC Frame Counter to set. 1338 */ 1339 void nrf_802154_security_global_frame_counter_set(uint32_t frame_counter); 1340 1341 /** 1342 * @brief Sets nRF 802.15.4 Radio Driver MAC Global Frame Counter if the value passed is larger than current. 1343 * 1344 * @param[in] frame_counter Frame counter to set. 1345 */ 1346 void nrf_802154_security_global_frame_counter_set_if_larger(uint32_t frame_counter); 1347 1348 /** 1349 * @brief Store the 802.15.4 MAC Security Key inside the nRF 802.15.4 Radio Driver. 1350 * 1351 * @param[in] p_key Pointer to the key to store. Refer to @ref nrf_802154_key_t for details. 1352 * Storing the key copies the content of the key and key ID into the Radio Driver. 1353 * This input parameter can be destroyed after the call. 1354 * 1355 * @note This function is not reentrant and must be called from thread context only. 1356 * 1357 * @retval NRF_802154_SECURITY_ERROR_NONE Storing of key is successful. 1358 * @retval NRF_802154_SECURITY_ERROR_TYPE_NOT_SUPPORTED Type of the key is not supported. 1359 * @retval NRF_802154_SECURITY_ERROR_MODE_NOT_SUPPORTED ID mode of the key is not supported. 1360 * @retval NRF_802154_SECURITY_ERROR_ALREADY_PRESENT Failed to store the key - key of such id is already 1361 * present. Remove the key first to overwrite. 1362 * @retval NRF_802154_SECURITY_ERROR_STORAGE_FULL Failed to store the key - storage full. 1363 */ 1364 nrf_802154_security_error_t nrf_802154_security_key_store(nrf_802154_key_t * p_key); 1365 1366 /** 1367 * @brief Remove the 802.15.4 MAC Security Key from the nRF 802.15.4 Radio Driver. 1368 * 1369 * @param[in] p_id Pointer to the ID of the key to remove. 1370 * 1371 * @note This function is not reentrant and must be called from thread context only. 1372 * 1373 * @retval NRF_802154_SECURITY_ERROR_NONE Removal of key is successful. 1374 * @retval NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND Failed to remove the key - no such key found. 1375 */ 1376 nrf_802154_security_error_t nrf_802154_security_key_remove(nrf_802154_key_id_t * p_id); 1377 1378 /** 1379 * @brief Remove all stored 802.15.4 MAC Security Keys from the nRF 802.15.4 Radio Driver. 1380 * 1381 * @note This function is not reentrant and must be called from thread context only. 1382 */ 1383 void nrf_802154_security_key_remove_all(void); 1384 1385 /** 1386 * @} 1387 * @defgroup nrf_802154_ie_writer Radio driver Information Element data injection feature. 1388 * @{ 1389 */ 1390 1391 /** 1392 * @brief Sets the value of CSL period to inject into the CSL information element. 1393 * 1394 * @param[in] period CSL period value. 1395 */ 1396 void nrf_802154_csl_writer_period_set(uint16_t period); 1397 1398 /** 1399 * @brief Sets the anchor time based on which the next CSL window time and the CSL phase is calculated. 1400 * 1401 * This function sets an anchor time based on which the times of future CSL windows are calculated. 1402 * When this anchor time is used for calculations, it is assumed that it points to a time where 1403 * the first bit of MAC header of the frame received from a peer happens. In other words, the anchor 1404 * time should point to a time where CSL phase would be equal 0. As a result, CSL phase can always 1405 * be calculated relatively to a time given by the equation @c anchor_time + @c n * @c csl_period 1406 * where @c n is an integer. Note that the reasoning holds irrespectively of signedness of @c n 1407 * so the anchor time can be either in the past or in the future. 1408 * 1409 * This function should be called after calling @ref nrf_802154_csl_writer_period_set and every time 1410 * when the CSL communication desynchronizes. 1411 * 1412 * If this function is not called a legacy CSL operation mode is chosen. The CSL phase is then 1413 * calculated based on the time of the nearest scheduled CSL reception window and can be undefined, 1414 * if no such window was scheduled. 1415 * 1416 * @param[in] anchor_time Anchor time in microseconds. 1417 */ 1418 void nrf_802154_csl_writer_anchor_time_set(uint64_t anchor_time); 1419 1420 /** 1421 * @brief Sets the RxOnWhenIdle mode value. 1422 * 1423 * This function sets the RxOnWhenIdle mode value, which defaults to true. When enabled, the radio will 1424 * stay in receive state during idle periods. When disabled, the radio will stay in sleep state during 1425 * idle periods. The new value will only take effect after a completed operation. 1426 * 1427 * Notice that the period following a failed reception is not considered idle, rather continuation of 1428 * the reception state. Same goes for the finalization of a reception during a receive slot. 1429 * 1430 * An idle period is started in the following situations: 1431 * - After @ref nrf_802154_receive starts a receive state and a frame is correctly received and passed 1432 * the filtering: 1433 * - If the received frame requests an ACK: after the ACK was properly transmitted or immediately 1434 * if for some internal condition the ACK is not transmitted. 1435 * - If the received frame does not request an ACK: immediately, unless the received frame is an 1436 * spurious ACK. 1437 * - Immediately after a frame is transmitted, when no ACK is requested. 1438 * - After a frame is transmitted, when ACK is requested, if: 1439 * - ACK timeout expires. 1440 * - An invalid ACK is received (or not an ACK frame). 1441 * - The matching ACK is received, unless the transmitted frame was a Data Request Command and the 1442 * frame pending bit is set to true in the ACK. 1443 * - After a standalone CCA is completed. 1444 * - After a failed CCA during CSMA/CA procedure. 1445 * - After every Energy Detection operation. 1446 * - After a delayed reception times out. 1447 * 1448 * Combining disabled RxOnWhenIdle mode and enabled promiscuous mode is unsupported. Such configuration 1449 * may result in an undefined behavior. 1450 * 1451 * @param[in] rx_on_when_idle If RxOnWhenIdle mode should be enabled. 1452 */ 1453 void nrf_802154_rx_on_when_idle_set(bool rx_on_when_idle); 1454 1455 /** 1456 * @brief Sets the value of CST period to inject into the CST information element. 1457 * 1458 * @param[in] period CST period value. 1459 */ 1460 void nrf_802154_cst_writer_period_set(uint16_t period); 1461 1462 /** 1463 * @brief Sets the anchor time based on which the next CST window time and the CST phase is calculated. 1464 * 1465 * This function sets an anchor time which is a time of a CST window, based which on the times of future CST windows are 1466 * calculated. It is assumed that all other CST windows occur at time @c anchor_time + @c n * @c cst_period where @c n is 1467 * an integer. Note that the anchor time can be both in the past and in the future. 1468 * 1469 * @param[in] anchor_time Anchor time value. 1470 */ 1471 void nrf_802154_cst_writer_anchor_time_set(uint64_t anchor_time); 1472 1473 /** 1474 * @} 1475 * @defgroup nrf_802154_test_modes Test modes 1476 * @{ 1477 */ 1478 1479 #if NRF_802154_TEST_MODES_ENABLED 1480 /** 1481 * @brief Gets the current CSMA/CA backoff test mode. 1482 * 1483 * @return Current CSMA/CA backoff test mode. 1484 */ 1485 nrf_802154_test_mode_csmaca_backoff_t nrf_802154_test_mode_csmaca_backoff_get(void); 1486 1487 /** 1488 * @brief Sets the csmaca backoff test mode. 1489 * 1490 * @param[in] value CSMA/CA backoff test mode (See @ref nrf_802154_test_mode_csmaca_backoff_t 1491 * for defined values). 1492 */ 1493 void nrf_802154_test_mode_csmaca_backoff_set(nrf_802154_test_mode_csmaca_backoff_t value); 1494 1495 #endif // NRF_802154_TEST_MODES_ENABLED 1496 1497 /** @} */ 1498 1499 #ifdef __cplusplus 1500 } 1501 #endif 1502 1503 #endif /* NRF_802154_H_ */ 1504 1505 /** @} */ 1506
