1 /* 2 * Copyright (c) 2017 - 2023, 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 * @brief Module that contains core of the nRF IEEE 802.15.4 radio driver. 37 * 38 */ 39 40 #ifndef NRF_802154_CORE_H_ 41 #define NRF_802154_CORE_H_ 42 43 #include <stdbool.h> 44 #include <stdint.h> 45 46 #include "nrf_802154_config.h" 47 #include "nrf_802154_notification.h" 48 #include "nrf_802154_rx_buffer.h" 49 #include "nrf_802154_types_internal.h" 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** 56 * @brief States of the nRF 802.15.4 driver. 57 */ 58 typedef enum 59 { 60 // Sleep 61 RADIO_STATE_SLEEP, ///< Low power mode (disabled) - the only state in which all radio preconditions are not requested. 62 RADIO_STATE_FALLING_ASLEEP, ///< Before entering the sleep state, all radio preconditions are requested. 63 64 // Receive 65 RADIO_STATE_RX, ///< The receiver is enabled and it is receiving frames. 66 RADIO_STATE_TX_ACK, ///< The frame is received and the ACK is being transmitted. 67 68 // Transmit 69 RADIO_STATE_CCA_TX, ///< Performing CCA followed by the frame transmission. 70 RADIO_STATE_TX, ///< Transmitting data frame (or beacon). 71 RADIO_STATE_RX_ACK, ///< Receiving ACK after the transmitted frame. 72 73 // Energy Detection 74 RADIO_STATE_ED, ///< Performing the energy detection procedure. 75 76 // CCA 77 RADIO_STATE_CCA, ///< Performing the CCA procedure. 78 79 #if NRF_802154_CARRIER_FUNCTIONS_ENABLED 80 // Continuous carrier 81 RADIO_STATE_CONTINUOUS_CARRIER, ///< Emitting the continuous carrier wave. 82 83 // Modulated carrier 84 RADIO_STATE_MODULATED_CARRIER ///< Emitting the modulated carrier signal. 85 #endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED 86 87 } radio_state_t; 88 89 /** 90 * @brief Initializes the 802.15.4 driver core. 91 */ 92 void nrf_802154_core_init(void); 93 94 /** 95 * @brief Deinitializes the 802.15.4 driver core. 96 */ 97 void nrf_802154_core_deinit(void); 98 99 /** 100 * @brief Gets the current state of the nRF 802.15.4 driver. 101 * 102 * @returns Current state of the 802.15.4 driver. 103 */ 104 radio_state_t nrf_802154_core_state_get(void); 105 106 /*************************************************************************************************** 107 * @section State machine transition requests 108 **************************************************************************************************/ 109 110 /** 111 * @brief Requests the transition to the @ref RADIO_STATE_SLEEP state. 112 * 113 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 114 * 115 * @retval true Entering the sleep state succeeded. 116 * @retval false Entering the sleep state failed (the driver is performing other procedure). 117 */ 118 bool nrf_802154_core_sleep(nrf_802154_term_t term_lvl); 119 120 /** 121 * @brief Requests the transition to the @ref RADIO_STATE_RX state. 122 * 123 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 124 * @param[in] req_orig Module that originates this request. 125 * @param[in] notify_function Function called to notify the status of this procedure. May be NULL. 126 * @param[in] notify_abort If abort notification is to be triggered. 127 * @param[in] id Identifier of reception window. 128 * 129 * @retval true Entering the receive state succeeded. 130 * @retval false Entering the receive state failed (the driver is performing other procedure). 131 */ 132 bool nrf_802154_core_receive(nrf_802154_term_t term_lvl, 133 req_originator_t req_orig, 134 nrf_802154_notification_func_t notify_function, 135 bool notify_abort, 136 uint32_t id); 137 138 /** 139 * @brief Requests the transition to the @ref RADIO_STATE_TX state. 140 * 141 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 142 * @param[in] req_orig Module that originates this request. 143 * @param[in] p_data Pointer to a frame to transmit. 144 * @param[in] p_params Pointer to transmission parameters. 145 * @param[in] notify_function Function called to notify the status of this procedure. May be NULL. 146 * 147 * @retval true Entering the transmit state succeeded. 148 * @retval false Entering the transmit state failed (the driver is performing other procedure). 149 */ 150 bool nrf_802154_core_transmit(nrf_802154_term_t term_lvl, 151 req_originator_t req_orig, 152 uint8_t * p_data, 153 nrf_802154_transmit_params_t * p_params, 154 nrf_802154_notification_func_t notify_function); 155 156 /** 157 * @brief Requests the transition to the @ref RADIO_STATE_ED state. 158 * 159 * When the energy detection procedure is finished, the driver transitions 160 * to the @ref RADIO_STATE_RX state. 161 * 162 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 163 * @param[in] time_us Minimal time of energy detection procedure. 164 * 165 * @retval true Entering the energy detection state succeeded. 166 * @retval false Entering the energy detection state failed 167 * (the driver is performing other procedure). 168 */ 169 bool nrf_802154_core_energy_detection(nrf_802154_term_t term_lvl, uint32_t time_us); 170 171 /** 172 * @brief Requests the transition to the @ref RADIO_STATE_CCA state. 173 * 174 * When the CCA procedure is finished, the driver transitions to the @ref RADIO_STATE_RX state. 175 * 176 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 177 * 178 * @retval true Entering the CCA state succeeded. 179 * @retval false Entering the CCA state failed (the driver is performing other procedure). 180 */ 181 bool nrf_802154_core_cca(nrf_802154_term_t term_lvl); 182 183 #if NRF_802154_CARRIER_FUNCTIONS_ENABLED 184 185 /** 186 * @brief Requests the transition to the @ref RADIO_STATE_CONTINUOUS_CARRIER state. 187 * 188 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 189 * 190 * @retval true Entering the continuous carrier state succeeded. 191 * @retval false Entering the continuous carrier state failed 192 * (the driver is performing other procedure). 193 */ 194 bool nrf_802154_core_continuous_carrier(nrf_802154_term_t term_lvl); 195 196 /** 197 * @brief Requests the transition to the @ref RADIO_STATE_MODULATED_CARRIER state. 198 * 199 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 200 * @param[in] p_data Data buffer to modulate the carrier with. 201 * 202 * @retval true Entering the modulated carrier state succeeded. 203 * @retval false Entering the modulated carrier state failed 204 * (the driver is performing other procedure). 205 */ 206 bool nrf_802154_core_modulated_carrier(nrf_802154_term_t term_lvl, 207 const uint8_t * p_data); 208 209 #endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED 210 211 /*************************************************************************************************** 212 * @section State machine notifications 213 **************************************************************************************************/ 214 215 /** 216 * @brief Notifies the core module that a higher layer freed a frame buffer. 217 * 218 * When there are no free buffers available, the core does not start the receiver. 219 * If the core receives this notification, it changes the internal state to make sure 220 * the receiver is started if requested. 221 * 222 * @param[in] p_data Pointer to buffer that has been freed. 223 */ 224 bool nrf_802154_core_notify_buffer_free(uint8_t * p_data); 225 226 /** 227 * @brief Notifies the core module that the next higher layer requested the change of the channel. 228 * 229 * The core is expected to update the frequency register of the peripheral and, if it is 230 * in the @ref RADIO_STATE_RX, in the @ref RADIO_STATE_CONTINUOUS_CARRIER 231 * or in the @ref RADIO_STATE_MODULATED_CARRIER state, the transceiver is disabled 232 * and enabled again to use the new channel. 233 * 234 * @param[in] req_orig Module that originates this request. 235 */ 236 bool nrf_802154_core_channel_update(req_originator_t req_orig); 237 238 /** 239 * @brief Notifies the core module that the next higher layer requested the change 240 * of the CCA configuration. 241 */ 242 bool nrf_802154_core_cca_cfg_update(void); 243 244 /** 245 * @brief Notifies the core module that the next higher layer requested the RSSI measurement. 246 */ 247 bool nrf_802154_core_rssi_measure(void); 248 249 /** 250 * @brief Gets the last RSSI measurement. 251 * 252 * @param[out] p_rssi RSSI measurement value in dBm. 253 */ 254 bool nrf_802154_core_last_rssi_measurement_get(int8_t * p_rssi); 255 256 /** 257 * Get RSSI of the last received non-ACK frame. 258 * 259 * Returns 0 if no frame was received yet. 260 * 261 * @returns Temperature-corrected RSSI of the last received frame 262 */ 263 int8_t nrf_802154_core_last_frame_rssi_get(void); 264 265 /** 266 * Get LQI of the last received non-ACK frame. 267 * 268 * Returns 0 if no frame was received yet. 269 * 270 * @returns Temperature-corrected LQI of the last received frame 271 */ 272 uint8_t nrf_802154_core_last_frame_lqi_get(void); 273 274 /** 275 * @brief Notifies the core module that the next higher layer requested the change of the antenna. 276 */ 277 bool nrf_802154_core_antenna_update(void); 278 279 #if !NRF_802154_INTERNAL_IRQ_HANDLING 280 /** 281 * @brief Notifies the core module that there is a pending IRQ to be handled. 282 */ 283 void nrf_802154_core_irq_handler(void); 284 #endif // !NRF_802154_INTERNAL_IRQ_HANDLING 285 286 #ifdef __cplusplus 287 } 288 #endif 289 290 #endif /* NRF_802154_CORE_H_ */ 291
