mbed official / mbed-dev

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

cmsis/BUILD/mbed/TARGET_TB_SENSE_1/TOOLCHAIN_ARM_STD/rail_ieee802154.h@189:f392fc9709a3, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 22:31:08 2019 +0000
Revision:
189:f392fc9709a3
mbed library release version 165

Who changed what in which revision?

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