alt-tek
/
rail
1
0
Fork 0
Code Issues Releases Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
v2.10.1
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'a6ae18eac9'
${ noResults }
rail/protocol/ieee802154/rail_ieee802154.h

995 lines
44 KiB
C
Raw Blame History

/***************************************************************************//**
* @file
* @brief The IEEE 802.15.4 specific header file for the RAIL library.
*******************************************************************************
* # License
* <b>Copyright 2020 Silicon Laboratories Inc. www.silabs.com</b>
*******************************************************************************
*
* SPDX-License-Identifier: Zlib
*
* The licensor of this software is Silicon Laboratories Inc.
*
* This software is provided 'as-is', without any express or implied
* warranty. In no event will the authors be held liable for any damages
* arising from the use of this software.
*
* Permission is granted to anyone to use this software for any purpose,
* including commercial applications, and to alter it and redistribute it
* freely, subject to the following restrictions:
*
* 1. The origin of this software must not be misrepresented; you must not
* claim that you wrote the original software. If you use this software
* in a product, an acknowledgment in the product documentation would be
* appreciated but is not required.
* 2. Altered source versions must be plainly marked as such, and must not be
* misrepresented as being the original software.
* 3. This notice may not be removed or altered from any source distribution.
*
******************************************************************************/
#ifndef __RAIL_IEEE802154_H__
#define __RAIL_IEEE802154_H__
#include "rail_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/// @addtogroup IEEE802_15_4 IEEE 802.15.4
/// @ingroup Protocol_Specific
/// @brief IEEE 802.15.4 configuration routines
///
/// The functions in this group configure RAIL IEEE 802.15.4 hardware
/// acceleration which includes IEEE 802.15.4 format filtering, address
/// filtering, ACKing, and filtering based on the frame type.
///
/// To configure IEEE 802.15.4 functionality, the application must first set up
/// a RAIL instance with RAIL_Init() and other setup functions.
/// Instead of RAIL_ConfigChannels(), however, an
/// application may use RAIL_IEEE802154_Config2p4GHzRadio() to set up the
/// official IEEE 2.4 GHz 802.15.4 PHY. This configuration is shown below.
///
/// 802.15.4 defines its macAckWaitDuration from the end of the transmitted
/// packet to complete reception of the ACK. RAIL's ackTimeout only covers
/// sync word detection of the ACK. Therefore, subtract the ACK's
/// PHY header and payload time to get RAIL's ackTimeout setting.
/// For 2.4 GHz OQPSK, macAckWaitDuration is specified as 54 symbols;
/// subtracting 2-symbol PHY header and 10-symbol payload yields a RAIL
/// ackTimeout of 42 symbols or 672 microseconds at 16 microseconds/symbol.
///
/// @code{.c}
/// static RAIL_Handle_t railHandle = NULL; // Initialized somewhere else.
///
/// static const RAIL_IEEE802154_Config_t rail154Config = {
/// .addresses = NULL,
/// .ackConfig = {
/// .enable = true, // Turn on auto ACK for IEEE 802.15.4.
/// .ackTimeout = 672, // See note above: 54-12 sym * 16 us/sym = 672 us.
/// .rxTransitions = {
/// .success = RAIL_RF_STATE_RX, // Return to RX after ACK processing
/// .error = RAIL_RF_STATE_RX, // Ignored
/// },
/// .txTransitions = {
/// .success = RAIL_RF_STATE_RX, // Return to RX after ACK processing
/// .error = RAIL_RF_STATE_RX, // Ignored
/// },
/// },
/// .timings = {
/// .idleToRx = 100,
/// .idleToTx = 100,
/// .rxToTx = 192, // 12 symbols * 16 us/symbol = 192 us
/// .txToRx = 192, // 12 symbols * 16 us/symbol = 192 us
/// .rxSearchTimeout = 0, // Not used
/// .txToRxSearchTimeout = 0, // Not used
/// },
/// .framesMask = RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES,
/// .promiscuousMode = false, // Enable format and address filtering.
/// .isPanCoordinator = false,
/// .defaultFramePendingInOutgoingAcks = false,
/// };
///
/// void config154(void)
/// {
/// // Configure the radio and channels for 2.4 GHz IEEE 802.15.4.
/// RAIL_IEEE802154_Config2p4GHzRadio(railHandle);
/// // Initialize the IEEE 802.15.4 configuration using the static configuration above.
/// RAIL_IEEE802154_Init(railHandle, &rail154Config);
/// }
/// @endcode
///
/// To configure address filtering, call
/// RAIL_IEEE802154_SetAddresses() with a structure containing all addresses or
/// call the individual RAIL_IEEE802154_SetPanId(),
/// RAIL_IEEE802154_SetShortAddress(), and RAIL_IEEE802154_SetLongAddress()
/// APIs. RAIL supports \ref RAIL_IEEE802154_MAX_ADDRESSES number of address
/// pairs to receive packets from multiple IEEE
/// 802.15.4 networks at the same time. Broadcast addresses are supported by
/// default without any additional configuration so they do not consume one of
/// these slots. If the application does not require all address pairs, be sure
/// to set unused ones to the proper disabled value for each type. These can
/// be found in the \ref RAIL_IEEE802154_AddrConfig_t documentation. Below is
/// an example of setting filtering for one set of addresses.
///
/// @code{.c}
/// // PanID OTA value of 0x34 0x12.
/// // Short Address OTA byte order of 0x78 0x56.
/// // Long address with OTA byte order of 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88.
///
/// // Set up all addresses simultaneously.
/// RAIL_Status_t setup1(void)
/// {
/// RAIL_IEEE802154_AddrConfig_t nodeAddress = {
/// { 0x1234, 0xFFFF, 0xFFFF },
/// { 0x5678, 0xFFFF, 0xFFFF },
/// { { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88 },
/// { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 },
/// { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 } }
/// };
/// return RAIL_IEEE802154_SetAddresses(railHandle, &nodeAddress);
/// }
///
/// // Alternatively, the addresses can be set up individually as follows:
/// RAIL_Status_t setup2(void)
/// {
/// RAIL_Status_t status;
/// const uint8_t longAddress[] = { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88 };
///
/// status = RAIL_IEEE802154_SetPanId(railHandle, 0x1234, 0);
/// if (status != RAIL_STATUS_NO_ERROR) {
/// return status
/// }
/// status = RAIL_IEEE802154_SetShortAddress(railHandle, 0x5678, 0);
/// if (status != RAIL_STATUS_NO_ERROR) {
/// return status
/// }
/// status = RAIL_IEEE802154_SetLongAddress(railHandle, longAddress, 0);
/// if (status != RAIL_STATUS_NO_ERROR) {
/// return status
/// }
///
/// return RAIL_STATUS_NO_ERROR;
/// }
/// @endcode
///
/// Address filtering will be enabled except when in promiscuous mode which can
/// be set with RAIL_IEEE802154_SetPromiscuousMode(). The addresses may be
/// changed at runtime. However, if you are receiving a packet while
/// reconfiguring the address filters, you may get undesired behavior so it's
/// safest to do this while not in receive.
///
/// Auto ACK is controlled by the ackConfig and timings fields passed to
/// RAIL_IEEE802154_Init(). After initialization they may be controlled
/// using the normal \ref Auto_Ack and \ref State_Transitions APIs. When in IEEE
/// 802.15.4 mode, the ACK will generally have a 5 byte length, its Frame Type
/// will be ACK, its Frame Version 0 (2003), and its Frame Pending bit will be
/// false unless the \ref RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event is
/// triggered in which case it will default to the
/// \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks setting.
/// If the default Frame Pending setting is incorrect,
/// the app must call \ref RAIL_IEEE802154_ToggleFramePending
/// (formerly \ref RAIL_IEEE802154_SetFramePending) while handling the
/// \ref RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event.
///
/// This event must be turned on by the user and will fire whenever a data
/// request is being received so that the stack can determine whether there
/// is pending data. Be aware that if the default Frame Pending bit needs to
/// be changed it must be done quickly otherwise the ACK may already
/// have been transmitted with the default setting. Check the return code of
/// RAIL_IEEE802154_ToggleFramePending() to be sure that the bit was changed
/// in time.
///
/// Transmit and receive operations are done using the standard RAIL APIs in
/// IEEE 802.15.4 mode. To send packets using the correct CSMA configuration
/// there is a \ref RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA define
/// that can initialize the csmaConfig structure passed to \ref
/// RAIL_StartCcaCsmaTx().
/// @{
/**
* @enum RAIL_IEEE802154_AddressLength_t
* @brief Different lengths that an 802.15.4 address can have
*/
RAIL_ENUM(RAIL_IEEE802154_AddressLength_t) {
RAIL_IEEE802154_ShortAddress = 2, /**< 2 byte short address. */
RAIL_IEEE802154_LongAddress = 3, /**< 8 byte extended address. */
};
#ifndef DOXYGEN_SHOULD_SKIP_THIS
// Self-referencing defines minimize compiler complaints when using RAIL_ENUM
#define RAIL_IEEE802154_ShortAddress ((RAIL_IEEE802154_AddressLength_t) RAIL_IEEE802154_ShortAddress)
#define RAIL_IEEE802154_LongAddress ((RAIL_IEEE802154_AddressLength_t) RAIL_IEEE802154_LongAddress)
#endif//DOXYGEN_SHOULD_SKIP_THIS
/**
* @struct RAIL_IEEE802154_Address_t
* @brief Representation of 802.15.4 address
* This structure is only used for received source address information
* needed to perform Frame Pending lookup.
*/
typedef struct RAIL_IEEE802154_Address{
/** Convenient storage for different address types. */
union {
uint16_t shortAddress; /**< Present for 2 byte addresses. */
uint8_t longAddress[8]; /**< Present for 8 byte addresses. */
};
/**
* Enumeration of the received address length.
*/
RAIL_IEEE802154_AddressLength_t length;
/**
* A bitmask representing which address filter(s) this packet has passed.
* It is undefined on platforms lacking \ref RAIL_SUPPORTS_ADDR_FILTER_MASK.
*/
RAIL_AddrFilterMask_t filterMask;
} RAIL_IEEE802154_Address_t;
/** The maximum number of allowed addresses of each type. */
#define RAIL_IEEE802154_MAX_ADDRESSES (3U)
/**
* @struct RAIL_IEEE802154_AddrConfig_t
* @brief A configuration structure for IEEE 802.15.4 Address Filtering. The
* broadcast addresses are handled separately and do not need to be specified
* here. Any address to be ignored should be set with all bits high.
*
* This structure allows configuration of multi-PAN functionality by specifying
* multiple PAN IDs and short addresses. A packet will be received if it matches
* an address and its corresponding PAN ID. Long address 0 and short address 0
* match against PAN ID 0, etc. The broadcast PAN ID and address will work with
* any address or PAN ID, respectively.
*/
typedef struct RAIL_IEEE802154_AddrConfig{
/**
* PAN IDs for destination filtering. All must be specified.
* To disable a PAN ID, set it to the broadcast value, 0xFFFF.
*/
uint16_t panId[RAIL_IEEE802154_MAX_ADDRESSES];
/**
* A short network addresses for destination filtering. All must be specified.
* To disable a short address, set it to the broadcast value, 0xFFFF.
*/
uint16_t shortAddr[RAIL_IEEE802154_MAX_ADDRESSES];
/**
* A 64-bit address for destination filtering. All must be specified.
* This field is parsed in over-the-air (OTA) byte order. To disable a long
* address, set it to the reserved value of 0x00 00 00 00 00 00 00 00.
*/
uint8_t longAddr[RAIL_IEEE802154_MAX_ADDRESSES][8];
} RAIL_IEEE802154_AddrConfig_t;
/**
* @struct RAIL_IEEE802154_Config_t
* @brief A configuration structure for IEEE 802.15.4 in RAIL.
*/
typedef struct RAIL_IEEE802154_Config {
/**
* Configure the RAIL Address Filter to allow the given destination
* addresses. If this pointer is NULL, defer destination address configuration.
* If a member of addresses is NULL, defer configuration of just that member.
* This can be overridden via RAIL_IEEE802154_SetAddresses(), or the
* individual members can be changed via RAIL_IEEE802154_SetPanId(),
* RAIL_IEEE802154_SetShortAddress(), and RAIL_IEEE802154_SetLongAddress().
*/
const RAIL_IEEE802154_AddrConfig_t *addresses;
/**
* Define the ACKing configuration for the IEEE 802.15.4 implementation.
*/
RAIL_AutoAckConfig_t ackConfig;
/**
* Define state timings for the IEEE 802.15.4 implementation.
*/
RAIL_StateTiming_t timings;
/**
* Set which 802.15.4 frame types will be received, of Beacon, Data, ACK, and
* Command. This setting can be overridden via RAIL_IEEE802154_AcceptFrames().
*/
uint8_t framesMask;
/**
* Enable promiscuous mode during configuration. This can be overridden via
* RAIL_IEEE802154_SetPromiscuousMode() afterwards.
*/
bool promiscuousMode;
/**
* Set whether the device is a PAN Coordinator during configuration. This can
* be overridden via RAIL_IEEE802154_SetPanCoordinator() afterwards.
*/
bool isPanCoordinator;
/**
* The default value for the Frame Pending bit in outgoing ACKs for packets
* that triggered the \ref RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event.
* Such an ACK's Frame Pending bit can be inverted if necessary during the
* handling of that event by calling \ref RAIL_IEEE802154_ToggleFramePending
* (formerly \ref RAIL_IEEE802154_SetFramePending).
*/
bool defaultFramePendingInOutgoingAcks;
} RAIL_IEEE802154_Config_t;
/**
* Initialize RAIL for IEEE802.15.4 features.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] config An IEEE802154 configuration structure.
* @return A status code indicating success of the function call.
*
* This function calls the following RAIL functions to configure the radio for
* IEEE802.15.4 features.
*
* Initializes the following:
* - Enables IEEE802154 hardware acceleration
* - Configures RAIL Auto ACK functionality
* - Configures RAIL Address Filter for 802.15.4 address filtering
*
* It saves having to call the following functions individually:
* - RAIL_ConfigAutoAck()
* - RAIL_SetRxTransitions()
* - RAIL_SetTxTransitions()
* - RAIL_WriteAutoAckFifo()
* - RAIL_SetStateTiming()
* - RAIL_ConfigAddressFilter()
* - RAIL_EnableAddressFilter()
*/
RAIL_Status_t RAIL_IEEE802154_Init(RAIL_Handle_t railHandle,
const RAIL_IEEE802154_Config_t *config);
/**
* Configure the radio for 2.4 GHz 802.15.4 operation.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for 2.4 GHz operation. It takes the place of
* calling \ref RAIL_ConfigChannels. After this call,
* channels 11-26 will be available, giving the frequencies of those channels
* on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
*/
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadio(RAIL_Handle_t railHandle);
/**
* Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for 2.4 GHz operation, but with a configuration
* that supports antenna diversity. It takes the place of
* calling \ref RAIL_ConfigChannels. After this call,
* channels 11-26 will be available, giving the frequencies of those channels
* on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
*/
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDiv(RAIL_Handle_t railHandle);
/**
* Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity
* optimized for radio coexistence.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for 2.4 GHz operation, but with a configuration
* that supports antenna diversity optimized for radio coexistence. It takes
* the place of calling \ref RAIL_ConfigChannels. After this call,
* channels 11-26 will be available, giving the frequencies of those channels
* on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
*/
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDivCoex(RAIL_Handle_t railHandle);
/**
* Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for 2.4 GHz operation, but with a configuration
* that supports radio coexistence. It takes the place of
* calling \ref RAIL_ConfigChannels. After this call,
* channels 11-26 will be available, giving the frequencies of those channels
* on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
*/
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioCoex(RAIL_Handle_t railHandle);
/**
* Configure the radio for 2.4 GHz 802.15.4 operation with a front end module.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for 2.4 GHz operation, but with a configuration
* that supports a front end module. It takes the place of
* calling \ref RAIL_ConfigChannels. After this call,
* channels 11-26 will be available, giving the frequencies of those channels
* on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
*/
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioFem(RAIL_Handle_t railHandle);
/**
* Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity
* optimized for a front end module.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for 2.4 GHz operation, but with a configuration
* that supports antenna diversity and a front end module. It takes the place of
* calling \ref RAIL_ConfigChannels. After this call,
* channels 11-26 will be available, giving the frequencies of those channels
* on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
*/
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDivFem(RAIL_Handle_t railHandle);
/**
* Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence
* and a front end module.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for 2.4 GHz operation, but with a configuration
* that supports radio coexistence and a front end module. It takes the place of
* calling \ref RAIL_ConfigChannels. After this call,
* channels 11-26 will be available, giving the frequencies of those channels
* on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
*/
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioCoexFem(RAIL_Handle_t railHandle);
/**
* Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity
* optimized for radio coexistence and a front end module.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for 2.4 GHz operation, but with a configuration
* that supports antenna diversity, radio coexistence and a front end module.
* It takes the place of calling \ref RAIL_ConfigChannels.
* After this call, channels 11-26 will be available, giving the frequencies of
* those channels on channel page 0, as defined by IEEE 802.15.4-2011 section 8.1.2.2.
*/
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDivCoexFem(RAIL_Handle_t railHandle);
/**
* Configure the radio for SubGHz GB868 863 MHz 802.15.4 operation.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for SubGHz GB868 863 MHz operation. It takes the
* place of calling \ref RAIL_ConfigChannels.
* After this call, GB868 channels in the 863 MHz band (channel pages 28, 29,
* and 30 -- logical channels 0x80..0x9A, 0xA0..0xA8, 0xC0..0xDA, respectively)
* will be available, as defined by Rev 22 of the Zigbee Specification, 2017
* document 05-3474-22, section D.10.2.1.3.2.
*/
RAIL_Status_t RAIL_IEEE802154_ConfigGB863MHzRadio(RAIL_Handle_t railHandle);
/**
* Configure the radio for SubGHz GB868 915 MHz 802.15.4 operation.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* This initializes the radio for SubGHz GB868 915 MHz operation. It takes the
* place of calling \ref RAIL_ConfigChannels.
* After this call, GB868 channels in the 915 MHz band (channel page 31 --
* logical channels 0xE0..0xFA) will be available, as defined by Rev 22 of
* the Zigbee Specification, 2017 document 05-3474-22, section D.10.2.1.3.2.
*/
RAIL_Status_t RAIL_IEEE802154_ConfigGB915MHzRadio(RAIL_Handle_t railHandle);
/**
* De-initialize IEEE802.15.4 hardware acceleration.
*
* @param[in] railHandle A handle of RAIL instance.
* @return A status code indicating success of the function call.
*
* Disables and resets all IEE802.15.4 hardware acceleration features. This
* function should only be called when the radio is IDLE. This calls the
* following:
* - RAIL_SetStateTiming(), to reset all timings to 100 us
* - RAIL_EnableAddressFilter(false)
* - RAIL_ResetAddressFilter()
*/
RAIL_Status_t RAIL_IEEE802154_Deinit(RAIL_Handle_t railHandle);
/**
* Return whether IEEE802.15.4 hardware acceleration is currently enabled.
*
* @param[in] railHandle A handle of RAIL instance.
* @return True if IEEE802.15.4 hardware acceleration was enabled to start with
* and false otherwise.
*/
bool RAIL_IEEE802154_IsEnabled(RAIL_Handle_t railHandle);
/**
* Configure the RAIL Address Filter for 802.15.4 filtering.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] addresses The address information that should be used.
* @return A status code indicating success of the function call. If this returns
* an error, the 802.15.4 address filter is in an undefined state.
*
* Set up the 802.15.4 address filter to accept messages to the given
* addresses. This will return false if any of the addresses failed to be set.
* If NULL is passed in for addresses, all addresses will be set to their
* reset value.
*/
RAIL_Status_t RAIL_IEEE802154_SetAddresses(RAIL_Handle_t railHandle,
const RAIL_IEEE802154_AddrConfig_t *addresses);
/**
* Set a PAN ID for 802.15.4 address filtering.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] panId The 16-bit PAN ID information.
* This will be matched against the destination PAN ID of incoming messages.
* The PAN ID is sent little endian over the air, meaning panId[7:0] is first in
* the payload followed by panId[15:8]. Set to 0xFFFF to disable for this index.
* @param[in] index Indicates which PAN ID to set. Must be below
* RAIL_IEEE802154_MAX_ADDRESSES.
* @return A status code indicating success of the function call.
*
* Set up the 802.15.4 address filter to accept messages to the given PAN ID.
*/
RAIL_Status_t RAIL_IEEE802154_SetPanId(RAIL_Handle_t railHandle,
uint16_t panId,
uint8_t index);
/**
* Set a short address for 802.15.4 address filtering.
*
* @param[in] railHandle A handle of RAIL instance
* @param[in] shortAddr 16 bit short address value. This will be matched against the
* destination short address of incoming messages. The short address is sent
* little endian over the air meaning shortAddr[7:0] is first in the payload
* followed by shortAddr[15:8]. Set to 0xFFFF to disable for this index.
* @param[in] index Which short address to set. Must be below
* RAIL_IEEE802154_MAX_ADDRESSES.
* @return A status code indicating success of the function call.
*
* Set up the 802.15.4 address filter to accept messages to the given short
* address.
*/
RAIL_Status_t RAIL_IEEE802154_SetShortAddress(RAIL_Handle_t railHandle,
uint16_t shortAddr,
uint8_t index);
/**
* Set a long address for 802.15.4 address filtering.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] longAddr A pointer to an 8-byte array containing the long address
* information. The long address must be in over-the-air byte order. This will
* be matched against the destination long address of incoming messages. Set to
* 0x00 00 00 00 00 00 00 00 to disable for this index.
* @param[in] index Indicates which long address to set. Must be below
* RAIL_IEEE802154_MAX_ADDRESSES.
* @return A status code indicating success of the function call.
*
* Set up the 802.15.4 address filter to accept messages to the given long
* address.
*/
RAIL_Status_t RAIL_IEEE802154_SetLongAddress(RAIL_Handle_t railHandle,
const uint8_t *longAddr,
uint8_t index);
/**
* Set whether the current node is a PAN coordinator.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] isPanCoordinator True if this device is a PAN coordinator.
* @return A status code indicating success of the function call.
*
* If the device is a PAN Coordinator, it will accept data and command
* frames with no destination address. This function will fail if 802.15.4
* hardware acceleration is not currently enabled. This setting may be changed
* at any time when 802.15.4 hardware acceleration is enabled.
*/
RAIL_Status_t RAIL_IEEE802154_SetPanCoordinator(RAIL_Handle_t railHandle,
bool isPanCoordinator);
/**
* Set whether to enable 802.15.4 promiscuous mode.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] enable True if all frames and addresses should be accepted.
* @return A status code indicating success of the function call.
*
* If promiscuous mode is enabled, no frame or address filtering steps
* will be performed other than checking the CRC. This function will fail if
* 802.15.4 hardware acceleration is not currently enabled. This setting may be
* changed at any time when 802.15.4 hardware acceleration is enabled.
*/
RAIL_Status_t RAIL_IEEE802154_SetPromiscuousMode(RAIL_Handle_t railHandle,
bool enable);
/**
* @enum RAIL_IEEE802154_EOptions_t
* @brief 802.15.4E-2012 options, in reality a bitmask.
*/
RAIL_ENUM_GENERIC(RAIL_IEEE802154_EOptions_t, uint32_t) {
/** Shift position of \ref RAIL_IEEE802154_E_OPTION_GB868 bit. */
RAIL_IEEE802154_E_OPTION_GB868_SHIFT = 0,
RAIL_IEEE802154_E_OPTION_ENH_ACK_SHIFT,
RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST_SHIFT,
};
/** A value representing no options enabled. */
#define RAIL_IEEE802154_E_OPTIONS_NONE 0UL
/** All options disabled by default . */
#define RAIL_IEEE802154_E_OPTIONS_DEFAULT RAIL_IEEE802154_E_OPTIONS_NONE
/**
* An option to enable/disable 802.15.4E-2012 features needed for GB868.
* When not promiscuous, RAIL normally accepts only 802.15.4 MAC frames
* whose MAC header Frame Version is 0 (802.15.4-2003) or 1 (802.15.4-2006),
* filtering out higher Frame Version packets (as \ref
* RAIL_RX_PACKET_ABORT_FORMAT).
* Enabling this feature additionally allows Frame Version 2 (802.15.4E-2012 /
* 802.15.4-2015) packets to be accepted and passed to the application.
*
* @note If 802.15.4 MAC-level encryption is used with Frame Version 2
* frames, RAIL_IEEE802154_EnableEarlyFramePending() should also be
* called otherwise data polls may not be recognized to trigger \ref
* RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND events.
*
* @note Enabling this feature also automatically enables \ref
* RAIL_IEEE802154_E_OPTION_ENH_ACK on platforms that support
* that feature.
*
* @note This feature does not automatically enable receiving Multipurpose
* frames; that can be enabled via RAIL_IEEE802154_AcceptFrames()'s
* \ref RAIL_IEEE802154_ACCEPT_MULTIPURPOSE_FRAMES.
*/
#define RAIL_IEEE802154_E_OPTION_GB868 (1UL << RAIL_IEEE802154_E_OPTION_GB868_SHIFT)
/**
* An option to enable/disable 802.15.4E-2012 features needed for Enhanced ACKs.
* This option requires that \ref RAIL_IEEE802154_E_OPTION_GB868 also be
* enabled, and is enabled automatically on platforms that support this
* feature. It exists as a separate flag to allow runtime detection of whether
* the platform supports this feature or not.
*
* When enabled, only an Enhanced ACK is expected in response to a transmitted
* ACK-requesting 802.15.4E Frame Version 2 frame, and when such a frame is
* received, the application is expected to generate the Enhanced ACK
* while processing \ref RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND and
* call \ref RAIL_IEEE802154_WriteEnhAck() in time for that Enhanced ACK to
* be sent. For this to work properly, the application should enable both
* \ref RAIL_IEEE802154_EnableEarlyFramePending() and
* \ref RAIL_IEEE802154_EnableDataFramePending(), and use
* \ref RAIL_GetRxIncomingPacketInfo() to determine whether an Enhanced ACK
* is needed along the contents of that ACK packet.
*
* On 802.15.4E GB868 platforms that lack this support, legacy Immediate ACKs
* are sent/expected for received/transmitted ACK-requesting 802.15.4E Frame
* Version 2 frames; calls to \ref RAIL_IEEE802154_WriteEnhAck() have no
* effect. Attempting to use this feature via \ref
* RAIL_IEEE802154_ConfigEOptions() returns an error.
*/
#define RAIL_IEEE802154_E_OPTION_ENH_ACK (1UL << RAIL_IEEE802154_E_OPTION_ENH_ACK_SHIFT)
/**
* An option to enable/disable 802.15.4E-2012 macImplicitBroadcast feature.
*
* When enabled, received Frame Version 2 frames without a destination
* PAN ID or destination address are treated as though they are addressed
* to the broadcast PAN ID and broadcast short address. When disabled, such
* frames are filtered unless the device is the PAN coordinator and
* appropriate source addressing information exists in the packet
*/
#define RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST (1UL << RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST_SHIFT)
/** A value representing all possible options. */
#define RAIL_IEEE802154_E_OPTIONS_ALL 0xFFFFFFFFUL
/**
* Configure certain 802.15.4E-2012 / 802.15.4-2015 Frame Version 2 features.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] mask A bitmask containing which options should be modified.
* @param[in] options A bitmask containing desired options settings.
* Bit positions for each option are found in the \ref
* RAIL_IEEE802154_EOptions_t.
* @return A status code indicating success of the function call.
*
* This function will fail if 802.15.4 hardware acceleration is not
* currently enabled or the platform does not support the feature(s).
* These settings may be changed at any time when 802.15.4 hardware
* acceleration is enabled.
*/
RAIL_Status_t RAIL_IEEE802154_ConfigEOptions(RAIL_Handle_t railHandle,
RAIL_IEEE802154_EOptions_t mask,
RAIL_IEEE802154_EOptions_t options);
/**
* @enum RAIL_IEEE802154_GOptions_t
* @brief 802.15.4G-2012 options, in reality a bitmask.
*/
RAIL_ENUM_GENERIC(RAIL_IEEE802154_GOptions_t, uint32_t) {
/** Shift position of \ref RAIL_IEEE802154_G_OPTION_GB868 bit. */
RAIL_IEEE802154_G_OPTION_GB868_SHIFT = 0,
};
/** A value representing no options enabled. */
#define RAIL_IEEE802154_G_OPTIONS_NONE 0UL
/** All options disabled by default . */
#define RAIL_IEEE802154_G_OPTIONS_DEFAULT RAIL_IEEE802154_G_OPTIONS_NONE
/**
* An option to enable/disable 802.15.4G-2012 features needed for GB868.
* Normally RAIL supports 802.15.4-2003 and -2006 radio configurations
* that have the single-byte PHY header allowing frames up to 128 bytes
* in size. This feature must be enabled for 802.15.4G-2012 or
* 802.15.4-2015 SUN PHY radio configurations with the two-byte
* bit-reversed-length PHY header format.
*
* While GB868 only supports whitened non-FEC non-mode-switch frames
* up to 129 bytes including 2-byte CRC, this option also enables:
* - On platforms where \ref RAIL_FEAT_IEEE802154_G_4BYTE_CRC_SUPPORTED
* is true: automatic per-packet 2/4-byte Frame Check Sequence (FCS)
* reception and transmission based on the FCS Type bit in the
* received/transmitted PHY header. This includes ACK reception
* and automatically-generated ACKs reflect the CRC size of the
* incoming frame being acknowledged (i.e., their MAC payload will be
* increased to 7 bytes when sending 4-byte FCS).
* On other platforms, only the 2-byte FCS is supported.
* - On platforms where \ref RAIL_FEAT_IEEE802154_G_UNWHITENED_RX_SUPPORTED
* and/or \ref RAIL_FEAT_IEEE802154_G_UNWHITENED_TX_SUPPORTED are true:
* automatic per-packet whitened/unwhitened reception and transmission,
* respectively, based on the Data Whitening bit in the received/transmitted
* PHY header. This includes ACK reception and automatically-generated ACKs
* which reflect the whitening of the incoming frame being acknowledged.
* On other platforms, only whitened frames are supported.
* - Support for frames up to 2049 bytes per the radio configuration's
* maximum packet length setting.
*
* @note Sending/receiving whitened frames assumes the radio configuration
* has established an appropriate 802.15.4-compliant whitening algorithm.
* RAIL does not itself override the radio configuration's whitening
* settings other than to enable/disable it per-packet based on the
* packet's PHY header Data Whitening flag.
*/
#define RAIL_IEEE802154_G_OPTION_GB868 (1UL << RAIL_IEEE802154_G_OPTION_GB868_SHIFT)
/** A value representing all possible options. */
#define RAIL_IEEE802154_G_OPTIONS_ALL 0xFFFFFFFFUL
/**
* Configure certain 802.15.4G-2012 / 802.15.4-2015 SUN PHY features
* (only for radio configurations designed accordingly).
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] mask A bitmask containing which options should be modified.
* @param[in] options A bitmask containing desired options settings.
* Bit positions for each option are found in the \ref
* RAIL_IEEE802154_GOptions_t.
* @return A status code indicating success of the function call.
*
* This function will fail if 802.15.4 hardware acceleration is not
* currently enabled, the platform does not support the feature(s),
* the radio configuration is not appropriate, or the radio is not idle.
*/
RAIL_Status_t RAIL_IEEE802154_ConfigGOptions(RAIL_Handle_t railHandle,
RAIL_IEEE802154_GOptions_t mask,
RAIL_IEEE802154_GOptions_t options);
/// When receiving packets, accept 802.15.4 BEACON frame types.
#define RAIL_IEEE802154_ACCEPT_BEACON_FRAMES (0x01)
/// When receiving packets, accept 802.15.4 DATA frame types.
#define RAIL_IEEE802154_ACCEPT_DATA_FRAMES (0x02)
/// When receiving packets, accept 802.15.4 ACK frame types.
/// @note Expected ACK frame types will still be accepted regardless
/// of this setting when waiting for an ACK after a transmit that
/// used \ref RAIL_TX_OPTION_WAIT_FOR_ACK and auto-ACK is enabled.
#define RAIL_IEEE802154_ACCEPT_ACK_FRAMES (0x04)
/// When receiving packets, accept 802.15.4 COMMAND frame types.
#define RAIL_IEEE802154_ACCEPT_COMMAND_FRAMES (0x08)
// Reserved for possible future use: (0x10)
/// When receiving packets, accept 802.15.4-2015 Multipurpose frame types.
/// (Not supported on EFR32XG1.)
#define RAIL_IEEE802154_ACCEPT_MULTIPURPOSE_FRAMES (0x20)
/// In standard operation, accept BEACON, DATA and COMMAND frames.
/// Don't receive ACK frames unless waiting for ACK (i.e., only
/// receive expected ACKs).
#define RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES (RAIL_IEEE802154_ACCEPT_BEACON_FRAMES \
| RAIL_IEEE802154_ACCEPT_DATA_FRAMES \
| RAIL_IEEE802154_ACCEPT_COMMAND_FRAMES)
/**
* Set which 802.15.4 frame types to accept.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] framesMask A mask containing which 802.15.4 frame types to receive.
* @return A status code indicating success of the function call.
*
* This function will fail if 802.15.4 hardware acceleration is not currently
* enabled or framesMask requests an unsupported frame type.
* This setting may be changed at any time when 802.15.4 hardware
* acceleration is enabled. Only Beacon, Data, ACK, Command, and Multipurpose
* (except on EFR32XG1) frames may be received.
* The RAIL_IEEE802154_ACCEPT_XXX_FRAMES defines may be combined to create a
* bitmask to pass into this function.
*
* \ref RAIL_IEEE802154_ACCEPT_ACK_FRAMES behaves slightly different than the
* other defines. If \ref RAIL_IEEE802154_ACCEPT_ACK_FRAMES is set, the radio
* will accept an ACK frame during normal packet reception, but only a
* truly expected ACK will have its \ref RAIL_RxPacketDetails_t::isAck true.
* If \ref RAIL_IEEE802154_ACCEPT_ACK_FRAMES is not set, ACK frames will be
* filtered unless they're expected when the radio is waiting for an ACK.
*/
RAIL_Status_t RAIL_IEEE802154_AcceptFrames(RAIL_Handle_t railHandle,
uint8_t framesMask);
/**
* Enable early Frame Pending lookup event notification
* (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND).
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] enable True to enable, false to disable.
* @return A status code indicating success of the function call.
*
* Normally RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered after
* receiving the entire MAC header for a MAC command and the MAC
* command byte indicating the packet is a data request. Enabling this
* feature causes this event to be triggered earlier, right after receiving
* the source address information in the MAC header, allowing for more time
* to perform the lookup and call \ref RAIL_IEEE802154_ToggleFramePending()
* to update the Frame Pending bit in the outgoing ACK for the incoming frame.
* This feature is also necessary for handling 802.15.4 MAC-encrypted
* frames where the MAC Command byte is encrypted (MAC Frame Version 2) --
* see \ref RAIL_IEEE802154_ConfigEOptions().
*
* This function will fail if 802.15.4 hardware acceleration is not
* currently enabled, or on platforms that do not support this feature.
* This setting may be changed at any time when 802.15.4 hardware
* acceleration is enabled.
*/
RAIL_Status_t RAIL_IEEE802154_EnableEarlyFramePending(RAIL_Handle_t railHandle,
bool enable);
/**
* Enable Frame Pending lookup event notification
* (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND) for MAC Data frames.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] enable True to enable, false to disable.
* @return A status code indicating success of the function call.
*
* Normally RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered only
* for MAC command frames whose MAC command byte indicates the packet is
* a data request. Enabling this feature causes this event to also be
* triggered for MAC data frames right after receiving the source
* address information in the MAC header -- necessary to support the
* Thread Basil-Hayden Enhanced Frame Pending feature.
*
* This function will fail if 802.15.4 hardware acceleration is not
* currently enabled. This setting may be changed at any time when
* 802.15.4 hardware acceleration is enabled.
*/
RAIL_Status_t RAIL_IEEE802154_EnableDataFramePending(RAIL_Handle_t railHandle,
bool enable);
/**
* Alternate naming for function \ref RAIL_IEEE802154_SetFramePending
* to depict it is used for changing the default setting specified by
* \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks in
* an outgoing ACK.
*/
#define RAIL_IEEE802154_ToggleFramePending RAIL_IEEE802154_SetFramePending
/**
* Change the Frame Pending bit on the outgoing legacy Immediate ACK from
* the default specified by
* \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks.
* @param[in] railHandle A handle of RAIL instance
* @return A status code indicating success of the function call.
*
* This function must only be called while processing the \ref
* RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND if the ACK
* for this packet should go out with its Frame Pending bit set differently
* than what was specified by
* \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks.
*
* It's intended only for use with 802.15.4 legacy Immediate ACKs and
* not 802.15.4E Enhanced ACKs.
* This will return \ref RAIL_STATUS_INVALID_STATE if it is too late to
* modify the outgoing Immediate ACK.
* @note This function is used to set the Frame Pending bit but its meaning
* depends on the value of
* \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks
* while transmitting ACK.
* If \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks
* is not set, then Frame Pending bit is set in outgoing ACK.
* Whereas, if \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks
* is set, then Frame Pending bit is cleared in outgoing ACK.
*
* Therefore, this function is to be called if the frame is pending when
* \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks
* is not set or if there is no frame pending when
* \ref RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks
* is set.
*/
RAIL_Status_t RAIL_IEEE802154_SetFramePending(RAIL_Handle_t railHandle);
/**
* Get the source address of the incoming data request.
*
* @param[in] railHandle A RAIL instance handle.
* @param[out] pAddress A pointer to \ref RAIL_IEEE802154_Address_t structure
* to populate with source address information.
* @return A status code indicating success of the function call.
*
* This function must only be called when handling the \ref
* RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event. This will return
* \ref RAIL_STATUS_INVALID_STATE if the address information is stale
* (i.e., it is too late to affect the outgoing ACK).
*/
RAIL_Status_t RAIL_IEEE802154_GetAddress(RAIL_Handle_t railHandle,
RAIL_IEEE802154_Address_t *pAddress);
/**
* Write the AutoACK FIFO for the next outgoing 802.15.4E Enhanced ACK.
*
* @param[in] railHandle A handle of RAIL instance.
* @param[in] ackData Pointer to ACK data to transmit
* @param[in] ackDataLen Length of ACK data, in bytes
* @return A status code indicating success of the function call.
*
* This function sets the AutoACK data to use in acknowledging the frame
* being received. It must only be called while processing the \ref
* RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND, and is intended for use
* when packet information from \ref RAIL_GetRxIncomingPacketInfo()
* indicates an 802.15.4E Enhanced ACK must be sent instead of a legacy
* Immediate ACK. \ref RAIL_IEEE802154_ToggleFramePending() should not be
* called for an Enhanced ACK; instead the Enhanced ACK's Frame Control
* Field should have the Frame Pending bit set appropriately in its ackData.
* This will return \ref RAIL_STATUS_INVALID_STATE if it is too late to
* write the outgoing ACK -- a situation that will likely trigger
* a \ref RAIL_EVENT_TXACK_UNDERFLOW event. When successful, the Enhanced
* ackData will only be sent once. Subsequent packets needing an Enhanced
* ACK will each need to call this function to write their ACK information.
*/
RAIL_Status_t RAIL_IEEE802154_WriteEnhAck(RAIL_Handle_t railHandle,
const uint8_t *ackData,
uint8_t ackDataLen);
/**
* Convert RSSI into 802.15.4 Link Quality Indication (LQI) metric
* compatible with the Silicon Labs Zigbee stack.
*
* @param[in] origLqi The original LQI, for example from
* \ref RAIL_RxPacketDetails_t::lqi.
* This parameter is not currently used but may be used in the future.
* @param[in] rssiDbm The RSSI in dBm, for example from
* \ref RAIL_RxPacketDetails_t::rssi.
* @return An LQI value (range 0..255 but not all intermediate values are
* possible) based on the rssiDbm and the chip's RSSI sensitivity range.
*
* This function is compatible with \ref RAIL_ConvertLqiCallback_t and
* is suitable to pass to \ref RAIL_ConvertLqi().
*/
uint8_t RAIL_IEEE802154_ConvertRssiToLqi(uint8_t origLqi, int8_t rssiDbm);
/**
* Convert RSSI into 802.15.4 Energy Detection (ED) metric
* compatible with the Silicon Labs Zigbee stack.
*
* @param[in] rssiDbm The RSSI in dBm, for example from
* \ref RAIL_RxPacketDetails_t::rssi.
* @return An Energy Detect value (range 0..255 but not all intermediate
* values are possible) based on the rssiDbm and the chip's RSSI
* sensitivity range.
*/
uint8_t RAIL_IEEE802154_ConvertRssiToEd(int8_t rssiDbm);
/** @} */ // end of IEEE802.15.4
#ifdef __cplusplus
}
#endif
#endif // __RAIL_IEEE802154_H__
Reference in New Issue View Git Blame Copy Permalink