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 * @brief Module that implements the storage of PIB attributes in the nRF 802.15.4 radio driver. 37 * 38 */ 39 40 #ifndef NRF_802154_PIB_H_ 41 #define NRF_802154_PIB_H_ 42 43 #include <stdbool.h> 44 #include <stdint.h> 45 46 #include "nrf_802154.h" 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * @brief Initializes this module. 54 */ 55 void nrf_802154_pib_init(void); 56 57 /** 58 * @brief Checks if the promiscuous mode is enabled. 59 * 60 * @retval true The promiscuous mode is enabled. 61 * @retval false The promiscuous mode is disabled. 62 */ 63 bool nrf_802154_pib_promiscuous_get(void); 64 65 /** 66 * @brief Enables or disables the promiscuous mode. 67 * 68 * @param[in] enabled If the promiscuous mode is to be enabled. 69 */ 70 void nrf_802154_pib_promiscuous_set(bool enabled); 71 72 /** 73 * @brief Checks if the RxOnWhenIdle mode is enabled. 74 * 75 * @retval true The RxOnWhenIdle mode is enabled. 76 * @retval false The RxOnWhenIdle mode is disabled. 77 */ 78 bool nrf_802154_pib_rx_on_when_idle_get(void); 79 80 /** 81 * @brief Enables or disables the RxOnWhenIdle mode. 82 * 83 * @param[in] enabled If the RxOnWhenIdle mode is to be enabled. 84 */ 85 void nrf_802154_pib_rx_on_when_idle_set(bool enabled); 86 87 /** 88 * @brief Checks if the auto ACK procedure is enabled. 89 * 90 * @retval true The auto ACK procedure is enabled. 91 * @retval false The auto ACK procedure is disabled. 92 */ 93 bool nrf_802154_pib_auto_ack_get(void); 94 95 /** 96 * @brief Enables or disables the auto ACK procedure. 97 * 98 * @param[in] enabled If the auto ACK procedure is to be enabled. 99 */ 100 void nrf_802154_pib_auto_ack_set(bool enabled); 101 102 /** 103 * @brief Checks if the radio is configured as the PAN coordinator. 104 * 105 * @retval true The radio is configured as the PAN coordinator. 106 * @retval false The radio is not configured as the PAN coordinator. 107 */ 108 bool nrf_802154_pib_pan_coord_get(void); 109 110 /** 111 * @brief Configures the device as the PAN coordinator. 112 * 113 * @param[in] enabled If the radio is configured as the PAN coordinator. 114 */ 115 void nrf_802154_pib_pan_coord_set(bool enabled); 116 117 /** 118 * @brief Gets the currently used channel. 119 * 120 * @returns Channel number used by the driver. 121 */ 122 uint8_t nrf_802154_pib_channel_get(void); 123 124 /** 125 * @brief Sets the channel that will be used by the driver. 126 * 127 * @param[in] channel Number of the channel used by the driver. 128 */ 129 void nrf_802154_pib_channel_set(uint8_t channel); 130 131 /** 132 * @brief Gets the transmit power. 133 * 134 * @returns Transmit power in dBm. 135 */ 136 int8_t nrf_802154_pib_tx_power_get(void); 137 138 /** 139 * @brief Sets the transmit power used for ACK frames. 140 * 141 * @param[in] dbm Transmit power in dBm. 142 */ 143 void nrf_802154_pib_tx_power_set(int8_t dbm); 144 145 /** 146 * @brief Gets the PAN ID used by this device. 147 * 148 * @returns Pointer to the buffer containing the PAN ID value (2 bytes, little-endian). 149 */ 150 const uint8_t * nrf_802154_pib_pan_id_get(void); 151 152 /** 153 * @brief Sets the PAN ID used by this device. 154 * 155 * @param[in] p_pan_id Pointer to the PAN ID (2 bytes, little-endian). 156 * 157 * This function makes a copy of the PAN ID. 158 */ 159 void nrf_802154_pib_pan_id_set(const uint8_t * p_pan_id); 160 161 /** 162 * @brief Gets the extended address of this device. 163 * 164 * @returns Pointer to the buffer containing the extended address (8 bytes, little-endian). 165 */ 166 const uint8_t * nrf_802154_pib_extended_address_get(void); 167 168 /** 169 * @brief Sets the extended address of this device. 170 * 171 * @param[in] p_extended_address Pointer to extended address (8 bytes, little-endian). 172 * 173 * This function makes a copy of the address. 174 */ 175 void nrf_802154_pib_extended_address_set(const uint8_t * p_extended_address); 176 177 /** 178 * @brief Gets the short address of this device. 179 * 180 * @returns Pointer to the buffer containing the short address (2 bytes, little-endian). 181 */ 182 const uint8_t * nrf_802154_pib_short_address_get(void); 183 184 /** 185 * @brief Sets the short address of this device. 186 * 187 * @param[in] p_short_address Pointer to the short address (2 bytes, little-endian). 188 * 189 * This function makes a copy of the address. 190 */ 191 void nrf_802154_pib_short_address_set(const uint8_t * p_short_address); 192 193 /** 194 * @brief Sets the radio CCA mode and threshold. 195 * 196 * @param[in] p_cca_cfg Pointer to the CCA configuration structure. Only fields relevant 197 * to the selected mode are updated. 198 */ 199 void nrf_802154_pib_cca_cfg_set(const nrf_802154_cca_cfg_t * p_cca_cfg); 200 201 /** 202 * @brief Gets the current radio CCA configuration. 203 * 204 * @param[out] p_cca_cfg Pointer to the structure for the current CCA configuration. 205 */ 206 void nrf_802154_pib_cca_cfg_get(nrf_802154_cca_cfg_t * p_cca_cfg); 207 208 /** 209 * @brief Sets Coex request mode used in receive operations. 210 * 211 * @param[in] mode Coex receive request mode. 212 * 213 * @retval true When value provided by @p mode param is supported. 214 * @retval false Otherwise. 215 */ 216 bool nrf_802154_pib_coex_rx_request_mode_set(nrf_802154_coex_rx_request_mode_t mode); 217 218 /** 219 * @brief Gets Coex request mode used in receive operations. 220 * 221 * @return Current Coex receive request mode. 222 */ 223 nrf_802154_coex_rx_request_mode_t nrf_802154_pib_coex_rx_request_mode_get(void); 224 225 /** 226 * @brief Sets Coex request mode used in transmit operations. 227 * 228 * @param[in] mode Coex transmit request mode. 229 * 230 * @retval true When value provided by @p mode param is supported. 231 * @retval false Otherwise. 232 */ 233 bool nrf_802154_pib_coex_tx_request_mode_set(nrf_802154_coex_tx_request_mode_t mode); 234 235 /** 236 * @brief Gets Coex request mode used in transmit operations. 237 * 238 * @return Current Coex transmit request mode. 239 */ 240 nrf_802154_coex_tx_request_mode_t nrf_802154_pib_coex_tx_request_mode_get(void); 241 242 #if NRF_802154_CSMA_CA_ENABLED 243 /** 244 * @brief Sets the minimum value of the backoff exponent (BE) in the CSMA-CA algorithm. 245 * 246 * @param[in] min_be Minimum value of the backoff exponent. 247 * 248 * @retval true When value provided by @p min_be does not exceed the implementation limit ( <= 8). 249 * @retval false Otherwise. 250 */ 251 bool nrf_802154_pib_csmaca_min_be_set(uint8_t min_be); 252 253 /** 254 * @brief Gets the minimum value of the backoff exponent (BE) in the CSMA-CA algorithm. 255 * 256 * @return Current minimum value of the backoff exponent. 257 */ 258 uint8_t nrf_802154_pib_csmaca_min_be_get(void); 259 260 /** 261 * @brief Sets the maximum value of the backoff exponent (BE) in the CSMA-CA algorithm. 262 * 263 * @param[in] max_be Maximum value of the backoff exponent. 264 * 265 * @retval true When value provided by @p max_be does not exceed the implementation limit ( <= 8). 266 * @retval false Otherwise. 267 */ 268 bool nrf_802154_pib_csmaca_max_be_set(uint8_t max_be); 269 270 /** 271 * @brief Gets the maximum value of the backoff exponent (BE) in the CSMA-CA algorithm. 272 * 273 * @return Current maximum value of the backoff exponent. 274 */ 275 uint8_t nrf_802154_pib_csmaca_max_be_get(void); 276 277 /** 278 * @brief Sets the maximum number of backoffs the CSMA-CA algorithm will attempt before declaring 279 * a channel access failure. 280 * 281 * @param[in] max_backoffs Maximum number of backoffs. 282 */ 283 void nrf_802154_pib_csmaca_max_backoffs_set(uint8_t max_backoffs); 284 285 /** 286 * @brief Gets the maximum number of backoffs the CSMA-CA algorithm will attempt before declaring 287 * a channel access failure. 288 * 289 * @return Current maximum number of backoffs. 290 */ 291 uint8_t nrf_802154_pib_csmaca_max_backoffs_get(void); 292 #endif // NRF_802154_CSMA_CA_ENABLED 293 294 #if NRF_802154_IFS_ENABLED 295 /** 296 * @brief Gets IFS operation mode. 297 * 298 * @return Current IFS operation mode. Refer to @ref nrf_802154_ifs_mode_t for details. 299 */ 300 nrf_802154_ifs_mode_t nrf_802154_pib_ifs_mode_get(void); 301 302 /** 303 * @brief Sets IFS operation mode. 304 * 305 * @param[in] mode IFS operation mode. Refer to @ref nrf_802154_ifs_mode_t for details. 306 * 307 * @retval true The update of PIB was successful. 308 * @retval false The update of PIB failed due to the unsupported mode. 309 */ 310 bool nrf_802154_pib_ifs_mode_set(nrf_802154_ifs_mode_t mode); 311 312 /** 313 * @brief Gets Short IFS period in microseconds. 314 * 315 * @return Current Short IFS period in microseconds. 316 */ 317 uint16_t nrf_802154_pib_ifs_min_sifs_period_get(void); 318 319 /** 320 * @brief Sets Short IFS period in microseconds. 321 * 322 * @param[in] period Short IFS period in microseconds. 323 * 324 * @note The period cannot be smaller than aTurnaroundTime. 325 */ 326 void nrf_802154_pib_ifs_min_sifs_period_set(uint16_t period); 327 328 /** 329 * @brief Gets Long IFS period in microseconds. 330 * 331 * @return Current Long IFS period in microseconds. 332 */ 333 uint16_t nrf_802154_pib_ifs_min_lifs_period_get(void); 334 335 /** 336 * @brief Sets Long IFS period in microseconds. 337 * 338 * @param[in] period Long IFS period in microseconds. 339 */ 340 void nrf_802154_pib_ifs_min_lifs_period_set(uint16_t period); 341 #endif // NRF_802154_IFS_ENABLED 342 343 #if NRF_802154_TEST_MODES_ENABLED 344 /** 345 * @brief Gets the current CSMA/CA backoff test mode. 346 * 347 * @return Current CSMA/CA backoff test mode. 348 */ 349 nrf_802154_test_mode_csmaca_backoff_t nrf_802154_pib_test_mode_csmaca_backoff_get(void); 350 351 /** 352 * @brief Sets the csmaca backoff test mode. 353 * 354 * @param[in] value CSMA/CA backoff test mode. 355 */ 356 void nrf_802154_pib_test_mode_csmaca_backoff_set(nrf_802154_test_mode_csmaca_backoff_t value); 357 358 #endif // NRF_802154_TEST_MODES_ENABLED 359 360 #ifdef __cplusplus 361 } 362 #endif 363 364 #endif /* NRF_802154_PIB_H_ */ 365
