mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_TB_SENSE_1/TOOLCHAIN_IAR/rail_ieee802154.h@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_TB_SENSE_12/TARGET_Silicon_Labs/TARGET_SL_RAIL/efr32-rf-driver/rail/ieee802154/rail_ieee802154.h@167:84c0a372a020 
mbed library. Release version 164

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Anna Bridge 142:4eea097334d6 1 /***************************************************************************//**
Anna Bridge 142:4eea097334d6 2 * @file rail_ieee802154.h
Anna Bridge 142:4eea097334d6 3 * @brief The IEEE 802.15.4 specific header file for the RAIL library.
AnnaBridge 167:84c0a372a020 4 * @copyright Copyright 2016 Silicon Laboratories, Inc. www.silabs.com
Anna Bridge 142:4eea097334d6 5 ******************************************************************************/
Anna Bridge 142:4eea097334d6 6
Anna Bridge 142:4eea097334d6 7 #ifndef __RAIL_IEEE802154_H__
Anna Bridge 142:4eea097334d6 8 #define __RAIL_IEEE802154_H__
Anna Bridge 142:4eea097334d6 9
Anna Bridge 160:5571c4ff569f 10 #include "rail_types.h"
Anna Bridge 142:4eea097334d6 11
AnnaBridge 167:84c0a372a020 12 #ifdef __cplusplus
AnnaBridge 167:84c0a372a020 13 extern "C" {
AnnaBridge 167:84c0a372a020 14 #endif
AnnaBridge 167:84c0a372a020 15
AnnaBridge 167:84c0a372a020 16 /// @addtogroup IEEE802_15_4 IEEE 802.15.4
AnnaBridge 167:84c0a372a020 17 /// @ingroup Protocol_Specific
AnnaBridge 167:84c0a372a020 18 /// @brief IEEE 802.15.4 configuration routines
AnnaBridge 167:84c0a372a020 19 ///
AnnaBridge 167:84c0a372a020 20 /// The functions in this group configure RAIL IEEE 802.15.4 hardware
AnnaBridge 167:84c0a372a020 21 /// acceleration which includes IEEE 802.15.4 format filtering, address
AnnaBridge 167:84c0a372a020 22 /// filtering, acking, and filtering based on the frame type.
AnnaBridge 167:84c0a372a020 23 ///
AnnaBridge 167:84c0a372a020 24 /// To configure IEEE 802.15.4 functionality, the application must first setup
AnnaBridge 167:84c0a372a020 25 /// a RAIL instance as normal with RAIL_Init() and other setup functions.
AnnaBridge 167:84c0a372a020 26 /// Instead of RAIL_ConfigChannels() and RAIL_ConfigRadio(), however, an
AnnaBridge 167:84c0a372a020 27 /// application may use RAIL_IEEE802154_Config2p4GHzRadio() to setup the
AnnaBridge 167:84c0a372a020 28 /// official IEEE 2.4GHz 802.15.4 PHY. This configuration is shown below.
AnnaBridge 167:84c0a372a020 29 ///
AnnaBridge 167:84c0a372a020 30 /// @code{.c}
AnnaBridge 167:84c0a372a020 31 /// static RAIL_Handle_t railHandle = NULL; // Initialized somewhere else
AnnaBridge 167:84c0a372a020 32 ///
AnnaBridge 167:84c0a372a020 33 /// static const RAIL_IEEE802154_Config_t rail154Config = {
AnnaBridge 167:84c0a372a020 34 /// .addresses = NULL,
AnnaBridge 167:84c0a372a020 35 /// .ackConfig = {
AnnaBridge 167:84c0a372a020 36 /// .enable = true, // Turn on auto ACK for IEEE 802.15.4
AnnaBridge 167:84c0a372a020 37 /// .ackTimeout = 864, // 54 symbols * 16 us/symbol = 864 us
AnnaBridge 167:84c0a372a020 38 /// .rxTransitions = {
AnnaBridge 167:84c0a372a020 39 /// .success = RAIL_RF_STATE_TX, // Go to Tx to send the ACK
AnnaBridge 167:84c0a372a020 40 /// .error = RAIL_RF_STATE_RX, // For an always on device stay in Rx
AnnaBridge 167:84c0a372a020 41 /// },
AnnaBridge 167:84c0a372a020 42 /// .txTransitions = {
AnnaBridge 167:84c0a372a020 43 /// .success = RAIL_RF_STATE_RX, // Go to Rx for receiving the ACK
AnnaBridge 167:84c0a372a020 44 /// .error = RAIL_RF_STATE_RX, // For an always on device stay in Rx
AnnaBridge 167:84c0a372a020 45 /// },
AnnaBridge 167:84c0a372a020 46 /// },
AnnaBridge 167:84c0a372a020 47 /// .timings = {
AnnaBridge 167:84c0a372a020 48 /// .idleToRx = 100,
AnnaBridge 167:84c0a372a020 49 /// .idleToTx = 100,
AnnaBridge 167:84c0a372a020 50 /// .rxToTx = 192, // 12 symbols * 16 us/symbol = 192 us
AnnaBridge 167:84c0a372a020 51 /// .txToRx = 192, // 12 symbols * 16 us/symbol = 192 us
AnnaBridge 167:84c0a372a020 52 /// .rxSearchTimeout = 0, // not used
AnnaBridge 167:84c0a372a020 53 /// .txToRxSearchTimeout = 0, // not used
AnnaBridge 167:84c0a372a020 54 /// },
AnnaBridge 167:84c0a372a020 55 /// .framesMask = RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES,
AnnaBridge 167:84c0a372a020 56 /// .promiscuousMode = false, // Enable format and address filtering
AnnaBridge 167:84c0a372a020 57 /// .isPanCoordinator = false,
AnnaBridge 167:84c0a372a020 58 /// };
AnnaBridge 167:84c0a372a020 59 ///
AnnaBridge 167:84c0a372a020 60 /// void config154(void)
AnnaBridge 167:84c0a372a020 61 /// {
AnnaBridge 167:84c0a372a020 62 /// // Configure the radio and channels for 2.4GHz IEEE 802.15.4
AnnaBridge 167:84c0a372a020 63 /// RAIL_IEEE802154_Config2p4GHzRadio(railHandle);
AnnaBridge 167:84c0a372a020 64 /// // Initialize the IEEE 802.15.4 config using the static config above
AnnaBridge 167:84c0a372a020 65 /// RAIL_IEEE802154_Init(railHandle, &rail154Config);
AnnaBridge 167:84c0a372a020 66 /// }
AnnaBridge 167:84c0a372a020 67 /// @endcode
AnnaBridge 167:84c0a372a020 68 ///
AnnaBridge 167:84c0a372a020 69 /// To configure address filtering the application can call
AnnaBridge 167:84c0a372a020 70 /// RAIL_IEEE802154_SetAddresses() with a structure containing all addresses or
AnnaBridge 167:84c0a372a020 71 /// can call the individual RAIL_IEEE802154_SetPanId(),
AnnaBridge 167:84c0a372a020 72 /// RAIL_IEEE802154_SetShortAddress(), and RAIL_IEEE802154_SetLongAddress()
AnnaBridge 167:84c0a372a020 73 /// APIs. RAIL supports \ref RAIL_IEEE802154_MAX_ADDRESSES number of address
AnnaBridge 167:84c0a372a020 74 /// pairs for situations where you want to receive packets from multiple IEEE
AnnaBridge 167:84c0a372a020 75 /// 802.15.4 networks at the same time. Broadcast addresses are supported by
AnnaBridge 167:84c0a372a020 76 /// default without any additional configuration so they do not consume one of
AnnaBridge 167:84c0a372a020 77 /// these slots. If the application does not require all address pairs be sure
AnnaBridge 167:84c0a372a020 78 /// to set unused ones to the proper disabled value for each type. These can
AnnaBridge 167:84c0a372a020 79 /// be found in the \ref RAIL_IEEE802154_AddrConfig_t documentation. Below is
AnnaBridge 167:84c0a372a020 80 /// an example of setting filtering for one set of addresses.
AnnaBridge 167:84c0a372a020 81 ///
AnnaBridge 167:84c0a372a020 82 /// @code{.c}
AnnaBridge 167:84c0a372a020 83 /// // PanID OTA value of 0x34 0x12
AnnaBridge 167:84c0a372a020 84 /// // Short Address OTA byte order of 0x78 0x56
AnnaBridge 167:84c0a372a020 85 /// // Long address with OTA byte order of 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88
AnnaBridge 167:84c0a372a020 86 ///
AnnaBridge 167:84c0a372a020 87 /// // Setup all address simultaneously
AnnaBridge 167:84c0a372a020 88 /// RAIL_Status_t setup1(void)
AnnaBridge 167:84c0a372a020 89 /// {
AnnaBridge 167:84c0a372a020 90 /// RAIL_IEEE802154_AddrConfig_t nodeAddress = {
AnnaBridge 167:84c0a372a020 91 /// { 0x1234, 0xFFFF, 0xFFFF },
AnnaBridge 167:84c0a372a020 92 /// { 0x5678, 0xFFFF, 0xFFFF },
AnnaBridge 167:84c0a372a020 93 /// { { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88 },
AnnaBridge 167:84c0a372a020 94 /// { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 },
AnnaBridge 167:84c0a372a020 95 /// { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 } }
AnnaBridge 167:84c0a372a020 96 /// };
AnnaBridge 167:84c0a372a020 97 /// return RAIL_IEEE802154_SetAddresses(railHandle, &nodeAddress);
AnnaBridge 167:84c0a372a020 98 /// }
AnnaBridge 167:84c0a372a020 99 ///
AnnaBridge 167:84c0a372a020 100 /// // Alternatively the addresses can be setup individually as follows:
AnnaBridge 167:84c0a372a020 101 /// RAIL_Status_t setup2(void)
AnnaBridge 167:84c0a372a020 102 /// {
AnnaBridge 167:84c0a372a020 103 /// RAIL_Status_t status;
AnnaBridge 167:84c0a372a020 104 /// const uint8_t longAddress[] = { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88 };
AnnaBridge 167:84c0a372a020 105 ///
AnnaBridge 167:84c0a372a020 106 /// status = RAIL_IEEE802154_SetPanId(railHandle, 0x1234, 0);
AnnaBridge 167:84c0a372a020 107 /// if (status != RAIL_STATUS_NO_ERROR) {
AnnaBridge 167:84c0a372a020 108 /// return status
AnnaBridge 167:84c0a372a020 109 /// }
AnnaBridge 167:84c0a372a020 110 /// status = RAIL_IEEE802154_SetShortAddress(railHandle, 0x5678, 0);
AnnaBridge 167:84c0a372a020 111 /// if (status != RAIL_STATUS_NO_ERROR) {
AnnaBridge 167:84c0a372a020 112 /// return status
AnnaBridge 167:84c0a372a020 113 /// }
AnnaBridge 167:84c0a372a020 114 /// status = RAIL_IEEE802154_SetLongAddress(railHandle, longAddress, 0);
AnnaBridge 167:84c0a372a020 115 /// if (status != RAIL_STATUS_NO_ERROR) {
AnnaBridge 167:84c0a372a020 116 /// return status
AnnaBridge 167:84c0a372a020 117 /// }
AnnaBridge 167:84c0a372a020 118 ///
AnnaBridge 167:84c0a372a020 119 /// return RAIL_STATUS_NO_ERROR;
AnnaBridge 167:84c0a372a020 120 /// }
AnnaBridge 167:84c0a372a020 121 /// @endcode
AnnaBridge 167:84c0a372a020 122 ///
AnnaBridge 167:84c0a372a020 123 /// Address filtering will be enabled except when in promiscuous mode which can
AnnaBridge 167:84c0a372a020 124 /// be set with RAIL_IEEE802154_SetPromiscuousMode(). The addresses may be
AnnaBridge 167:84c0a372a020 125 /// changed at runtime but if you are receiving a packet while reconfiguring the
AnnaBridge 167:84c0a372a020 126 /// address filters you may get undesired behavior so it's safest to do this
AnnaBridge 167:84c0a372a020 127 /// while not in receive.
AnnaBridge 167:84c0a372a020 128 ///
AnnaBridge 167:84c0a372a020 129 /// Auto ACK is controlled by the ackConfig and timings fields passed to
AnnaBridge 167:84c0a372a020 130 /// RAIL_IEEE802154_Init(). After initialization though they may be controlled
AnnaBridge 167:84c0a372a020 131 /// using the normal \ref Auto_Ack and \ref State_Transitions APIs. When in IEEE
AnnaBridge 167:84c0a372a020 132 /// 802.15.4 mode the ACK will have a 5 byte length, the frame type will be set
AnnaBridge 167:84c0a372a020 133 /// to ack, and the frame pending bit will be set if
AnnaBridge 167:84c0a372a020 134 /// RAIL_IEEE802154_SetFramePending() is called when the \ref
AnnaBridge 167:84c0a372a020 135 /// RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event is triggered. This event
AnnaBridge 167:84c0a372a020 136 /// must be turned on by the user and will fire whenever a data request is being
AnnaBridge 167:84c0a372a020 137 /// received so that the stack can determine whether there is pending data. Be
AnnaBridge 167:84c0a372a020 138 /// aware that the frame pending bit must be set quickly after receiving the
AnnaBridge 167:84c0a372a020 139 /// event or the ACK may already have been transmitted. Check the return code of
AnnaBridge 167:84c0a372a020 140 /// RAIL_IEEE802154_SetFramePending() to be sure that the bit was set in time.
AnnaBridge 167:84c0a372a020 141 ///
AnnaBridge 167:84c0a372a020 142 /// Transmit and receive operations are all done using the standard RAIL APIs in
AnnaBridge 167:84c0a372a020 143 /// IEEE 802.15.4 mode. To send packets using the correct CSMA configuration
AnnaBridge 167:84c0a372a020 144 /// there is a \ref RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA define
AnnaBridge 167:84c0a372a020 145 /// that can initialize the csmaConfig structure passed to \ref
AnnaBridge 167:84c0a372a020 146 /// RAIL_StartCcaCsmaTx().
AnnaBridge 167:84c0a372a020 147 /// @{
Anna Bridge 142:4eea097334d6 148
Anna Bridge 142:4eea097334d6 149 /**
Anna Bridge 142:4eea097334d6 150 * @enum RAIL_IEEE802154_AddressLength_t
Anna Bridge 142:4eea097334d6 151 * @brief Different lengths that an 802.15.4 address can have
Anna Bridge 142:4eea097334d6 152 */
Anna Bridge 160:5571c4ff569f 153 RAIL_ENUM(RAIL_IEEE802154_AddressLength_t) {
Anna Bridge 142:4eea097334d6 154 RAIL_IEEE802154_ShortAddress = 2, /**< 2 byte short address. */
Anna Bridge 142:4eea097334d6 155 RAIL_IEEE802154_LongAddress = 3, /**< 8 byte extended address. */
Anna Bridge 160:5571c4ff569f 156 };
Anna Bridge 142:4eea097334d6 157
Anna Bridge 142:4eea097334d6 158 /**
Anna Bridge 142:4eea097334d6 159 * @struct RAIL_IEEE802154_Address_t
Anna Bridge 142:4eea097334d6 160 * @brief Representation of 802.15.4 address
Anna Bridge 142:4eea097334d6 161 * This structure is only used for a received address, which needs to be parsed
Anna Bridge 142:4eea097334d6 162 * to discover the type.
Anna Bridge 142:4eea097334d6 163 */
Anna Bridge 160:5571c4ff569f 164 typedef struct RAIL_IEEE802154_Address{
Anna Bridge 160:5571c4ff569f 165 /** Convenient storage for different address types */
Anna Bridge 160:5571c4ff569f 166 union {
Anna Bridge 160:5571c4ff569f 167 uint16_t shortAddress; /**< Present for 2 byte addresses. */
Anna Bridge 160:5571c4ff569f 168 uint8_t longAddress[8]; /**< Present for 8 byte addresses. */
Anna Bridge 160:5571c4ff569f 169 };
Anna Bridge 142:4eea097334d6 170 /**
Anna Bridge 142:4eea097334d6 171 * Enum of the received address length
Anna Bridge 142:4eea097334d6 172 */
Anna Bridge 142:4eea097334d6 173 RAIL_IEEE802154_AddressLength_t length;
Anna Bridge 142:4eea097334d6 174 } RAIL_IEEE802154_Address_t;
Anna Bridge 142:4eea097334d6 175
Anna Bridge 160:5571c4ff569f 176 /** The maximum number of allowed addresses of each type. */
Anna Bridge 160:5571c4ff569f 177 #define RAIL_IEEE802154_MAX_ADDRESSES 3
Anna Bridge 160:5571c4ff569f 178
Anna Bridge 142:4eea097334d6 179 /**
Anna Bridge 142:4eea097334d6 180 * @struct RAIL_IEEE802154_AddrConfig_t
Anna Bridge 142:4eea097334d6 181 * @brief Configuration structure for IEEE 802.15.4 Address Filtering. The
Anna Bridge 142:4eea097334d6 182 * broadcast addresses are handled separately, and do not need to be specified
Anna Bridge 160:5571c4ff569f 183 * here. Any address to be ignored should be set with all bits high.
Anna Bridge 160:5571c4ff569f 184 *
Anna Bridge 160:5571c4ff569f 185 * This structure allows configuration of dual-PAN functionality, by specifying
Anna Bridge 160:5571c4ff569f 186 * multiple PAN IDs and short addresses. A packet will be received if it
Anna Bridge 160:5571c4ff569f 187 * matches either PAN ID and the long address. The short addresses are specific
Anna Bridge 160:5571c4ff569f 188 * to a given PAN, so the first short address goes with the first PAN ID, and
Anna Bridge 160:5571c4ff569f 189 * not with the second PAN ID. The broadcast PAN ID and address will work with
Anna Bridge 160:5571c4ff569f 190 * any address or PAN ID, respectively.
Anna Bridge 142:4eea097334d6 191 */
Anna Bridge 160:5571c4ff569f 192 typedef struct RAIL_IEEE802154_AddrConfig{
Anna Bridge 160:5571c4ff569f 193 /**
Anna Bridge 160:5571c4ff569f 194 * PAN IDs for destination filtering. Both must be specified.
Anna Bridge 160:5571c4ff569f 195 * To disable a PAN ID, set it to the broadcast value, 0xFFFF.
Anna Bridge 160:5571c4ff569f 196 */
Anna Bridge 160:5571c4ff569f 197 uint16_t panId[RAIL_IEEE802154_MAX_ADDRESSES];
Anna Bridge 160:5571c4ff569f 198 /**
Anna Bridge 160:5571c4ff569f 199 * Short network addresses for destination filtering. Both must be specified.
Anna Bridge 160:5571c4ff569f 200 * To disable a short address, set it to the broadcast value, 0xFFFF.
Anna Bridge 160:5571c4ff569f 201 */
Anna Bridge 160:5571c4ff569f 202 uint16_t shortAddr[RAIL_IEEE802154_MAX_ADDRESSES];
Anna Bridge 160:5571c4ff569f 203 /**
Anna Bridge 160:5571c4ff569f 204 * 64 bit address for destination filtering. Both must be specified.
Anna Bridge 160:5571c4ff569f 205 * This field is parsed in over-the-air (OTA) byte order. To disable a long
Anna Bridge 160:5571c4ff569f 206 * address, set it to the reserved value of 0x00 00 00 00 00 00 00 00.
Anna Bridge 160:5571c4ff569f 207 */
Anna Bridge 160:5571c4ff569f 208 uint8_t longAddr[RAIL_IEEE802154_MAX_ADDRESSES][8];
Anna Bridge 142:4eea097334d6 209 } RAIL_IEEE802154_AddrConfig_t;
Anna Bridge 142:4eea097334d6 210
Anna Bridge 142:4eea097334d6 211 /**
Anna Bridge 142:4eea097334d6 212 * @struct RAIL_IEEE802154_Config_t
Anna Bridge 142:4eea097334d6 213 * @brief Configuration structure for IEEE 802.15.4 in RAIL
Anna Bridge 142:4eea097334d6 214 */
Anna Bridge 142:4eea097334d6 215 typedef struct RAIL_IEEE802154_Config {
Anna Bridge 142:4eea097334d6 216 /**
Anna Bridge 160:5571c4ff569f 217 * Configure the RAIL Address Filter to allow the given destination
Anna Bridge 160:5571c4ff569f 218 * addresses. If addresses is NULL, defer destination address configuration.
Anna Bridge 160:5571c4ff569f 219 * If a member of addresses is NULL, defer configuration of just that member.
Anna Bridge 160:5571c4ff569f 220 * This can be overridden via RAIL_IEEE802154_SetAddresses(), or the
Anna Bridge 160:5571c4ff569f 221 * individual members can be changed via RAIL_IEEE802154_SetPanId(),
Anna Bridge 160:5571c4ff569f 222 * RAIL_IEEE802154_SetShortAddress(), and RAIL_IEEE802154_SetLongAddress().
Anna Bridge 160:5571c4ff569f 223 */
Anna Bridge 160:5571c4ff569f 224 const RAIL_IEEE802154_AddrConfig_t *addresses;
Anna Bridge 160:5571c4ff569f 225 /**
Anna Bridge 160:5571c4ff569f 226 * Defines the acking configuration for the IEEE 802.15.4 implementation
Anna Bridge 160:5571c4ff569f 227 */
Anna Bridge 160:5571c4ff569f 228 RAIL_AutoAckConfig_t ackConfig;
Anna Bridge 160:5571c4ff569f 229 /**
Anna Bridge 160:5571c4ff569f 230 * Defines state timings for the IEEE 802.15.4 implementation
Anna Bridge 160:5571c4ff569f 231 */
Anna Bridge 160:5571c4ff569f 232 RAIL_StateTiming_t timings;
Anna Bridge 160:5571c4ff569f 233 /**
Anna Bridge 160:5571c4ff569f 234 * Set which 802.15.4 frame types will be received, of Beacon, Data, Ack, and
Anna Bridge 160:5571c4ff569f 235 * Command. This setting can be overridden via RAIL_IEEE802154_AcceptFrames().
Anna Bridge 160:5571c4ff569f 236 */
Anna Bridge 160:5571c4ff569f 237 uint8_t framesMask;
Anna Bridge 160:5571c4ff569f 238 /**
Anna Bridge 142:4eea097334d6 239 * Enable promiscuous mode during configuration. This can be overridden via
Anna Bridge 142:4eea097334d6 240 * RAIL_IEEE802154_SetPromiscuousMode() afterwards.
Anna Bridge 142:4eea097334d6 241 */
Anna Bridge 142:4eea097334d6 242 bool promiscuousMode;
Anna Bridge 142:4eea097334d6 243 /**
Anna Bridge 142:4eea097334d6 244 * Set whether the device is a PAN Coordinator during configuration. This can
Anna Bridge 142:4eea097334d6 245 * be overridden via RAIL_IEEE802154_SetPanCoordinator() afterwards.
Anna Bridge 142:4eea097334d6 246 */
Anna Bridge 142:4eea097334d6 247 bool isPanCoordinator;
Anna Bridge 142:4eea097334d6 248 } RAIL_IEEE802154_Config_t;
Anna Bridge 142:4eea097334d6 249
Anna Bridge 142:4eea097334d6 250 /**
Anna Bridge 142:4eea097334d6 251 * Initialize RAIL for IEEE802.15.4 features
Anna Bridge 142:4eea097334d6 252 *
Anna Bridge 160:5571c4ff569f 253 * @param[in] railHandle Handle of RAIL instance
AnnaBridge 167:84c0a372a020 254 * @param[in] fifteenFourConfig IEEE802154 configuration struct
Anna Bridge 160:5571c4ff569f 255 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 256 *
Anna Bridge 142:4eea097334d6 257 * This function calls the following RAIL functions to configure the radio for
Anna Bridge 142:4eea097334d6 258 * IEEE802.15.4 features.
Anna Bridge 142:4eea097334d6 259 *
Anna Bridge 142:4eea097334d6 260 * Initializes the following:
Anna Bridge 142:4eea097334d6 261 * - Enables IEEE802154 hardware acceleration
Anna Bridge 142:4eea097334d6 262 * - Configures RAIL Auto Ack functionality
Anna Bridge 142:4eea097334d6 263 * - Configures RAIL Address Filter for 802.15.4 address filtering
Anna Bridge 142:4eea097334d6 264 *
Anna Bridge 142:4eea097334d6 265 * It calls the following functions:
Anna Bridge 160:5571c4ff569f 266 * - RAIL_ConfigAutoAck()
Anna Bridge 142:4eea097334d6 267 * - RAIL_SetRxTransitions()
Anna Bridge 142:4eea097334d6 268 * - RAIL_SetTxTransitions()
Anna Bridge 142:4eea097334d6 269 * - RAIL_SetStateTiming()
Anna Bridge 160:5571c4ff569f 270 * - RAIL_ConfigAddressFilter()
Anna Bridge 160:5571c4ff569f 271 * - RAIL_EnableAddressFilter()
Anna Bridge 142:4eea097334d6 272 */
Anna Bridge 160:5571c4ff569f 273 RAIL_Status_t RAIL_IEEE802154_Init(RAIL_Handle_t railHandle,
AnnaBridge 167:84c0a372a020 274 const RAIL_IEEE802154_Config_t *fifteenFourConfig);
Anna Bridge 142:4eea097334d6 275
Anna Bridge 142:4eea097334d6 276 /**
Anna Bridge 142:4eea097334d6 277 * Configures the radio for 2.4GHz 802.15.4 operation
Anna Bridge 142:4eea097334d6 278 *
Anna Bridge 160:5571c4ff569f 279 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 160:5571c4ff569f 280 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 281 *
Anna Bridge 142:4eea097334d6 282 * This initializes the radio for 2.4GHz operation. It takes the place of
Anna Bridge 160:5571c4ff569f 283 * calling \ref RAIL_ConfigRadio and \ref RAIL_ConfigChannels. After this call,
Anna Bridge 142:4eea097334d6 284 * channels 11-26 will be available, giving the frequencies of those channels
Anna Bridge 142:4eea097334d6 285 * on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
Anna Bridge 142:4eea097334d6 286 */
Anna Bridge 160:5571c4ff569f 287 RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadio(RAIL_Handle_t railHandle);
Anna Bridge 142:4eea097334d6 288
Anna Bridge 142:4eea097334d6 289 /**
Anna Bridge 142:4eea097334d6 290 * De-initializes IEEE802.15.4 hardware acceleration
Anna Bridge 142:4eea097334d6 291 *
Anna Bridge 160:5571c4ff569f 292 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 160:5571c4ff569f 293 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 294 *
Anna Bridge 142:4eea097334d6 295 * Disables and resets all IEE802.15.4 hardware acceleration features. This
Anna Bridge 142:4eea097334d6 296 * function should only be called when the radio is IDLE. This calls the
Anna Bridge 142:4eea097334d6 297 * following:
Anna Bridge 142:4eea097334d6 298 * - RAIL_SetStateTiming(), to reset all timings to 100 us
Anna Bridge 160:5571c4ff569f 299 * - RAIL_EnableAddressFilter(false)
Anna Bridge 160:5571c4ff569f 300 * - RAIL_ResetAddressFilter()
Anna Bridge 142:4eea097334d6 301 */
Anna Bridge 160:5571c4ff569f 302 RAIL_Status_t RAIL_IEEE802154_Deinit(RAIL_Handle_t railHandle);
Anna Bridge 142:4eea097334d6 303
Anna Bridge 142:4eea097334d6 304 /**
AnnaBridge 167:84c0a372a020 305 * Return whether IEEE802.15.4 hardware acceleration is currently enabled.
Anna Bridge 142:4eea097334d6 306 *
Anna Bridge 160:5571c4ff569f 307 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 142:4eea097334d6 308 * @return True if IEEE802.15.4 hardware acceleration was enabled to start with
Anna Bridge 142:4eea097334d6 309 * and false otherwise
Anna Bridge 142:4eea097334d6 310 */
Anna Bridge 160:5571c4ff569f 311 bool RAIL_IEEE802154_IsEnabled(RAIL_Handle_t railHandle);
Anna Bridge 142:4eea097334d6 312
Anna Bridge 142:4eea097334d6 313 /**
Anna Bridge 142:4eea097334d6 314 * Configure the RAIL Address Filter for 802.15.4 filtering
Anna Bridge 142:4eea097334d6 315 *
Anna Bridge 160:5571c4ff569f 316 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 142:4eea097334d6 317 * @param[in] addresses The address information that should be used
Anna Bridge 160:5571c4ff569f 318 * @return Status code indicating success of the function call. If this returns
Anna Bridge 160:5571c4ff569f 319 * an error, then the 802.15.4 address filter is in an undefined state.
Anna Bridge 142:4eea097334d6 320 *
Anna Bridge 142:4eea097334d6 321 * Set up the 802.15.4 address filter to accept messages to the given
Anna Bridge 160:5571c4ff569f 322 * addresses. This will return false if any of the addresses failed to be set.
Anna Bridge 160:5571c4ff569f 323 * If NULL is passed in for addresses, then all addresses will be set to their
Anna Bridge 160:5571c4ff569f 324 * reset value.
Anna Bridge 142:4eea097334d6 325 */
Anna Bridge 160:5571c4ff569f 326 RAIL_Status_t RAIL_IEEE802154_SetAddresses(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 327 const RAIL_IEEE802154_AddrConfig_t *addresses);
Anna Bridge 142:4eea097334d6 328
Anna Bridge 142:4eea097334d6 329 /**
Anna Bridge 142:4eea097334d6 330 * Set a PAN ID for 802.15.4 address filtering
Anna Bridge 142:4eea097334d6 331 *
Anna Bridge 160:5571c4ff569f 332 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 142:4eea097334d6 333 * @param[in] panId The 16-bit PAN ID information.
Anna Bridge 142:4eea097334d6 334 * This will be matched against the destination PAN ID of incoming messages.
Anna Bridge 142:4eea097334d6 335 * The PAN ID is sent little endian over the air meaning panId[7:0] is first in
AnnaBridge 167:84c0a372a020 336 * the payload followed by panId[15:8]. Set to 0xFFFF to disable for this index.
Anna Bridge 160:5571c4ff569f 337 * @param[in] index Which PAN ID to set. Must be below
Anna Bridge 160:5571c4ff569f 338 * RAIL_IEEE802154_MAX_ADDRESSES.
Anna Bridge 160:5571c4ff569f 339 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 340 *
Anna Bridge 142:4eea097334d6 341 * Set up the 802.15.4 address filter to accept messages to the given PAN ID.
Anna Bridge 142:4eea097334d6 342 */
Anna Bridge 160:5571c4ff569f 343 RAIL_Status_t RAIL_IEEE802154_SetPanId(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 344 uint16_t panId,
Anna Bridge 160:5571c4ff569f 345 uint8_t index);
Anna Bridge 142:4eea097334d6 346
Anna Bridge 142:4eea097334d6 347 /**
Anna Bridge 142:4eea097334d6 348 * Set a short address for 802.15.4 address filtering
Anna Bridge 142:4eea097334d6 349 *
Anna Bridge 160:5571c4ff569f 350 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 142:4eea097334d6 351 * @param[in] shortAddr 16 bit short address value. This will be matched against the
Anna Bridge 142:4eea097334d6 352 * destination short address of incoming messages. The short address is sent
Anna Bridge 142:4eea097334d6 353 * little endian over the air meaning shortAddr[7:0] is first in the payload
AnnaBridge 167:84c0a372a020 354 * followed by shortAddr[15:8]. Set to 0xFFFF to disable for this index.
Anna Bridge 160:5571c4ff569f 355 * @param[in] index Which short address to set. Must be below
Anna Bridge 160:5571c4ff569f 356 * RAIL_IEEE802154_MAX_ADDRESSES.
Anna Bridge 160:5571c4ff569f 357 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 358 *
Anna Bridge 142:4eea097334d6 359 * Set up the 802.15.4 address filter to accept messages to the given short
Anna Bridge 142:4eea097334d6 360 * address.
Anna Bridge 142:4eea097334d6 361 */
Anna Bridge 160:5571c4ff569f 362 RAIL_Status_t RAIL_IEEE802154_SetShortAddress(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 363 uint16_t shortAddr,
Anna Bridge 160:5571c4ff569f 364 uint8_t index);
Anna Bridge 142:4eea097334d6 365
Anna Bridge 142:4eea097334d6 366 /**
Anna Bridge 142:4eea097334d6 367 * Set a long address for 802.15.4 address filtering
Anna Bridge 142:4eea097334d6 368 *
Anna Bridge 160:5571c4ff569f 369 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 142:4eea097334d6 370 * @param[in] longAddr Pointer to a 8 byte array containing the long address
Anna Bridge 142:4eea097334d6 371 * information. The long address must be in over the air byte order. This will
AnnaBridge 167:84c0a372a020 372 * be matched against the destination long address of incoming messages. Set to
AnnaBridge 167:84c0a372a020 373 * 0x00 00 00 00 00 00 00 00 to disable for this index.
Anna Bridge 160:5571c4ff569f 374 * @param[in] index Which long address to set. Must be below
Anna Bridge 160:5571c4ff569f 375 * RAIL_IEEE802154_MAX_ADDRESSES.
Anna Bridge 160:5571c4ff569f 376 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 377 *
Anna Bridge 142:4eea097334d6 378 * Set up the 802.15.4 address filter to accept messages to the given long
Anna Bridge 142:4eea097334d6 379 * address.
Anna Bridge 142:4eea097334d6 380 */
Anna Bridge 160:5571c4ff569f 381 RAIL_Status_t RAIL_IEEE802154_SetLongAddress(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 382 const uint8_t *longAddr,
Anna Bridge 160:5571c4ff569f 383 uint8_t index);
Anna Bridge 142:4eea097334d6 384
Anna Bridge 142:4eea097334d6 385 /**
Anna Bridge 142:4eea097334d6 386 * Set whether the current node is a PAN coordinator
Anna Bridge 142:4eea097334d6 387 *
Anna Bridge 160:5571c4ff569f 388 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 142:4eea097334d6 389 * @param[in] isPanCoordinator True if this device is a PAN coordinator
Anna Bridge 160:5571c4ff569f 390 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 391 *
Anna Bridge 142:4eea097334d6 392 * If the device is a PAN Coordinator, then it will accept data and command
Anna Bridge 142:4eea097334d6 393 * frames with no destination address. This function will fail if 802.15.4
Anna Bridge 142:4eea097334d6 394 * hardware acceleration is not currently enabled. This setting may be changed
AnnaBridge 167:84c0a372a020 395 * at any time when 802.15.4 hardware acceleration is enabled.
Anna Bridge 142:4eea097334d6 396 */
Anna Bridge 160:5571c4ff569f 397 RAIL_Status_t RAIL_IEEE802154_SetPanCoordinator(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 398 bool isPanCoordinator);
Anna Bridge 142:4eea097334d6 399
Anna Bridge 142:4eea097334d6 400 /**
Anna Bridge 142:4eea097334d6 401 * Set whether to enable 802.15.4 promiscuous mode
Anna Bridge 142:4eea097334d6 402 *
Anna Bridge 160:5571c4ff569f 403 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 142:4eea097334d6 404 * @param[in] enable True if all frames and addresses should be accepted
Anna Bridge 160:5571c4ff569f 405 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 406 *
Anna Bridge 142:4eea097334d6 407 * If promiscuous mode is enabled, then no frame or address filtering steps
Anna Bridge 142:4eea097334d6 408 * will be performed, other than checking the CRC. This function will fail if
Anna Bridge 142:4eea097334d6 409 * 802.15.4 hardware acceleration is not currently enabled. This setting may be
Anna Bridge 142:4eea097334d6 410 * changed at any time when 802.15.4 hardware acceleration is enabled.
Anna Bridge 142:4eea097334d6 411 */
Anna Bridge 160:5571c4ff569f 412 RAIL_Status_t RAIL_IEEE802154_SetPromiscuousMode(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 413 bool enable);
Anna Bridge 142:4eea097334d6 414
Anna Bridge 142:4eea097334d6 415 /// When receiving packets, accept 802.15.4 BEACON frame types
Anna Bridge 142:4eea097334d6 416 #define RAIL_IEEE802154_ACCEPT_BEACON_FRAMES (0x01)
Anna Bridge 142:4eea097334d6 417 /// When receiving packets, accept 802.15.4 DATA frame types
Anna Bridge 142:4eea097334d6 418 #define RAIL_IEEE802154_ACCEPT_DATA_FRAMES (0x02)
Anna Bridge 142:4eea097334d6 419 /// When receiving packets, accept 802.15.4 ACK frame types
Anna Bridge 142:4eea097334d6 420 /// If this is not enabled, ACK frame types will only be accepted while waiting
Anna Bridge 142:4eea097334d6 421 /// for an ack
Anna Bridge 142:4eea097334d6 422 #define RAIL_IEEE802154_ACCEPT_ACK_FRAMES (0x04)
Anna Bridge 142:4eea097334d6 423 /// When receiving packets, accept 802.15.4 COMMAND frame types
Anna Bridge 142:4eea097334d6 424 #define RAIL_IEEE802154_ACCEPT_COMMAND_FRAMES (0x08)
Anna Bridge 142:4eea097334d6 425
Anna Bridge 142:4eea097334d6 426 /// In standard operation, accept BEACON, DATA and COMMAND frames.
Anna Bridge 142:4eea097334d6 427 /// Only receive ACK frames while waiting for ack
Anna Bridge 160:5571c4ff569f 428 #define RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES (RAIL_IEEE802154_ACCEPT_BEACON_FRAMES \
Anna Bridge 160:5571c4ff569f 429 | RAIL_IEEE802154_ACCEPT_DATA_FRAMES \
Anna Bridge 160:5571c4ff569f 430 | RAIL_IEEE802154_ACCEPT_COMMAND_FRAMES)
Anna Bridge 142:4eea097334d6 431
Anna Bridge 142:4eea097334d6 432 /**
Anna Bridge 142:4eea097334d6 433 * Set which 802.15.4 frame types to accept
Anna Bridge 142:4eea097334d6 434 *
Anna Bridge 160:5571c4ff569f 435 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 142:4eea097334d6 436 * @param[in] framesMask Mask containing which 802.15.4 frame types to receive
Anna Bridge 160:5571c4ff569f 437 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 438 *
Anna Bridge 142:4eea097334d6 439 * This function will fail if 802.15.4 hardware acceleration is not currently
Anna Bridge 142:4eea097334d6 440 * enabled. This setting may be changed at any time when 802.15.4 hardware
Anna Bridge 142:4eea097334d6 441 * acceleration is enabled. Only Beacon, Data, Ack, and Command frames may
Anna Bridge 142:4eea097334d6 442 * be received. The RAIL_IEEE802154_ACCEPT_XXX_FRAMES defines may be combined
Anna Bridge 142:4eea097334d6 443 * to create a bitmask to pass into this function.
Anna Bridge 142:4eea097334d6 444 *
Anna Bridge 142:4eea097334d6 445 * \ref RAIL_IEEE802154_ACCEPT_ACK_FRAMES behaves slightly different than the
Anna Bridge 142:4eea097334d6 446 * other defines. If \ref RAIL_IEEE802154_ACCEPT_ACK_FRAMES is set, the radio
Anna Bridge 142:4eea097334d6 447 * will accept an ACK frame during normal packet reception. If \ref
Anna Bridge 142:4eea097334d6 448 * RAIL_IEEE802154_ACCEPT_ACK_FRAMES is not set, ACK frames will be filtered
Anna Bridge 142:4eea097334d6 449 * unless the radio is waiting for an ACK.
Anna Bridge 142:4eea097334d6 450 */
Anna Bridge 160:5571c4ff569f 451 RAIL_Status_t RAIL_IEEE802154_AcceptFrames(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 452 uint8_t framesMask);
Anna Bridge 142:4eea097334d6 453
Anna Bridge 142:4eea097334d6 454 /**
Anna Bridge 142:4eea097334d6 455 * Set the frame pending bit on the outgoing ACK
Anna Bridge 142:4eea097334d6 456 *
Anna Bridge 160:5571c4ff569f 457 * @param[in] railHandle Handle of RAIL instance
Anna Bridge 160:5571c4ff569f 458 * @return Status code indicating success of the function call.
Anna Bridge 142:4eea097334d6 459 *
Anna Bridge 160:5571c4ff569f 460 * This function should be called after receiving \ref
Anna Bridge 160:5571c4ff569f 461 * RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND, if the given source address has
Anna Bridge 160:5571c4ff569f 462 * a pending frame. This will return \ref RAIL_STATUS_INVALID_STATE if it is
Anna Bridge 160:5571c4ff569f 463 * too late to modify the ACK.
Anna Bridge 142:4eea097334d6 464 */
Anna Bridge 160:5571c4ff569f 465 RAIL_Status_t RAIL_IEEE802154_SetFramePending(RAIL_Handle_t railHandle);
Anna Bridge 142:4eea097334d6 466
Anna Bridge 142:4eea097334d6 467 /**
Anna Bridge 160:5571c4ff569f 468 * Get the source address of the incoming data request.
Anna Bridge 160:5571c4ff569f 469 *
Anna Bridge 160:5571c4ff569f 470 * @param[in] railHandle A RAIL instance handle.
Anna Bridge 160:5571c4ff569f 471 * @param[out] pAddress Pointer to \ref RAIL_IEEE802154_Address_t structure
Anna Bridge 160:5571c4ff569f 472 * to populate with address information.
Anna Bridge 160:5571c4ff569f 473 * @return Status code indicating success of the function call.
Anna Bridge 160:5571c4ff569f 474 *
Anna Bridge 160:5571c4ff569f 475 * This function should only be called when handling the \ref
Anna Bridge 160:5571c4ff569f 476 * RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event.
Anna Bridge 142:4eea097334d6 477 */
Anna Bridge 160:5571c4ff569f 478 RAIL_Status_t RAIL_IEEE802154_GetAddress(RAIL_Handle_t railHandle,
Anna Bridge 160:5571c4ff569f 479 RAIL_IEEE802154_Address_t *pAddress);
Anna Bridge 142:4eea097334d6 480
Anna Bridge 160:5571c4ff569f 481 /** @} */ // end of IEEE802.15.4
Anna Bridge 142:4eea097334d6 482
AnnaBridge 167:84c0a372a020 483 #ifdef __cplusplus
AnnaBridge 167:84c0a372a020 484 }
AnnaBridge 167:84c0a372a020 485 #endif
AnnaBridge 167:84c0a372a020 486
Anna Bridge 142:4eea097334d6 487 #endif // __RAIL_IEEE802154_H__