IEEE 802.15.4#
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.
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);
}
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 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 RAIL_IEEE802154_AddrConfig_t documentation. Below is an example of setting filtering for one set of addresses.
// PAN Id over-the-air value of 0x34 0x12.
// Short Address over-the-air byte order of 0x78 0x56.
// Long address with over-the-air 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:
void 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);
assert(status == RAIL_STATUS_NO_ERROR);
status = RAIL_IEEE802154_SetShortAddress(railHandle, 0x5678, 0);
assert(status == RAIL_STATUS_NO_ERROR);
status = RAIL_IEEE802154_SetLongAddress(railHandle, longAddress, 0);
assert(status == RAIL_STATUS_NO_ERROR);
}
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 RAIL_IEEE802154_Config_t::ackConfig and RAIL_IEEE802154_Config_t::timings fields passed to RAIL_IEEE802154_Init(). After initialization, they may be controlled using the normal Auto-Ack and 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 RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event is triggered in which case it will default to the RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks setting. If the default Frame Pending setting is incorrect, the app must call RAIL_IEEE802154_ToggleFramePending() (formerly RAIL_IEEE802154_SetFramePending()) while handling the 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 if there is pending data. Note 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, use RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA define that can initialize the csmaConfig structure passed to RAIL_StartCcaCsmaTx().
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 sl_rail_init() and other setup functions. Instead of sl_rail_config_channels(), however, an application may use sl_rail_ieee802154_config_2p4_ghz_radio() 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 ack_timeout_us only covers sync word detection of the Ack. Therefore, subtract the Ack's PHY header and payload time to get RAIL's ack_timeout_us setting. For 2.4 GHz OQPSK, macAckWaitDuration is specified as 54 symbols; subtracting 2-symbol PHY header and 10-symbol payload yields a RAIL ack_timeout_us of 42 symbols or 672 microseconds at 16 microseconds/symbol.
static sl_rail_handle_t rail_handle = NULL; // Initialized somewhere else.
static const sl_rail_ieee802154_config_t rail_154_config = {
.p_addresses = NULL,
.ack_config = {
.enable = true, // Turn on auto Ack for IEEE 802.15.4.
.ack_timeout_us = 672, // See note above: 54-12 sym * 16 us/sym = 672 us.
.rx_transitions = {
.success = SL_RAIL_RF_STATE_RX, // Return to RX after Ack processing
.error = SL_RAIL_RF_STATE_RX, // Ignored
},
.tx_transitions = {
.success = SL_RAIL_RF_STATE_RX, // Return to RX after Ack processing
.error = SL_RAIL_RF_STATE_RX, // Ignored
},
},
.timings = {
.idle_to_rx = 100,
.idle_to_tx = 100,
.rx_to_tx = 192, // 12 symbols * 16 us/symbol = 192 us
.tx_to_rx = 192, // 12 symbols * 16 us/symbol = 192 us
.rxsearch_timeout = 0, // Not used
.tx_to_rxsearch_timeout = 0, // Not used
},
.frames_mask = SL_RAIL_IEEE802154_ACCEPT_STANDARD_FRAMES,
.promiscuous_mode = false, // Enable format and address filtering.
.is_pan_coordinator = false,
.default_frame_pending_in_outgoing_acks = false,
};
void config154(void)
{
// Configure the radio and channels for 2.4 GHz IEEE 802.15.4.
sl_rail_ieee802154_config_2p4_ghz_radio(rail_handle);
// Initialize the IEEE 802.15.4 configuration using the static configuration above.
sl_rail_ieee802154_init(rail_handle, &rail_154_config);
}
To configure address filtering, call sl_rail_ieee802154_set_addresses() with a structure containing all addresses or call the individual sl_rail_ieee802154_set_pan_id(), sl_rail_ieee802154_set_short_address(), and sl_rail_ieee802154_set_long_address() APIs. RAIL supports SL_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 sl_rail_ieee802154_addr_config_t documentation. Below is an example of setting filtering for one set of addresses.
// PAN Id over-the-air value of 0x34 0x12.
// Short Address over-the-air byte order of 0x78 0x56.
// Long address with over-the-air byte order of 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88.
// Set up all addresses simultaneously.
sl_rail_status_t setup_1(void)
{
sl_rail_ieee802154_addr_config_t node_addresses = {
.pan_id = { 0x1234, 0xFFFF, 0xFFFF },
.short_addr = { 0x5678, 0xFFFF, 0xFFFF },
.long_addr = { { 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 sl_rail_ieee802154_set_addresses(rail_handle, &node_addresses);
}
// Alternatively, the addresses can be set up individually as follows:
void setup_2(void)
{
sl_rail_status_t status;
const uint8_t long_address[] = { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88 };
status = sl_rail_ieee802154_set_pan_id(rail_handle, 0x1234, 0);
assert(status == SL_RAIL_STATUS_NO_ERROR);
status = sl_rail_ieee802154_set_short_address(rail_handle, 0x5678, 0);
assert(status == SL_RAIL_STATUS_NO_ERROR);
status = sl_rail_ieee802154_set_long_address(rail_handle, long_address, 0);
assert(status == SL_RAIL_STATUS_NO_ERROR);
}
Address filtering will be enabled except when in promiscuous mode, which can be set with sl_rail_ieee802154_set_promiscuous_mode(). 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 sl_rail_ieee802154_config_t::ack_config and sl_rail_ieee802154_config_t::timings fields passed to sl_rail_ieee802154_init(). After initialization, they may be controlled using the normal Auto-Ack and 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 SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event is triggered in which case it will default to the sl_rail_ieee802154_config_t::default_frame_pending_in_outgoing_acks setting. If the default Frame Pending setting is incorrect, the app must call sl_rail_ieee802154_toggle_frame_pending() while handling the SL_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 if there is pending data. Note 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 sl_rail_ieee802154_toggle_frame_pending() 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, use SL_RAIL_CSMA_CONFIG_802_15_4_2003_2P4_GHZ_OQPSK_CSMA define that can initialize the csma_config structure passed to sl_rail_start_cca_csma_tx().
Modules#
RAIL_IEEE802154_RxChannelSwitchingCfg_t
RAIL_IEEE802154_ModeSwitchPhr_t
sl_rail_ieee802154_addr_config_t
sl_rail_ieee802154_rx_channel_switching_cfg_t
sl_rail_ieee802154_mode_switch_phr_t
IEEE 802.15.4 Radio Configurations
Enumerations#
Different lengths that an 802.15.4 address can have.
802.15.4 PTI radio configuration mode
802.15.4E-2012 options, in reality a bitmask.
802.15.4G-2012 options, in reality a bitmask.
Available CCA modes.
Available Signal identifier modes.
Different lengths that an 802.15.4 address can have.
The 802.15.4 PHY identifier (aka PTI radio configuration id).
802.15.4E-2012 options, in reality a bitmask.
802.15.4G-2012 options, in reality a bitmask.
Available CCA modes.
Available Signal identifier modes.
Typedefs#
The 802.15.4 PHY feature bitmask.
Functions#
Initialize RAIL for IEEE802.15.4 features.
Configure the radio for 2.4 GHz 802.15.4 operation.
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity.
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence.
Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence.
Configure the radio for 2.4 GHz 802.15.4 operation with a front end module.
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for a front end module.
Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence and a front end module.
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence and a front end module.
Configure the radio for 2.4 GHz 802.15.4 operation with custom settings.
Configure the radio for Sub-GHz GB868 863 MHz 802.15.4 operation.
Configure the radio for Sub-GHz GB868 915 MHz 802.15.4 operation.
De-initialize IEEE802.15.4 hardware acceleration.
Return whether IEEE802.15.4 hardware acceleration is currently enabled.
Return IEEE802.15.4 PTI radio config.
Configure the RAIL Address Filter for 802.15.4 filtering.
Set a PAN Id for 802.15.4 address filtering.
Set a short address for 802.15.4 address filtering.
Set a long address for 802.15.4 address filtering.
Set whether the current node is a PAN coordinator.
Set whether to enable 802.15.4 promiscuous mode.
Configure certain 802.15.4E-2012 / 802.15.4-2015 Frame Version 2 features.
Configure certain 802.15.4G-2012 / 802.15.4-2015 SUN PHY features (only for radio configurations designed accordingly).
Compute channel to switch to given a targeted PHY Mode Id in the context of Wi-SUN mode switching.
Manage forbidden channels during mode switch.
Set which 802.15.4 frame types to accept.
Enable early Frame Pending lookup event notification (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND).
Enable Frame Pending lookup event notification (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND) for MAC Data frames.
Change the Frame Pending bit on the outgoing legacy Immediate Ack from the default specified by RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks.
Get the source address of the incoming data request.
Write the Auto-Ack FIFO for the next outgoing 802.15.4E Enhanced Ack.
Set a separate RX packet to TX state transition turnaround time for sending an Enhanced Ack.
Convert RSSI into 802.15.4 Link Quality Indication (LQI) metric compatible with the Silicon Labs Zigbee stack.
Convert RSSI into 802.15.4 Energy Detection (ED) metric compatible with the Silicon Labs Zigbee stack.
Configure signal identifier for 802.15.4 signal detection.
Enable or disable signal identifier for 802.15.4 signal detection.
Set 802.15.4 CCA mode.
Configure RX channel switching for 802.15.4.
Initialize RAIL for IEEE802.15.4 features.
Configure the radio for 2.4 GHz 802.15.4 operation.
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity.
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence.
Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence.
Configure the radio for 2.4 GHz 802.15.4 operation with a front end module.
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for a front end module.
Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence and a front end module.
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence and a front end module.
Configure the radio for Sub-GHz GB868 863 MHz 802.15.4 operation.
Configure the radio for Sub-GHz GB868 915 MHz 802.15.4 operation.
De-initialize IEEE802.15.4 hardware acceleration.
Return whether IEEE802.15.4 hardware acceleration is currently enabled.
Load an 802.15.4 channel config.
Return IEEE802.15.4 PHY identifier.
Configure the RAIL Address Filter for 802.15.4 filtering.
Set a PAN Id for 802.15.4 address filtering.
Set a short address for 802.15.4 address filtering.
Set a long address for 802.15.4 address filtering.
Set whether the current node is a PAN coordinator.
Set whether to enable 802.15.4 promiscuous mode.
Configure certain 802.15.4E-2012 / 802.15.4-2015 Frame Version 2 features.
Configure certain 802.15.4G-2012 / 802.15.4-2015 SUN PHY features (only for radio configurations designed accordingly).
Compute channel to switch to given a targeted PHY Mode Id in the context of Wi-SUN mode switching.
Manage forbidden channels during mode switch.
Set which 802.15.4 frame types to accept.
Enable early Frame Pending lookup event notification (SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND).
Enable Frame Pending lookup event notification (SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND) for MAC Data frames.
Change the Frame Pending bit on the outgoing legacy Immediate Ack from the default specified by sl_rail_ieee802154_config_t::default_frame_pending_in_outgoing_acks.
Get the source address of the incoming data request.
Write the Auto-Ack FIFO for the next outgoing 802.15.4E Enhanced Ack.
Set a separate RX packet to TX state transition turnaround time for sending an Enhanced Ack.
Convert RSSI into 802.15.4 Link Quality Indication (LQI) metric compatible with the Silicon Labs Zigbee stack.
Convert RSSI into 802.15.4 Energy Detection (ED) metric compatible with the Silicon Labs Zigbee stack.
Configure signal identifier for 802.15.4 signal detection.
Enable or disable signal identifier for 802.15.4 signal detection.
Set 802.15.4 CCA mode.
Configure RX channel switching for 802.15.4.
Macros#
The maximum number of allowed addresses of each type.
RX channel switching buffer size, in bytes.
Fixed-width type indicating the needed alignment for RX channel switching buffer.
Alignment that is needed for RX channel switching buffer.
Maximum numbers of channels supported for RX channel switching.
A value representing no options enabled.
All options disabled by default .
An option to enable/disable 802.15.4E-2012 features needed for GB868.
An option to enable/disable 802.15.4E-2012 features needed for Enhanced Acks.
An option to enable/disable 802.15.4E-2012 macImplicitBroadcast feature.
A value representing all possible options.
A value representing no options enabled.
All options disabled by default .
An option to enable/disable 802.15.4G-2012 features needed for GB868.
An option to enable/disable 802.15.4G dynamic FEC feature (SUN FSK only).
An option to enable/disable Wi-SUN Mode Switch feature.
A value representing all possible options.
When receiving packets, accept 802.15.4 BEACON frame types.
When receiving packets, accept 802.15.4 DATA frame types.
When receiving packets, accept 802.15.4 Ack frame types.
When receiving packets, accept 802.15.4 COMMAND frame types.
When receiving packets, accept 802.15.4-2015 Multipurpose frame types.
In standard operation, accept BEACON, DATA and COMMAND frames.
Alternate naming for function RAIL_IEEE802154_SetFramePending to depict it is used for changing the default setting specified by RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks in an outgoing Ack.
Backward compatible name for the RAIL_IEEE802154_EnableSignalDetection API.
The maximum number of allowed addresses of each type.
RX channel switching buffer size, in bytes.
Fixed-width type indicating the needed alignment for RX channel switching buffer.
Alignment that is needed for RX channel switching buffer.
Maximum numbers of channels supported for RX channel switching.
PHY id shift of extension for stackinfo.phyId.
PHY id bitmask of extension for stackinfo.phyId.
PHY id bitmask of 2-byte PHR length flag for use with indicated radio configurations.
PHY id bitmask for external (non-built-in) radio configuration.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_ANT_DIV bit.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_COEX bit.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_FEM bit.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_2_MBPS bit.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_1_MBPS_FEC bit.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_RX_CH_SWITCHING bit.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_RX_DUTY_CYCLING bit.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_FCS_2_MBPS bit.
Shift position of SL_RAIL_IEEE802154_PHY_FEATURE_2P4_GHZ_FCS_1_MBPS_FEC bit.
No IEEE802.15.4 features selected.
RX antenna diversity feature.
WiFi coex feature.
Front end module feature.
Mode switch feature for 2Mbps 2.4 GHz operation.
Mode switch feature for 1Mbps 2.4 GHz operation with forward error correction (1-byte PHR).
RX channel switching feature.
RX Duty cycling feature.
Mode switch feature for 2Mbps 2.4 GHz operation with fast channel switching.
Mode switch feature for 1Mbps 2.4 GHz operation with forward error correction (1-byte PHR) and fast channel switching.
RX antenna diversity and WiFi coex features.
Front end module and RX antenna diversity features.
Front end module and WiFi coex feature.
Front end module and RX antenna diversity and WiFi coex feature.
A value representing no options enabled.
All options disabled by default .
An option to enable/disable 802.15.4E-2012 features needed for GB868.
An option to enable/disable 802.15.4E-2012 features needed for Enhanced Acks.
An option to enable/disable 802.15.4E-2012 macImplicitBroadcast feature.
A value representing all possible options.
A value representing no options enabled.
All options disabled by default .
An option to enable/disable 802.15.4G-2012 features needed for GB868.
An option to enable/disable 802.15.4G dynamic FEC feature (SUN FSK only).
An option to enable/disable Wi-SUN Mode Switch feature.
A value representing all possible options.
When receiving packets, accept 802.15.4 BEACON frame types.
When receiving packets, accept 802.15.4 DATA frame types.
When receiving packets, accept 802.15.4 Ack frame types.
When receiving packets, accept 802.15.4 COMMAND frame types.
When receiving packets, accept 802.15.4-2015 Multipurpose frame types.
In standard operation, accept BEACON, DATA and COMMAND frames.
Enumeration Documentation#
RAIL_IEEE802154_AddressLength_t#
RAIL_IEEE802154_AddressLength_t
Different lengths that an 802.15.4 address can have.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_address_length_t.
| Enumerator | |
|---|---|
| RAIL_IEEE802154_ShortAddress | 2 byte short address. |
| RAIL_IEEE802154_LongAddress | 8 byte extended address. |
RAIL_IEEE802154_PtiRadioConfig_t#
RAIL_IEEE802154_PtiRadioConfig_t
802.15.4 PTI radio configuration mode
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_phy_t.
| Enumerator | |
|---|---|
| RAIL_IEEE802154_PTI_RADIO_CONFIG_2P4GHZ | Built-in 2.4 GHz 802.15.4 radio configuration. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_2P4GHZ_ANTDIV | Built-in 2.4 GHz 802.15.4 radio configuration with RX antenna diversity support. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_2P4GHZ_COEX | Built-in 2.4 GHz 802.15.4 radio configuration optimized for radio coexistence. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_2P4GHZ_ANTDIV_COEX | Built-in 2.4 GHz 802.15.4 radio configuration with RX antenna diversity support optimized for radio coexistence. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_2P4GHZ_FEM | Built-in 2.4 GHz 802.15.4 radio configuration optimized for front end modules. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_2P4GHZ_FEM_ANTDIV | Built-in 2.4 GHz 802.15.4 radio configuration with RX antenna diversity support optimized for front end modules. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_2P4GHZ_FEM_COEX | Built-in 2.4 GHz 802.15.4 radio configuration optimized for radio coexistence and front end modules. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_2P4GHZ_FEM_ANTDIV_COEX | Built-in 2.4 GHz 802.15.4 radio configuration with RX antenna diversity support optimized for radio coexistence and front end modules. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_863MHZ_GB868 | Built-in 863 MHz GB868 802.15.4 radio configuration. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_915MHZ_GB868 | Built-in 915 MHz GB868 802.15.4 radio configuration. |
| RAIL_IEEE802154_PTI_RADIO_CONFIG_915MHZ_R23_NA_EXT | External 915 MHz Zigbee R23 802.15.4 NA radio configuration. |
RAIL_IEEE802154_EOptions_t#
RAIL_IEEE802154_EOptions_t
802.15.4E-2012 options, in reality a bitmask.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_e_options_t.
| Enumerator | |
|---|---|
| RAIL_IEEE802154_E_OPTION_GB868_SHIFT | Shift position of RAIL_IEEE802154_E_OPTION_GB868 bit. |
| RAIL_IEEE802154_E_OPTION_ENH_ACK_SHIFT | Shift position of RAIL_IEEE802154_E_OPTION_ENH_ACK bit. |
| RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST_SHIFT | Shift position of RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST bit. |
RAIL_IEEE802154_GOptions_t#
RAIL_IEEE802154_GOptions_t
802.15.4G-2012 options, in reality a bitmask.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_g_options_t.
| Enumerator | |
|---|---|
| RAIL_IEEE802154_G_OPTION_GB868_SHIFT | Shift position of RAIL_IEEE802154_G_OPTION_GB868 bit. |
| RAIL_IEEE802154_G_OPTION_DYNFEC_SHIFT | Shift position of RAIL_IEEE802154_G_OPTION_DYNFEC bit. |
| RAIL_IEEE802154_G_OPTION_WISUN_MODESWITCH_SHIFT | Shift position of RAIL_IEEE802154_G_OPTION_WISUN_MODESWITCH bit. |
RAIL_IEEE802154_CcaMode_t#
RAIL_IEEE802154_CcaMode_t
Available CCA modes.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_cca_mode_t.
| Enumerator | |
|---|---|
| RAIL_IEEE802154_CCA_MODE_RSSI | RSSI-based CCA. |
| RAIL_IEEE802154_CCA_MODE_SIGNAL | Signal Identifier-based CCA. |
| RAIL_IEEE802154_CCA_MODE_SIGNAL_OR_RSSI | RSSI or signal identifier-based CCA. |
| RAIL_IEEE802154_CCA_MODE_SIGNAL_AND_RSSI | RSSI and signal identifier-based CCA. |
| RAIL_IEEE802154_CCA_MODE_ALWAYS_TRANSMIT | ALOHA. |
| RAIL_IEEE802154_CCA_MODE_COUNT | Number of CCA modes. |
RAIL_IEEE802154_SignalIdentifierMode_t#
RAIL_IEEE802154_SignalIdentifierMode_t
Available Signal identifier modes.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_signal_identifier_mode_t.
| Enumerator | |
|---|---|
| RAIL_IEEE802154_SIGNAL_IDENTIFIER_MODE_DISABLE | Disable signal detection mode. |
| RAIL_IEEE802154_SIGNAL_IDENTIFIER_MODE_154 | 2.4 GHz 802.15.4 signal detection mode. |
sl_rail_ieee802154_address_length_t#
sl_rail_ieee802154_address_length_t
Different lengths that an 802.15.4 address can have.
| Enumerator | |
|---|---|
| SL_RAIL_IEEE802154_SHORT_ADDRESS | 2 byte short address. |
| SL_RAIL_IEEE802154_LONG_ADDRESS | 8 byte extended address. |
sl_rail_ieee802154_phy_t#
sl_rail_ieee802154_phy_t
The 802.15.4 PHY identifier (aka PTI radio configuration id).
| Enumerator | |
|---|---|
| SL_RAIL_IEEE802154_PHY_2P4_GHZ | Built-in 2.4 GHz 802.15.4 radio configuration. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_ANT_DIV | Built-in 2.4 GHz 802.15.4 radio configuration with RX antenna diversity support. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_COEX | Built-in 2.4 GHz 802.15.4 radio configuration optimized for radio coexistence. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_ANT_DIV_COEX | Built-in 2.4 GHz 802.15.4 radio configuration with RX antenna diversity support optimized for radio coexistence. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_FEM | Built-in 2.4 GHz 802.15.4 radio configuration optimized for front end modules. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_FEM_ANT_DIV | Built-in 2.4 GHz 802.15.4 radio configuration with RX antenna diversity support optimized for front end modules. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_FEM_COEX | Built-in 2.4 GHz 802.15.4 radio configuration optimized for radio coexistence and front end modules. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_FEM_ANT_DIV_COEX | Built-in 2.4 GHz 802.15.4 radio configuration with RX antenna diversity support optimized for radio coexistence and front end modules. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_2_MBPS | 2Mbps 2.4 GHz operation (1-byte PHR). |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_RX_CH_SWITCHING | Built-in 2.4 GHz 802.15.4 radio configuration with RX channel switching support optimized. |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_1_MBPS_FEC | Built-in 2.4 GHz 802.15.4 radio configuration with mode switch to 1Mbps 2.4 GHz operation with forward error correction (1-byte PHR). |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_FCS_2_MBPS | Built-in 2.4 GHz 802.15.4 radio configuration with RX channel switching and 2Mbps 2.4 GHz operation (1-byte PHR). |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_FCS_1_MBPS_FEC | Built-in 2.4 GHz 802.15.4 radio configuration with RX channel switching and 1Mbps 2.4 GHz operation with forward error correction (1-byte PHR). |
| SL_RAIL_IEEE802154_PHY_2P4_GHZ_RX_DUTY_CYCLING | Built-in 2.4 GHz 802.15.4 radio configuration with duty cycling. |
| SL_RAIL_IEEE802154_PHY_863_MHZ_GB868 | Built-in 863 MHz GB868 802.15.4 radio configuration. |
| SL_RAIL_IEEE802154_PHY_915_MHZ_GB868 | Built-in 915 MHz GB868 802.15.4 radio configuration. |
sl_rail_ieee802154_e_options_t#
sl_rail_ieee802154_e_options_t
802.15.4E-2012 options, in reality a bitmask.
| Enumerator | |
|---|---|
| SL_RAIL_IEEE802154_E_OPTION_GB868_SHIFT | Shift position of SL_RAIL_IEEE802154_E_OPTION_GB868 bit. |
| SL_RAIL_IEEE802154_E_OPTION_ENH_ACK_SHIFT | Shift position of SL_RAIL_IEEE802154_E_OPTION_ENH_ACK bit. |
| SL_RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST_SHIFT | Shift position of SL_RAIL_IEEE802154_E_OPTION_IMPLICIT_BROADCAST bit. |
sl_rail_ieee802154_g_options_t#
sl_rail_ieee802154_g_options_t
802.15.4G-2012 options, in reality a bitmask.
| Enumerator | |
|---|---|
| SL_RAIL_IEEE802154_G_OPTION_GB868_SHIFT | Shift position of SL_RAIL_IEEE802154_G_OPTION_GB868 bit. |
| SL_RAIL_IEEE802154_G_OPTION_DYN_FEC_SHIFT | Shift position of SL_RAIL_IEEE802154_G_OPTION_DYN_FEC bit. |
| SL_RAIL_IEEE802154_G_OPTION_WI_SUN_MODE_SWITCH_SHIFT | Shift position of SL_RAIL_IEEE802154_G_OPTION_WI_SUN_MODE_SWITCH bit. |
sl_rail_ieee802154_cca_mode_t#
sl_rail_ieee802154_cca_mode_t
Available CCA modes.
| Enumerator | |
|---|---|
| SL_RAIL_IEEE802154_CCA_MODE_RSSI | RSSI-based CCA. |
| SL_RAIL_IEEE802154_CCA_MODE_SIGNAL | Signal Identifier-based CCA. |
| SL_RAIL_IEEE802154_CCA_MODE_SIGNAL_OR_RSSI | RSSI or signal identifier-based CCA. |
| SL_RAIL_IEEE802154_CCA_MODE_SIGNAL_AND_RSSI | RSSI and signal identifier-based CCA. |
| SL_RAIL_IEEE802154_CCA_MODE_ALWAYS_TRANSMIT | ALOHA. |
| SL_RAIL_IEEE802154_CCA_MODE_COUNT | Number of CCA modes. |
sl_rail_ieee802154_signal_identifier_mode_t#
sl_rail_ieee802154_signal_identifier_mode_t
Available Signal identifier modes.
| Enumerator | |
|---|---|
| SL_RAIL_IEEE802154_SIGNAL_IDENTIFIER_MODE_DISABLE | Disable signal detection mode. |
| SL_RAIL_IEEE802154_SIGNAL_IDENTIFIER_MODE_154 | 2.4 GHz 802.15.4 signal detection mode with SI block reset on GPIO falling edge (via PRS). |
| SL_RAIL_IEEE802154_SIGNAL_IDENTIFIER_MODE_154_WITH_AGC_RESET | 2.4 GHz 802.15.4 signal detection mode with SI block reset on AGC negative step. |
Typedef Documentation#
sl_rail_ieee802154_phy_features_t#
sl_rail_ieee802154_phy_features_t
The 802.15.4 PHY feature bitmask.
Function Documentation#
RAIL_IEEE802154_Init#
RAIL_Status_t RAIL_IEEE802154_Init (RAIL_Handle_t railHandle, const RAIL_IEEE802154_Config_t * config)
Initialize RAIL for IEEE802.15.4 features.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const RAIL_IEEE802154_Config_t * | [in] | config | A non-NULL pointer to an IEEE802154 configuration structure. |
Returns
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:
It must be called before most of the RAIL_IEEE802154_* functions.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_init().
RAIL_IEEE802154_Config2p4GHzRadio#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadio (RAIL_Handle_t railHandle)
Configure the radio for 2.4 GHz 802.15.4 operation.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
This initializes the radio for 2.4 GHz operation. It takes the place of calling 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.
Note
This call implicitly disables all RAIL_IEEE802154_GOptions_t.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_2p4_ghz_radio().
RAIL_IEEE802154_Config2p4GHzRadioAntDiv#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDiv (RAIL_Handle_t railHandle)
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
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 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.
Note
This call implicitly disables all RAIL_IEEE802154_GOptions_t.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_2p4_ghz_radio_ant_div().
RAIL_IEEE802154_Config2p4GHzRadioAntDivCoex#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDivCoex (RAIL_Handle_t railHandle)
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
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 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.
Note
This call implicitly disables all RAIL_IEEE802154_GOptions_t.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_coex().
RAIL_IEEE802154_Config2p4GHzRadioCoex#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioCoex (RAIL_Handle_t railHandle)
Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
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 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.
Note
This call implicitly disables all RAIL_IEEE802154_GOptions_t.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_2p4_ghz_radio_coex().
RAIL_IEEE802154_Config2p4GHzRadioFem#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioFem (RAIL_Handle_t railHandle)
Configure the radio for 2.4 GHz 802.15.4 operation with a front end module.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
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 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.
Note
This call implicitly disables all RAIL_IEEE802154_GOptions_t.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_2p4_ghz_radio_fem().
RAIL_IEEE802154_Config2p4GHzRadioAntDivFem#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDivFem (RAIL_Handle_t railHandle)
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for a front end module.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
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 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.
Note
This call implicitly disables all RAIL_IEEE802154_GOptions_t.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_fem().
RAIL_IEEE802154_Config2p4GHzRadioCoexFem#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioCoexFem (RAIL_Handle_t railHandle)
Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence and a front end module.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
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 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.
Note
This call implicitly disables all RAIL_IEEE802154_GOptions_t.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_2p4_ghz_radio_coex_fem().
RAIL_IEEE802154_Config2p4GHzRadioAntDivCoexFem#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioAntDivCoexFem (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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
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 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.
Note
This call implicitly disables all RAIL_IEEE802154_GOptions_t.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_coex_fem().
RAIL_IEEE802154_Config2p4GHzRadioCustom1#
RAIL_Status_t RAIL_IEEE802154_Config2p4GHzRadioCustom1 (RAIL_Handle_t railHandle)
Configure the radio for 2.4 GHz 802.15.4 operation with custom settings.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
It enables better interoperability with some proprietary PHYs, but doesn't guarantee data sheet performance.
Returns
Status code indicating success of the function call.
This initializes the radio for 2.4 GHz operation with custom settings. It replaces needing to call RAIL_ConfigChannels(). Do not call this function unless instructed by Silicon Labs.
Note
This feature is only available on platforms where RAIL_IEEE802154_SUPPORTS_CUSTOM1_PHY is true.
DeprecatedThis RAIL 2.x function has been eliminated in RAIL 3; it is no longer supported.
RAIL_IEEE802154_ConfigGB863MHzRadio#
RAIL_Status_t RAIL_IEEE802154_ConfigGB863MHzRadio (RAIL_Handle_t railHandle)
Configure the radio for Sub-GHz GB868 863 MHz 802.15.4 operation.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
This initializes the radio for Sub-GHz GB868 863 MHz operation. It takes the place of calling 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.
Note
This call implicitly enables RAIL_IEEE802154_G_OPTION_GB868.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_gb863_mhz_radio().
RAIL_IEEE802154_ConfigGB915MHzRadio#
RAIL_Status_t RAIL_IEEE802154_ConfigGB915MHzRadio (RAIL_Handle_t railHandle)
Configure the radio for Sub-GHz GB868 915 MHz 802.15.4 operation.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
This initializes the radio for Sub-GHz GB868 915 MHz operation. It takes the place of calling 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.
Note
This call implicitly enables RAIL_IEEE802154_G_OPTION_GB868.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_gb915_mhz_radio().
RAIL_IEEE802154_Deinit#
RAIL_Status_t RAIL_IEEE802154_Deinit (RAIL_Handle_t railHandle)
De-initialize IEEE802.15.4 hardware acceleration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
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() passing false for its enable parameter
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_deinit().
RAIL_IEEE802154_IsEnabled#
bool RAIL_IEEE802154_IsEnabled (RAIL_Handle_t railHandle)
Return whether IEEE802.15.4 hardware acceleration is currently enabled.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
true if IEEE802.15.4 hardware acceleration was enabled to start with and false otherwise.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_is_enabled().
RAIL_IEEE802154_GetPtiRadioConfig#
RAIL_IEEE802154_PtiRadioConfig_t RAIL_IEEE802154_GetPtiRadioConfig (RAIL_Handle_t railHandle)
Return IEEE802.15.4 PTI radio config.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
PTI (Packet Trace Information) radio config Id.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_get_phy_id().
RAIL_IEEE802154_SetAddresses#
RAIL_Status_t RAIL_IEEE802154_SetAddresses (RAIL_Handle_t railHandle, const RAIL_IEEE802154_AddrConfig_t * addresses)
Configure the RAIL Address Filter for 802.15.4 filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const RAIL_IEEE802154_AddrConfig_t * | [in] | addresses | A pointer to the address information that should be used. |
Returns
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.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_set_addresses().
RAIL_IEEE802154_SetPanId#
RAIL_Status_t RAIL_IEEE802154_SetPanId (RAIL_Handle_t railHandle, uint16_t panId, uint8_t index)
Set a PAN Id for 802.15.4 address filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint16_t | [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. |
| uint8_t | [in] | index | Indicates which PAN Id to set. Must be below RAIL_IEEE802154_MAX_ADDRESSES. |
Returns
Status code indicating success of the function call.
Set up the 802.15.4 address filter to accept messages to the given PAN Id.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_set_pan_id().
RAIL_IEEE802154_SetShortAddress#
RAIL_Status_t RAIL_IEEE802154_SetShortAddress (RAIL_Handle_t railHandle, uint16_t shortAddr, uint8_t index)
Set a short address for 802.15.4 address filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A handle of RAIL instance |
| uint16_t | [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. |
| uint8_t | [in] | index | Which short address to set. Must be below RAIL_IEEE802154_MAX_ADDRESSES. |
Returns
Status code indicating success of the function call.
Set up the 802.15.4 address filter to accept messages to the given short address.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_set_short_address().
RAIL_IEEE802154_SetLongAddress#
RAIL_Status_t RAIL_IEEE802154_SetLongAddress (RAIL_Handle_t railHandle, const uint8_t * longAddr, uint8_t index)
Set a long address for 802.15.4 address filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const uint8_t * | [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. |
| uint8_t | [in] | index | Indicates which long address to set. Must be below RAIL_IEEE802154_MAX_ADDRESSES. |
Returns
Status code indicating success of the function call.
Set up the 802.15.4 address filter to accept messages to the given long address.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_set_long_address().
RAIL_IEEE802154_SetPanCoordinator#
RAIL_Status_t RAIL_IEEE802154_SetPanCoordinator (RAIL_Handle_t railHandle, bool isPanCoordinator)
Set whether the current node is a PAN coordinator.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| bool | [in] | isPanCoordinator | true if this device is a PAN coordinator. |
Returns
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 by calling RAIL_IEEE802154_Init(). This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_set_pan_coordinator().
RAIL_IEEE802154_SetPromiscuousMode#
RAIL_Status_t RAIL_IEEE802154_SetPromiscuousMode (RAIL_Handle_t railHandle, bool enable)
Set whether to enable 802.15.4 promiscuous mode.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| bool | [in] | enable | true if all frames and addresses should be accepted. |
Returns
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 by calling RAIL_IEEE802154_Init(). This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_set_promiscuous_mode().
RAIL_IEEE802154_ConfigEOptions#
RAIL_Status_t RAIL_IEEE802154_ConfigEOptions (RAIL_Handle_t railHandle, RAIL_IEEE802154_EOptions_t mask, RAIL_IEEE802154_EOptions_t options)
Configure certain 802.15.4E-2012 / 802.15.4-2015 Frame Version 2 features.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_IEEE802154_EOptions_t | [in] | mask | A bitmask containing which options should be modified. |
| RAIL_IEEE802154_EOptions_t | [in] | options | A bitmask containing desired options settings. Bit positions for each option are found in the RAIL_IEEE802154_EOptions_t. |
Returns
Status code indicating success of the function call.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling RAIL_IEEE802154_Init() 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.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_e_options().
RAIL_IEEE802154_ConfigGOptions#
RAIL_Status_t RAIL_IEEE802154_ConfigGOptions (RAIL_Handle_t railHandle, RAIL_IEEE802154_GOptions_t mask, RAIL_IEEE802154_GOptions_t options)
Configure certain 802.15.4G-2012 / 802.15.4-2015 SUN PHY features (only for radio configurations designed accordingly).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_IEEE802154_GOptions_t | [in] | mask | A bitmask containing which options should be modified. |
| RAIL_IEEE802154_GOptions_t | [in] | options | A bitmask containing desired options settings. Bit positions for each option are found in the RAIL_IEEE802154_GOptions_t. |
Returns
Status code indicating success of the function call.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling RAIL_IEEE802154_Init(), the platform does not support the feature(s), the radio configuration is not appropriate, or the radio is not idle.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_g_options().
RAIL_IEEE802154_ComputeChannelFromPhyModeId#
RAIL_Status_t RAIL_IEEE802154_ComputeChannelFromPhyModeId (RAIL_Handle_t railHandle, uint8_t newPhyModeId, uint16_t * pChannel)
Compute channel to switch to given a targeted PHY Mode Id in the context of Wi-SUN mode switching.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint8_t | [in] | newPhyModeId | A targeted PHY Mode Id. |
| uint16_t * | [out] | pChannel | A pointer to the channel to switch to. |
Returns
Status code indicating success of the function call.
This function will fail if:
the targeted PHY Mode Id is the same as the current PHY Mode Id
called on a platform that lacks RAIL_IEEE802154_SUPPORTS_G_MODESWITCH
called on a platform that doesn't have 802154G options enabled by RAIL_IEEE802154_ConfigGOptions(). For newPhyModeId associated with a FSK FEC_off PHY, if dynamic FEC is activated (see RAIL_IEEE802154_G_OPTION_DYNFEC), the returned channel can correspond to the associated FSK FEC_on PHY corresponding then to PHY Mode Id = newPhyModeId + 16
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_compute_channel_from_phy_mode_id().
RAILCb_IEEE802154_IsModeSwitchNewChannelValid#
RAIL_Status_t RAILCb_IEEE802154_IsModeSwitchNewChannelValid (uint32_t currentBaseFreq, uint8_t newPhyModeId, const RAIL_ChannelConfigEntry_t * configEntryNewPhyModeId, uint16_t * pChannel)
Manage forbidden channels during mode switch.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | currentBaseFreq | The current frequency of the base channel. |
| uint8_t | [in] | newPhyModeId | A targeted PHY Mode Id. |
| const RAIL_ChannelConfigEntry_t * | [in] | configEntryNewPhyModeId | A pointer to RAIL_ChannelConfigEntry_t structure corresponding to the new PHY configEntry. |
| uint16_t * | [inout] | pChannel | A pointer to the channel to switch to. If channel is valid, the function must just return. If channel is forbidden, the function must update it with the closest valid channel. The highest channel must be selected in case of two valid channels being equidistant to a forbidden channel. |
Returns
Status code indicating success of the function call. It must return RAIL_STATUS_INVALID_PARAMETER for failure or RAIL_STATUS_NO_ERROR for success.
This function must fail if no valid channel has been found. If so, RAIL will abort the mode switch.
Note
This callback will only be called on platforms where RAIL_IEEE802154_SUPPORTS_G_MODESWITCH is true, RAIL_IEEE802154_G_OPTION_WISUN_MODESWITCH was successfully enabled, and a valid mode switch PHY header is received.
DeprecatedRAIL 2.x synonym of sl_railcb_ieee802154_is_mode_switch_new_channel_valid().
RAIL_IEEE802154_AcceptFrames#
RAIL_Status_t RAIL_IEEE802154_AcceptFrames (RAIL_Handle_t railHandle, uint8_t framesMask)
Set which 802.15.4 frame types to accept.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint8_t | [in] | framesMask | A mask containing which 802.15.4 frame types to receive. |
Returns
Status code indicating success of the function call.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling RAIL_IEEE802154_Init() 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 frames may be received. The RAIL_IEEE802154_ACCEPT_*_FRAMES defines may be combined to create a bitmask to pass into this function.
RAIL_IEEE802154_ACCEPT_ACK_FRAMES behaves slightly different than the other defines. If 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 RAIL_RxPacketDetails_t::isAck true. If 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.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_accept_frames().
RAIL_IEEE802154_EnableEarlyFramePending#
RAIL_Status_t RAIL_IEEE802154_EnableEarlyFramePending (RAIL_Handle_t railHandle, bool enable)
Enable early Frame Pending lookup event notification (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| bool | [in] | enable | true to enable, false to disable. |
Returns
Status code indicating success of the function call.
Normally, RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered after receiving the entire MAC header and MAC command byte for an Ack-requesting MAC command frame. Version 0/1 frames also require that command to be a Data Request for this event to occur. Enabling this feature causes this event to be triggered earlier to allow for more time to determine the type of Ack needed (Immediate or Enhanced) and/or perform frame pending lookup to influence the outgoing Ack by using RAIL_IEEE802154_WriteEnhAck() or RAIL_IEEE802154_ToggleFramePending().
For Frame Version 0/1 packets and for Frame Version 2 packets when RAIL_IEEE802154_E_OPTION_ENH_ACK is not in use, "early" means right after receiving the source address information in the MAC header.
For Frame Version 2 packets when RAIL_IEEE802154_E_OPTION_ENH_ACK is in use, "early" means right after receiving any Auxiliary Security header which follows the source address information in the MAC header.
This feature is useful when the protocol knows an Ack-requesting MAC Command must be a data poll without needing to receive the MAC Command byte, giving it a bit more time to adjust Frame Pending or generate an Enhanced Ack.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling RAIL_IEEE802154_Init(), 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.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_enable_early_frame_pending().
RAIL_IEEE802154_EnableDataFramePending#
RAIL_Status_t RAIL_IEEE802154_EnableDataFramePending (RAIL_Handle_t railHandle, bool enable)
Enable Frame Pending lookup event notification (RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND) for MAC Data frames.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| bool | [in] | enable | true to enable, false to disable. |
Returns
Status code indicating success of the function call.
Normally RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered only for Ack-requesting MAC command frames. Enabling this feature causes this event to also be triggered for MAC data frames, at the same point in the packet as RAIL_IEEE802154_EnableEarlyFramePending() would trigger. This feature is necessary to support the Thread Basil-Hayden Enhanced Frame Pending feature in Version 0/1 frames, and to support Version 2 Data frames which require an Enhanced Ack.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling RAIL_IEEE802154_Init(). This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_enable_data_frame_pending().
RAIL_IEEE802154_SetFramePending#
RAIL_Status_t RAIL_IEEE802154_SetFramePending (RAIL_Handle_t railHandle)
Change the Frame Pending bit on the outgoing legacy Immediate Ack from the default specified by RAIL_IEEE802154_Config_t::defaultFramePendingInOutgoingAcks.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A handle of RAIL instance |
Returns
Status code indicating success of the function call.
This function must only be called while processing the 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 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 RAIL_STATUS_INVALID_STATE if it is too late to modify the outgoing Immediate Ack.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_toggle_frame_pending().
RAIL_IEEE802154_GetAddress#
RAIL_Status_t RAIL_IEEE802154_GetAddress (RAIL_Handle_t railHandle, RAIL_IEEE802154_Address_t * pAddress)
Get the source address of the incoming data request.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_IEEE802154_Address_t * | [out] | pAddress | A pointer to RAIL_IEEE802154_Address_t structure to populate with source address information. |
Returns
Status code indicating success of the function call.
This function must only be called when handling the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event. This will return RAIL_STATUS_INVALID_STATE if the address information is stale (i.e., it is too late to affect the outgoing Ack).
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_get_address().
RAIL_IEEE802154_WriteEnhAck#
RAIL_Status_t RAIL_IEEE802154_WriteEnhAck (RAIL_Handle_t railHandle, const uint8_t * ackData, uint16_t ackDataLen)
Write the Auto-Ack FIFO for the next outgoing 802.15.4E Enhanced Ack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const uint8_t * | [in] | ackData | A pointer to Ack data to transmit This may be NULL, in which case it's assumed the data has already been emplaced into the Ack buffer and RAIL just needs to be told how many bytes are there. Use RAIL_GetAutoAckFifo() to get the address of RAIL's Auto-Ack buffer in RAM and its size. |
| uint16_t | [in] | ackDataLen | Length of Ack data, in bytes. If this exceeds RAIL_AUTOACK_MAX_LENGTH the function will return RAIL_STATUS_INVALID_PARAMETER. |
Returns
Status code indicating success of the function call.
This function sets the Auto-Ack data to use in acknowledging the frame being received. It must only be called while processing the RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND, and is intended for use when packet information from RAIL_GetRxIncomingPacketInfo() indicates an 802.15.4E Enhanced Ack must be sent instead of a legacy Immediate Ack. 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 RAIL_STATUS_INVALID_STATE if it is too late to write the outgoing Ack – a situation that will likely trigger a 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.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_write_enh_ack().
RAIL_IEEE802154_SetRxToEnhAckTx#
RAIL_Status_t RAIL_IEEE802154_SetRxToEnhAckTx (RAIL_Handle_t railHandle, RAIL_TransitionTime_t * pRxToEnhAckTx)
Set a separate RX packet to TX state transition turnaround time for sending an Enhanced Ack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_TransitionTime_t * | [inout] | pRxToEnhAckTx | A pointer to the turnaround transition requested for Enhanced Acks. It will be updated with the actual time set. Requesting a time of 0 will sync the Enhanced Ack turnaround time with that used for immediate Acks (and output 0). Requesting a time of RAIL_TRANSITION_TIME_KEEP will output the current Enhanced Ack timing parameter (0 if it is the same as that used for Immediate Acks). |
Returns
Status code indicating a success of the function call. An error will not update the pRxToEnhAckTx output parameter.
Normally Immediate and Enhanced Acks are both sent using the RAIL_IEEE802154_Config_t::timings rxToTx turnaround time. If the stack needs more time to prepare an Enhanced Ack, it can call this function after RAIL_IEEE802154_Init() to set a longer turnaround time used just for Enhanced Ack transmits.
This function will fail on platforms that lack RAIL_IEEE802154_SUPPORTS_E_ENHANCED_ACK.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_set_rx_to_enh_ack_tx().
RAIL_IEEE802154_ConvertRssiToLqi#
uint8_t RAIL_IEEE802154_ConvertRssiToLqi (uint8_t origLqi, int8_t rssiDbm)
Convert RSSI into 802.15.4 Link Quality Indication (LQI) metric compatible with the Silicon Labs Zigbee stack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | [in] | origLqi | The original LQI, for example from RAIL_RxPacketDetails_t::lqi. This parameter is not currently used but may be used in the future. |
| int8_t | [in] | rssiDbm | The RSSI in dBm, for example from RAIL_RxPacketDetails_t::rssi. |
Returns
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 RAIL_ConvertLqiCallback_t() and is suitable to pass to RAIL_ConvertLqi().
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_convert_rssi_to_lqi().
RAIL_IEEE802154_ConvertRssiToEd#
uint8_t RAIL_IEEE802154_ConvertRssiToEd (int8_t rssiDbm)
Convert RSSI into 802.15.4 Energy Detection (ED) metric compatible with the Silicon Labs Zigbee stack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| int8_t | [in] | rssiDbm | The RSSI in dBm, for example from RAIL_RxPacketDetails_t::rssi. |
Returns
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.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_convert_rssi_to_ed().
RAIL_IEEE802154_ConfigSignalIdentifier#
RAIL_Status_t RAIL_IEEE802154_ConfigSignalIdentifier (RAIL_Handle_t railHandle, RAIL_IEEE802154_SignalIdentifierMode_t signalIdentifierMode)
Configure signal identifier for 802.15.4 signal detection.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_IEEE802154_SignalIdentifierMode_t | [in] | signalIdentifierMode | Mode of signal identifier operation. |
This features allows detection of 2.4 GHz 802.15.4 signal on air. This function must be called once before RAIL_IEEE802154_EnableSignalDetection() to configure and enable signal identifier.
To enable event for signal detection RAIL_ConfigEvents() must be called for enabling RAIL_EVENT_SIGNAL_DETECTED.
This function is only supported by chips where RAIL_IEEE802154_SUPPORTS_SIGNAL_IDENTIFIER and RAIL_IEEE802154_SupportsSignalIdentifier() are true.
Returns
Status code indicating success of the function call.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_signal_identifier().
RAIL_IEEE802154_EnableSignalDetection#
RAIL_Status_t RAIL_IEEE802154_EnableSignalDetection (RAIL_Handle_t railHandle, bool enable)
Enable or disable signal identifier for 802.15.4 signal detection.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| bool | [in] | enable | Signal detection is enabled if true, disabled if false. |
RAIL_IEEE802154_ConfigSignalIdentifier() must be called once before calling this function to configure and enable signal identifier. Once a signal is detected signal detection will be turned off and this function should be called to re-enable the signal detection without needing to call RAIL_IEEE802154_ConfigSignalIdentifier() if the signal identifier is already configured and enabled.
This function is only supported by chips where RAIL_IEEE802154_SUPPORTS_SIGNAL_IDENTIFIER and RAIL_IEEE802154_SupportsSignalIdentifier() are true.
Returns
Status code indicating success of the function call.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_enable_signal_detection().
RAIL_IEEE802154_ConfigCcaMode#
RAIL_Status_t RAIL_IEEE802154_ConfigCcaMode (RAIL_Handle_t railHandle, RAIL_IEEE802154_CcaMode_t ccaMode)
Set 802.15.4 CCA mode.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_IEEE802154_CcaMode_t | [in] | ccaMode | Mode of CCA operation. |
This function sets the CCA mode RAIL_IEEE802154_CcaMode_t. If not called, RAIL_IEEE802154_CCA_MODE_RSSI (RSSI-based CCA) is used for CCA.
In RAIL_IEEE802154_CCA_MODE_SIGNAL, RAIL_IEEE802154_CCA_MODE_SIGNAL_OR_RSSI and RAIL_IEEE802154_CCA_MODE_SIGNAL_AND_RSSI the signal identifier is enabled for the duration of LBT. If previously enabled by RAIL_IEEE802154_ConfigSignalIdentifier(), the signal identifier will remain active until triggered.
This function is only supported by chips where RAIL_IEEE802154_SUPPORTS_SIGNAL_IDENTIFIER and RAIL_IEEE802154_SupportsSignalIdentifier() are true.
Returns
Status code indicating success of the function call. An error should be returned if ccaMode is unsuppported on a given device.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_cca_mode().
RAIL_IEEE802154_ConfigRxChannelSwitching#
RAIL_Status_t RAIL_IEEE802154_ConfigRxChannelSwitching (RAIL_Handle_t railHandle, const RAIL_IEEE802154_RxChannelSwitchingCfg_t * pConfig)
Configure RX channel switching for 802.15.4.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const RAIL_IEEE802154_RxChannelSwitchingCfg_t * | [in] | pConfig | A pointer to RAIL_IEEE802154_RxChannelSwitchingCfg_t structure. NULL will disable any switching previously set up. The feature can also be disabled by disabling RAIL_RX_OPTION_CHANNEL_SWITCHING. |
Returns
Status code indicating success of the function call. For series 3 parts: return RAIL_STATUS_INVALID_STATE if IEEE 802.15.4 is not enabled via RAIL_IEEE802154_Init(), return RAIL_STATUS_NO_ERROR otherwise.
This function configures RX channel switching, allowing reception of 2.4 GHz 802.15.4 signals on two different radio channels within the same PHY. This function should be called once before RAIL_StartRx() and/or enabling RAIL_RX_OPTION_CHANNEL_SWITCHING.
When RAIL_RX_OPTION_CHANNEL_SWITCHING is enabled, channel switching will occur during normal listening but is suspended when starting any kind of transmit, including scheduled or CSMA transmits. It remains suspended after a RAIL_TX_OPTION_WAIT_FOR_ACK transmit until the Ack is received or times out.
When RAIL_RX_OPTION_CHANNEL_SWITCHING is disabled after switching has been active, the radio could be left listening on either channel, so the application should call RAIL_StartRx() to put it on the desired non-switching channel.
Note
Switching is cancelled on any PHY change, so this function would need to be re-called to reestablish switching after such a change. When RX channel switching is active, receive sensitivity and performance are slightly impacted.
Switching is stopped on any channel change that is not from RAIL_IEEE802154_RxChannelSwitchingCfg_t but is resumed on configuring back the appropriate channel.
Note
For series 2 parts: If the two channels are same, the function behaves the same as if pConfig was NULL.
IEEE 802.15.4 must be enabled via RAIL_IEEE802154_Init(), and the radio must be in the idle state when configuring RX channel switching. A DMA channel must be allocated with RAIL_UseDma() or by incorporating the Direct Memory Access (DMA) Utility plugin; otherwise this API will return RAIL_STATUS_INVALID_CALL. This feature also requires a PRS channel, internally allocated by the RAIL library, to use and hold onto for future use. If no PRS channel is available, the function returns RAIL_STATUS_INVALID_PARAMETER.
This function internally uses RAIL_EnableCacheSynthCal() to enable/disable the sequencer cache to store the synth calibration value.
Warnings
For series 2 parts, this function relies on LDMA access and RAIL is meant to run in TrustZone non-secure world, it is not supported if LDMA is configured as secure peripheral and it will return RAIL_STATUS_INVALID_CALL.
Note
For series 3 parts:
IEEE 802.15.4 must be enabled via RAIL_IEEE802154_Init().
If the two channels are same, the function will do channel switching on a single frequency but will still duty cycle if PHY allows it.
RAIL_RX_OPTION_CHANNEL_SWITCHING is only considered when RAIL_StartRx() or RAIL_PrepareChannel() is called, not instantly.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_config_rx_channel_switching().
sl_rail_ieee802154_init#
sl_rail_status_t sl_rail_ieee802154_init (sl_rail_handle_t rail_handle, const sl_rail_ieee802154_config_t * p_config)
Initialize RAIL for IEEE802.15.4 features.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const sl_rail_ieee802154_config_t * | [in] | p_config | A non-NULL pointer to an IEEE802154 configuration structure. |
Returns
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:
It must be called before most of the sl_rail_ieee802154_* functions.
sl_rail_ieee802154_config_2p4_ghz_radio#
sl_rail_status_t sl_rail_ieee802154_config_2p4_ghz_radio (sl_rail_handle_t rail_handle)
Configure the radio for 2.4 GHz 802.15.4 operation.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
Status code indicating success of the function call.
This initializes the radio for 2.4 GHz operation. It takes the place of calling sl_rail_config_channels(). 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.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_config_2p4_ghz_radio_ant_div#
sl_rail_status_t sl_rail_ieee802154_config_2p4_ghz_radio_ant_div (sl_rail_handle_t rail_handle)
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
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 sl_rail_config_channels(). 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.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_coex#
sl_rail_status_t sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_coex (sl_rail_handle_t rail_handle)
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
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 sl_rail_config_channels(). 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.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_config_2p4_ghz_radio_coex#
sl_rail_status_t sl_rail_ieee802154_config_2p4_ghz_radio_coex (sl_rail_handle_t rail_handle)
Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
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 sl_rail_config_channels(). 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.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_config_2p4_ghz_radio_fem#
sl_rail_status_t sl_rail_ieee802154_config_2p4_ghz_radio_fem (sl_rail_handle_t rail_handle)
Configure the radio for 2.4 GHz 802.15.4 operation with a front end module.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
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 sl_rail_config_channels(). 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.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_fem#
sl_rail_status_t sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_fem (sl_rail_handle_t rail_handle)
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for a front end module.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
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 sl_rail_config_channels(). 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.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_config_2p4_ghz_radio_coex_fem#
sl_rail_status_t sl_rail_ieee802154_config_2p4_ghz_radio_coex_fem (sl_rail_handle_t rail_handle)
Configure the radio for 2.4 GHz 802.15.4 operation optimized for radio coexistence and a front end module.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
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 sl_rail_config_channels(). 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.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_coex_fem#
sl_rail_status_t sl_rail_ieee802154_config_2p4_ghz_radio_ant_div_coex_fem (sl_rail_handle_t rail_handle)
Configure the radio for 2.4 GHz 802.15.4 operation with antenna diversity optimized for radio coexistence and a front end module.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
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 sl_rail_config_channels(). 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.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_config_gb863_mhz_radio#
sl_rail_status_t sl_rail_ieee802154_config_gb863_mhz_radio (sl_rail_handle_t rail_handle)
Configure the radio for Sub-GHz GB868 863 MHz 802.15.4 operation.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
Status code indicating success of the function call.
This initializes the radio for Sub-GHz GB868 863 MHz operation. It takes the place of calling sl_rail_config_channels(). 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.
Note
This call implicitly enables SL_RAIL_IEEE802154_G_OPTION_GB868.
sl_rail_ieee802154_config_gb915_mhz_radio#
sl_rail_status_t sl_rail_ieee802154_config_gb915_mhz_radio (sl_rail_handle_t rail_handle)
Configure the radio for Sub-GHz GB868 915 MHz 802.15.4 operation.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
Status code indicating success of the function call.
This initializes the radio for Sub-GHz GB868 915 MHz operation. It takes the place of calling sl_rail_config_channels(). 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.
Note
This call implicitly enables SL_RAIL_IEEE802154_G_OPTION_GB868.
sl_rail_ieee802154_deinit#
sl_rail_status_t sl_rail_ieee802154_deinit (sl_rail_handle_t rail_handle)
De-initialize IEEE802.15.4 hardware acceleration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
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:
sl_rail_set_state_timing(), to reset all timings to 100 us
sl_rail_enable_address_filter() passing false for its enable parameter
sl_rail_ieee802154_is_enabled#
bool sl_rail_ieee802154_is_enabled (sl_rail_handle_t rail_handle)
Return whether IEEE802.15.4 hardware acceleration is currently enabled.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
true if IEEE802.15.4 hardware acceleration was enabled to start with and false otherwise.
sl_rail_ieee802154_config_channels#
sl_rail_status_t sl_rail_ieee802154_config_channels (sl_rail_handle_t rail_handle, const sl_rail_channel_config_t * p_channel_config, sl_rail_ieee802154_phy_t phy_id)
Load an 802.15.4 channel config.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const sl_rail_channel_config_t * | N/A | p_channel_config | A pointer to a channel configuration. |
| sl_rail_ieee802154_phy_t | N/A | phy_id | PTI config ID. |
Returns
Status code indicating success of the function call.
This initializes the radio for 802.15.4 operation. It takes the place of calling sl_rail_config_channels(). 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. The channelConfig can potentially define additional channels outside of the range 11-26.
Note
This call implicitly disables all sl_rail_ieee802154_g_options_t.
sl_rail_ieee802154_get_phy_id#
sl_rail_ieee802154_phy_t sl_rail_ieee802154_get_phy_id (sl_rail_handle_t rail_handle)
Return IEEE802.15.4 PHY identifier.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
PHY identifier (aka PTI radio config id).
sl_rail_ieee802154_set_addresses#
sl_rail_status_t sl_rail_ieee802154_set_addresses (sl_rail_handle_t rail_handle, const sl_rail_ieee802154_addr_config_t * p_addresses)
Configure the RAIL Address Filter for 802.15.4 filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const sl_rail_ieee802154_addr_config_t * | [in] | p_addresses | A pointer to the address information that should be used. |
Returns
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 p_addresses, all addresses will be set to their reset value.
sl_rail_ieee802154_set_pan_id#
sl_rail_status_t sl_rail_ieee802154_set_pan_id (sl_rail_handle_t rail_handle, uint16_t pan_id, uint8_t index)
Set a PAN Id for 802.15.4 address filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| uint16_t | [in] | pan_id | 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 pan_id<7:0> is first in the payload followed by pan_id<15:8>. Set to 0xFFFF to disable for this index. |
| uint8_t | [in] | index | Indicates which PAN Id to set. Must be below SL_RAIL_IEEE802154_MAX_ADDRESSES. |
Returns
Status code indicating success of the function call.
Set up the 802.15.4 address filter to accept messages to the given PAN Id.
sl_rail_ieee802154_set_short_address#
sl_rail_status_t sl_rail_ieee802154_set_short_address (sl_rail_handle_t rail_handle, uint16_t short_addr, uint8_t index)
Set a short address for 802.15.4 address filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| uint16_t | [in] | short_addr | A 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 short_addr<7:0> is first in the payload followed by short_addr<15:8>. Set to 0xFFFF to disable for this index. |
| uint8_t | [in] | index | Which short address to set. Must be below SL_RAIL_IEEE802154_MAX_ADDRESSES. |
Returns
Status code indicating success of the function call.
Set up the 802.15.4 address filter to accept messages to the given short address.
sl_rail_ieee802154_set_long_address#
sl_rail_status_t sl_rail_ieee802154_set_long_address (sl_rail_handle_t rail_handle, const uint8_t * p_long_addr, uint8_t index)
Set a long address for 802.15.4 address filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const uint8_t * | [in] | p_long_addr | 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. |
| uint8_t | [in] | index | Indicates which long address to set. Must be below SL_RAIL_IEEE802154_MAX_ADDRESSES. |
Returns
Status code indicating success of the function call.
Set up the 802.15.4 address filter to accept messages to the given long address.
sl_rail_ieee802154_set_pan_coordinator#
sl_rail_status_t sl_rail_ieee802154_set_pan_coordinator (sl_rail_handle_t rail_handle, bool is_pan_coordinator)
Set whether the current node is a PAN coordinator.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| bool | [in] | is_pan_coordinator | true if this device is a PAN coordinator. |
Returns
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 by calling sl_rail_ieee802154_init(). This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.
sl_rail_ieee802154_set_promiscuous_mode#
sl_rail_status_t sl_rail_ieee802154_set_promiscuous_mode (sl_rail_handle_t rail_handle, bool enable)
Set whether to enable 802.15.4 promiscuous mode.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| bool | [in] | enable | true if all frames and addresses should be accepted. |
Returns
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 by calling sl_rail_ieee802154_init(). This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.
sl_rail_ieee802154_config_e_options#
sl_rail_status_t sl_rail_ieee802154_config_e_options (sl_rail_handle_t rail_handle, sl_rail_ieee802154_e_options_t mask, sl_rail_ieee802154_e_options_t options)
Configure certain 802.15.4E-2012 / 802.15.4-2015 Frame Version 2 features.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_ieee802154_e_options_t | [in] | mask | A bitmask containing which options should be modified. |
| sl_rail_ieee802154_e_options_t | [in] | options | A bitmask containing desired options settings. Bit positions for each option are found in the sl_rail_ieee802154_e_options_t. |
Returns
Status code indicating success of the function call.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling sl_rail_ieee802154_init() 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.
sl_rail_ieee802154_config_g_options#
sl_rail_status_t sl_rail_ieee802154_config_g_options (sl_rail_handle_t rail_handle, sl_rail_ieee802154_g_options_t mask, sl_rail_ieee802154_g_options_t options)
Configure certain 802.15.4G-2012 / 802.15.4-2015 SUN PHY features (only for radio configurations designed accordingly).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_ieee802154_g_options_t | [in] | mask | A bitmask containing which options should be modified. |
| sl_rail_ieee802154_g_options_t | [in] | options | A bitmask containing desired options settings. Bit positions for each option are found in the sl_rail_ieee802154_g_options_t. |
Returns
Status code indicating success of the function call.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling sl_rail_ieee802154_init(), the platform does not support the feature(s), the radio configuration is not appropriate, or the radio is not idle.
sl_rail_ieee802154_compute_channel_from_phy_mode_id#
sl_rail_status_t sl_rail_ieee802154_compute_channel_from_phy_mode_id (sl_rail_handle_t rail_handle, uint8_t new_phy_mode_id, uint16_t * p_channel)
Compute channel to switch to given a targeted PHY Mode Id in the context of Wi-SUN mode switching.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| uint8_t | [in] | new_phy_mode_id | A targeted PHY Mode Id. |
| uint16_t * | [out] | p_channel | A pointer to the channel to switch to. |
Returns
Status code indicating success of the function call.
This function will fail if:
the targeted phy_mode_id is the same as the current PHY Mode Id
called on a platform that lacks SL_RAIL_IEEE802154_SUPPORTS_G_MODE_SWITCH
called on a platform that doesn't have 802154G options enabled by sl_rail_ieee802154_config_g_options(). For new_phy_mode_id associated with a FSK FEC_off PHY, if dynamic FEC is activated (see SL_RAIL_IEEE802154_G_OPTION_DYN_FEC), the returned channel can correspond to the associated FSK FEC_on PHY corresponding then to PHY Mode Id = new_phy_mode_id + 16
sl_railcb_ieee802154_is_mode_switch_new_channel_valid#
sl_rail_status_t sl_railcb_ieee802154_is_mode_switch_new_channel_valid (sl_rail_handle_t rail_handle, uint32_t current_base_freq_hz, uint8_t new_phy_mode_id, const sl_rail_channel_config_entry_t * p_config_entry_new_phy_mode_id, uint16_t * p_channel)
Manage forbidden channels during mode switch.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | The real RAIL instance handle issuing the callback. |
| uint32_t | [in] | current_base_freq_hz | The current frequency of the base channel. |
| uint8_t | [in] | new_phy_mode_id | A targeted PHY Mode Id. |
| const sl_rail_channel_config_entry_t * | [in] | p_config_entry_new_phy_mode_id | A pointer to sl_rail_channel_config_entry_t structure corresponding to the new PHY config_entry. |
| uint16_t * | [inout] | p_channel | A pointer to the channel to switch to. If channel is valid, the function must just return. If channel is forbidden, the function must update it with the closest valid channel. The highest channel must be selected in case of two valid channels being equidistant to a forbidden channel. |
Returns
Status code indicating success of the function call. It must return SL_RAIL_STATUS_INVALID_PARAMETER for failure or SL_RAIL_STATUS_NO_ERROR for success.
This function must fail if no valid channel has been found. If so, RAIL will abort the mode switch.
Note
This callback will only be called on platforms where SL_RAIL_IEEE802154_SUPPORTS_G_MODE_SWITCH is true, SL_RAIL_IEEE802154_G_OPTION_WI_SUN_MODE_SWITCH was successfully enabled, and a valid mode switch PHY header is received.
sl_rail_ieee802154_accept_frames#
sl_rail_status_t sl_rail_ieee802154_accept_frames (sl_rail_handle_t rail_handle, uint8_t frames_mask)
Set which 802.15.4 frame types to accept.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| uint8_t | [in] | frames_mask | A mask containing which 802.15.4 frame types to receive. |
Returns
Status code indicating success of the function call.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling sl_rail_ieee802154_init() or frames_mask 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 frames may be received. The SL_RAIL_IEEE802154_ACCEPT_*_FRAMES defines may be combined to create a bitmask to pass into this function.
SL_RAIL_IEEE802154_ACCEPT_ACK_FRAMES behaves slightly different than the other defines. If SL_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 sl_rail_rx_packet_details_t::is_ack true. If SL_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.
sl_rail_ieee802154_enable_early_frame_pending#
sl_rail_status_t sl_rail_ieee802154_enable_early_frame_pending (sl_rail_handle_t rail_handle, bool enable)
Enable early Frame Pending lookup event notification (SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| bool | [in] | enable | true to enable, false to disable. |
Returns
Status code indicating success of the function call.
Normally, SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered after receiving the entire MAC header and MAC command byte for an Ack-requesting MAC command frame. Version 0/1 frames also require that command to be a Data Request for this event to occur. Enabling this feature causes this event to be triggered earlier to allow for more time to determine the type of Ack needed (Immediate or Enhanced) and/or perform frame pending lookup to influence the outgoing Ack by using sl_rail_ieee802154_write_enh_ack() or sl_rail_ieee802154_toggle_frame_pending().
For Frame Version 0/1 packets and for Frame Version 2 packets when SL_RAIL_IEEE802154_E_OPTION_ENH_ACK is not in use, "early" means right after receiving the source address information in the MAC header.
For Frame Version 2 packets when SL_RAIL_IEEE802154_E_OPTION_ENH_ACK is in use, "early" means right after receiving any Auxiliary Security header which follows the source address information in the MAC header.
This feature is useful when the protocol knows an Ack-requesting MAC Command must be a data poll without needing to receive the MAC Command byte, giving it a bit more time to adjust Frame Pending or generate an Enhanced Ack.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling sl_rail_ieee802154_init(), 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.
sl_rail_ieee802154_enable_data_frame_pending#
sl_rail_status_t sl_rail_ieee802154_enable_data_frame_pending (sl_rail_handle_t rail_handle, bool enable)
Enable Frame Pending lookup event notification (SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND) for MAC Data frames.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| bool | [in] | enable | true to enable, false to disable. |
Returns
Status code indicating success of the function call.
Normally SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND is triggered only for Ack-requesting MAC command frames. Enabling this feature causes this event to also be triggered for MAC data frames, at the same point in the packet as sl_rail_ieee802154_enable_early_frame_pending() would trigger. This feature is necessary to support the Thread Basil-Hayden Enhanced Frame Pending feature in Version 0/1 frames, and to support Version 2 Data frames which require an Enhanced Ack.
This function will fail if 802.15.4 hardware acceleration is not currently enabled by calling sl_rail_ieee802154_init(). This setting may be changed at any time when 802.15.4 hardware acceleration is enabled.
sl_rail_ieee802154_toggle_frame_pending#
sl_rail_status_t sl_rail_ieee802154_toggle_frame_pending (sl_rail_handle_t rail_handle)
Change the Frame Pending bit on the outgoing legacy Immediate Ack from the default specified by sl_rail_ieee802154_config_t::default_frame_pending_in_outgoing_acks.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
Status code indicating success of the function call.
This function must only be called while processing the SL_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 sl_rail_ieee802154_config_t::default_frame_pending_in_outgoing_acks.
It's intended only for use with 802.15.4 legacy immediate Acks and not 802.15.4E enhanced Acks. This will return SL_RAIL_STATUS_INVALID_STATE if it is too late to modify the outgoing Immediate Ack.
sl_rail_ieee802154_get_address#
sl_rail_status_t sl_rail_ieee802154_get_address (sl_rail_handle_t rail_handle, sl_rail_ieee802154_address_t * p_address)
Get the source address of the incoming data request.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_ieee802154_address_t * | [out] | p_address | A pointer to sl_rail_ieee802154_address_t structure to populate with source address information. |
Returns
Status code indicating success of the function call.
This function must only be called when handling the SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND event. This will return SL_RAIL_STATUS_INVALID_STATE if the address information is stale (i.e., it is too late to affect the outgoing Ack).
sl_rail_ieee802154_write_enh_ack#
sl_rail_status_t sl_rail_ieee802154_write_enh_ack (sl_rail_handle_t rail_handle, const uint8_t * p_ack_data, uint16_t ack_data_bytes)
Write the Auto-Ack FIFO for the next outgoing 802.15.4E Enhanced Ack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const uint8_t * | [in] | p_ack_data | A pointer to Ack data to transmit This may be NULL, in which case it's assumed the data has already been emplaced into the Ack buffer and RAIL just needs to be told how many bytes are there. Use sl_rail_get_auto_ack_fifo() to get the address of RAIL's Auto-Ack buffer in RAM and its size. |
| uint16_t | [in] | ack_data_bytes | Length of Ack data, in bytes. If this exceeds the size of the Auto-Ack FIFO buffer the function will return SL_RAIL_STATUS_INVALID_PARAMETER. |
Returns
Status code indicating success of the function call.
This function sets the Auto-Ack data to use in acknowledging the frame being received. It must only be called while processing the SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND, and is intended for use when packet information from sl_rail_get_rx_incoming_packet_info() indicates an 802.15.4E Enhanced Ack must be sent instead of a legacy Immediate Ack. sl_rail_ieee802154_toggle_frame_pending() 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 p_ack_data. This will return SL_RAIL_STATUS_INVALID_STATE if it is too late to write the outgoing Ack – a situation that will likely trigger a SL_RAIL_EVENT_TXACK_UNDERFLOW event. When successful, the Enhanced p_ack_data will only be sent once. Subsequent packets needing an Enhanced Ack will each need to call this function to write their Ack information.
sl_rail_ieee802154_set_rx_to_enh_ack_tx#
sl_rail_status_t sl_rail_ieee802154_set_rx_to_enh_ack_tx (sl_rail_handle_t rail_handle, sl_rail_transition_time_t * p_rx_to_enh_ack_tx)
Set a separate RX packet to TX state transition turnaround time for sending an Enhanced Ack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_transition_time_t * | [inout] | p_rx_to_enh_ack_tx | A pointer to the turnaround transition requested for Enhanced Acks. It will be updated with the actual time set. Requesting a time of 0 will sync the Enhanced Ack turnaround time with that used for immediate Acks (and output 0). Requesting a time of SL_RAIL_TRANSITION_TIME_KEEP will output the current Enhanced Ack timing parameter (0 if it is the same as that used for Immediate Acks). |
Returns
Status code indicating a success of the function call. An error will not update the p_rx_to_enh_ack_tx output parameter.
Normally Immediate and Enhanced Acks are both sent using the sl_rail_ieee802154_config_t::timings rx_to_tx turnaround time. If the stack needs more time to prepare an Enhanced Ack, it can call this function after sl_rail_ieee802154_init() to set a longer turnaround time used just for Enhanced Ack transmits.
This function will fail on platforms that lack SL_RAIL_IEEE802154_SUPPORTS_E_ENHANCED_ACK.
sl_rail_ieee802154_convert_rssi_to_lqi#
uint8_t sl_rail_ieee802154_convert_rssi_to_lqi (uint8_t orig_lqi, int8_t rssi_dbm)
Convert RSSI into 802.15.4 Link Quality Indication (LQI) metric compatible with the Silicon Labs Zigbee stack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t | [in] | orig_lqi | The original LQI, for example from sl_rail_rx_packet_details_t::lqi. This parameter is not currently used but may be used in the future. |
| int8_t | [in] | rssi_dbm | The RSSI in dBm, for example from sl_rail_rx_packet_details_t::rssi_dbm. |
Returns
An LQI value (range 0..255 but not all intermediate values are possible) based on the rssi_dbm and the chip's RSSI sensitivity range.
This function is compatible with sl_rail_convert_lqi_callback_t() and is suitable to pass to sl_rail_convert_lqi().
sl_rail_ieee802154_convert_rssi_to_ed#
uint8_t sl_rail_ieee802154_convert_rssi_to_ed (int8_t rssi_dbm)
Convert RSSI into 802.15.4 Energy Detection (ED) metric compatible with the Silicon Labs Zigbee stack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| int8_t | [in] | rssi_dbm | The RSSI in dBm, for example from sl_rail_rx_packet_details_t::rssi_dbm. |
Returns
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.
sl_rail_ieee802154_config_signal_identifier#
sl_rail_status_t sl_rail_ieee802154_config_signal_identifier (sl_rail_handle_t rail_handle, sl_rail_ieee802154_signal_identifier_mode_t signal_identifier_mode)
Configure signal identifier for 802.15.4 signal detection.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_ieee802154_signal_identifier_mode_t | [in] | signal_identifier_mode | Mode of signal identifier operation. |
This features allows detection of 2.4 GHz 802.15.4 signal on air. This function must be called once before sl_rail_ieee802154_enable_signal_detection() to configure and enable signal identifier.
To enable event for signal detection sl_rail_config_events() must be called for enabling SL_RAIL_EVENT_SIGNAL_DETECTED.
This function is only supported by chips where SL_RAIL_IEEE802154_SUPPORTS_SIGNAL_IDENTIFIER and sl_rail_ieee802154_supports_signal_identifier() are true.
Returns
Status code indicating success of the function call.
sl_rail_ieee802154_enable_signal_detection#
sl_rail_status_t sl_rail_ieee802154_enable_signal_detection (sl_rail_handle_t rail_handle, bool enable)
Enable or disable signal identifier for 802.15.4 signal detection.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| bool | [in] | enable | Signal detection is enabled if true, disabled if false. |
sl_rail_ieee802154_config_signal_identifier() must be called once before calling this function to configure and enable signal identifier. Once a signal is detected signal detection will be turned off and this function should be called to re-enable the signal detection without needing to call sl_rail_ieee802154_config_signal_identifier() if the signal identifier is already configured and enabled.
This function is only supported by chips where SL_RAIL_IEEE802154_SUPPORTS_SIGNAL_IDENTIFIER and sl_rail_ieee802154_supports_signal_identifier() are true.
Returns
Status code indicating success of the function call.
sl_rail_ieee802154_config_cca_mode#
sl_rail_status_t sl_rail_ieee802154_config_cca_mode (sl_rail_handle_t rail_handle, sl_rail_ieee802154_cca_mode_t cca_mode)
Set 802.15.4 CCA mode.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_ieee802154_cca_mode_t | [in] | cca_mode | Mode of CCA operation. |
This function sets the CCA mode sl_rail_ieee802154_cca_mode_t. If not called, SL_RAIL_IEEE802154_CCA_MODE_RSSI (RSSI-based CCA) is used for CCA.
In SL_RAIL_IEEE802154_CCA_MODE_SIGNAL, SL_RAIL_IEEE802154_CCA_MODE_SIGNAL_OR_RSSI and SL_RAIL_IEEE802154_CCA_MODE_SIGNAL_AND_RSSI the signal identifier is enabled for the duration of LBT. If previously enabled by sl_rail_ieee802154_config_signal_identifier(), the signal identifier will remain active until triggered.
This function is only supported by chips where SL_RAIL_IEEE802154_SUPPORTS_SIGNAL_IDENTIFIER and sl_rail_ieee802154_supports_signal_identifier() are true.
Returns
Status code indicating success of the function call. An error should be returned if cca_mode is unsuppported on a given device.
sl_rail_ieee802154_config_rx_channel_switching#
sl_rail_status_t sl_rail_ieee802154_config_rx_channel_switching (sl_rail_handle_t rail_handle, const sl_rail_ieee802154_rx_channel_switching_cfg_t * p_config)
Configure RX channel switching for 802.15.4.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const sl_rail_ieee802154_rx_channel_switching_cfg_t * | [in] | p_config | A pointer to sl_rail_ieee802154_rx_channel_switching_cfg_t structure. NULL will disable any switching previously set up. The feature can also be disabled by disabling SL_RAIL_RX_OPTION_CHANNEL_SWITCHING. |
Returns
Status code indicating success of the function call. For series 3 parts: return SL_RAIL_STATUS_INVALID_STATE if IEEE 802.15.4 is not enabled via sl_rail_ieee802154_init(), return SL_RAIL_STATUS_NO_ERROR otherwise.
This function configures RX channel switching, allowing reception of 2.4 GHz 802.15.4 signals on two different radio channels within the same PHY. This function should be called once before sl_rail_start_rx() and/or enabling SL_RAIL_RX_OPTION_CHANNEL_SWITCHING.
When SL_RAIL_RX_OPTION_CHANNEL_SWITCHING is enabled, channel switching will occur during normal listening but is suspended (and the radio is idled) when starting any kind of transmit, including scheduled or CSMA transmits. It remains suspended after a SL_RAIL_TX_OPTION_WAIT_FOR_ACK transmit until the Ack is received or times out.
When SL_RAIL_RX_OPTION_CHANNEL_SWITCHING is disabled after switching has been active, the radio could be left listening on either channel, so the application should call sl_rail_start_rx() to put it on the desired non-switching channel.
Note
Switching is cancelled on any PHY change and this function would need to be re-called to reestablish switching after such a change. When RX channel switching is active, receive sensitivity and performance are slightly impacted.
Switching is stopped on any channel change that is not from sl_rail_ieee802154_rx_channel_switching_cfg_t but is resumed on configuring back the appropriate channel.
Note
For series 2 parts: If the two channels are same, the function behaves the same as if p_config was NULL.
IEEE 802.15.4 must be enabled via sl_rail_ieee802154_init(), and the radio must be in the idle state when configuring RX channel switching. A DMA channel must be allocated with sl_rail_use_dma() or by incorporating the Direct Memory Access (DMA) Utility plugin; otherwise this API will return SL_RAIL_STATUS_INVALID_CALL. This feature also requires a PRS channel, internally allocated by the RAIL library, to use and hold onto for future use. If no PRS channel is available, the function returns SL_RAIL_STATUS_INVALID_PARAMETER.
This function internally uses sl_rail_enable_cache_synth_cal() to enable/disable the sequencer cache to store the synth calibration value.
Warnings
For series 2 parts, this function relies on LDMA access and RAIL is meant to run in TrustZone non-secure world, it is not supported if LDMA is configured as secure peripheral and it will return SL_RAIL_STATUS_INVALID_CALL.
Note
For series 3 parts:
IEEE 802.15.4 must be enabled via sl_rail_ieee802154_init().
If the two channels are same, the function will do channel switching on a single frequency but will still duty cycle if PHY allows it.
SL_RAIL_RX_OPTION_CHANNEL_SWITCHING is only considered when sl_rail_start_rx() or sl_rail_prepare_channel() is called, not instantly.