Z-Wave#
Z-Wave configuration routines.
The functions in this group configure RAIL Z-Wave hardware acceleration features.
To configure Z-Wave functionality, the application must first set up a RAIL instance with RAIL_Init() and other setup functions.
RAIL_ZWAVE_NodeId_t gRecentBeamNodeId;
uint8_t gRecentBeamChannelIndex;
// Main RAIL_EVENT callback
static void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
// Get beam Node Id and channel index from beam packet
if (events & RAIL_EVENT_ZWAVE_BEAM) {
if (RAIL_ZWAVE_IsEnabled(railHandle)) {
if ((RAIL_ZWAVE_GetBeamNodeId(railHandle, &gRecentBeamNodeId)
!= RAIL_STATUS_NO_ERROR)
|| (RAIL_ZWAVE_GetBeamChannelIndex(railHandle, &gRecentBeamChannelIndex)
!= RAIL_STATUS_NO_ERROR)) {
return;
}
}
}
}
static const RAIL_ZWAVE_Config_t zwaveConfig = {
.options = RAIL_ZWAVE_OPTIONS_DEFAULT
};
RAIL_Status_t zwaveInit(void)
{
// initialize Z-Wave
RAIL_Status_t status = RAIL_ZWAVE_Init(railHandle, &zwaveConfig);
if (status != RAIL_STATUS_NO_ERROR) {
return status;
}
uint8_t myHomeId[4] = { 0xDE, 0xAD, 0xBE, 0xEF };
RAIL_ZWAVE_SetNodeId(railHandle, RAIL_ZWAVE_NODE_ID_DEFAULT);
RAIL_ZWAVE_SetHomeId(railHandle, myHomeId, RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE);
// configure region to EU(European Union)
return RAIL_ZWAVE_ConfigRegion(railHandle, RAIL_ZWAVE_REGION_EU);
}
The functions in this group configure RAIL Z-Wave hardware acceleration features.
To configure Z-Wave functionality, the application must first set up a RAIL instance with sl_rail_init() and other setup functions.
sl_rail_zwave_beam_details_t g_recent_beam_details;
// Main SL_RAIL_EVENT callback
static void rail_events_callback(sl_rail_handle_t rail_handle,
sl_rail_events_t events)
{
// Get beam details from the beam packet
if (events & SL_RAIL_EVENT_ZWAVE_BEAM) {
if (sl_rail_zwave_is_enabled(rail_handle)) {
if (sl_rail_zwave_get_rx_beam_details(rail_handle, &g_recent_beam_details)
!= SL_RAIL_STATUS_NO_ERROR)
return;
}
}
}
}
static const sl_rail_zwave_config_t zwave_config = {
.options = SL_RAIL_ZWAVE_OPTIONS_DEFAULT
};
void zwave_init(void)
{
// initialize Z-Wave
sl_rail_status_t status = sl_rail_zwave_init(rail_handle, &zwave_config);
assert(status == SL_RAIL_STATUS_NO_ERROR);
uint8_t my_home_id[4] = { 0xDE, 0xAD, 0xBE, 0xEF };
sl_rail_zwave_set_node_id(rail_handle, SL_RAIL_ZWAVE_NODE_ID_DEFAULT);
sl_rail_zwave_set_home_id(rail_handle, my_home_id, SL_RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE);
// configure region to EU(European Union)
status = sl_rail_zwave_config_region(rail_handle, SL_RAIL_ZWAVE_REGION_EU);
assert(status == SL_RAIL_STATUS_NO_ERROR);
}
Modules#
sl_rail_zwave_beam_rx_config_t
Enumerations#
Z-Wave options.
A Z-Wave Node Id.
A Z-Wave Home Id.
A Z-Wave Home Id hash.
Z-Wave supported baud rates or PHYs.
Z-Wave region identifications.
Z-Wave options.
A Z-Wave Node Id.
A Z-Wave Home Id.
A Z-Wave Home Id hash.
Z-Wave supported baud rates or PHYs.
The Z-Wave PHY identifier (aka PTI radio configuration id).
Z-Wave region identifications.
Typedefs#
Rx channel hopping on-channel time for all Z-Wave channels in a region.
Rx channel hopping on-channel time for all Z-Wave channels in a region.
Variables#
EU-European Union.
US-United States.
ANZ-Australia/New Zealand.
HK-Hong Kong.
MY-Malaysia.
IN-India.
JP-Japan.
JP-Japan Energy-Detect.
RU-Russia.
IL-Israel.
KR-Korea.
KR-Korea Energy-Detect.
CN-China.
US-Long Range 1.
US-Long Range 2.
US-Long Range 3.
EU-Long Range 1.
EU-Long Range 2.
EU-Long Range 3.
Invalid Region.
EU-European Union.
US-United States.
ANZ-Australia/New Zealand.
HK-Hong Kong.
MY-Malaysia.
IN-India.
JP-Japan.
RU-Russia.
IL-Israel.
KR-Korea.
CN-China.
US-Long Range 1.
US-Long Range 2.
US-Long Range 3.
EU-Long Range 1.
EU-Long Range 2.
EU-Long Range 3.
Invalid Region.
An array of region configurations indexed by sl_rail_zwave_region_id_t.
Functions#
Switch the Z-Wave region.
Perform image rejection calibration on all valid channels of a Z-Wave region.
Initialize RAIL for Z-Wave features.
De-initialize Z-Wave hardware acceleration.
Return whether Z-Wave hardware acceleration is currently enabled.
Configure Z-Wave options.
Inform RAIL of the Z-Wave node's Node Id for receive filtering.
Inform RAIL of the Z-Wave node's Home Id and its hash for receive filtering.
Get the Node Id of the most recently seen beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.
Get the Home Id hash of the most recently seen beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.
Get the channel hopping index of the most recently seen beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.
Get the TX power used by the transmitter of the most recently seen long range beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.
Get the RSSI of the received beam frame.
Set the Raw Low Power settings.
Get the TX low power in raw units (see rail_chip_specific.h for value ranges).
Set the Low Power settings in deci-dBm.
Get the TX low power in terms of deci-dBm.
Implement beam detection and reception algorithms.
Configure the receive algorithm used in RAIL_ZWAVE_ReceiveBeam().
Set the default RX beam configuration.
Get the current RX beam configuration.
Configure the channel hop timings for use in Z-Wave RX channel hop configuration.
Get the Z-Wave region.
Write the Auto-Ack FIFO for the next outgoing Z-Wave Long Range Ack.
Switch the Z-Wave region.
Perform image rejection calibration on all valid channels of a Z-Wave region.
Initialize RAIL for Z-Wave features.
De-initialize Z-Wave hardware acceleration.
Return whether Z-Wave hardware acceleration is currently enabled.
Configure Z-Wave options.
Inform RAIL of the Z-Wave node's Node Id for receive filtering.
Inform RAIL of the Z-Wave node's Home Id and its hash for receive filtering.
Get detailed information about a Z-Wave beam frame that triggered SL_RAIL_EVENT_ZWAVE_BEAM.
Set the Low Power settings in deci-dBm.
Get the TX low power in terms of deci-dBm.
Implement beam detection and reception algorithms.
Configure the receive algorithm used in sl_rail_zwave_receive_beam().
Set the default RX beam configuration.
Get the current RX beam configuration.
Configure the channel hop timings for use in Z-Wave RX channel hop configuration.
Get the Z-Wave region.
Write the Auto-Ack FIFO for the next outgoing Z-Wave Long Range Ack.
Macros#
A value representing no options.
All options are disabled by default.
An option to configure promiscuous mode, accepting non-beam packets regardless of their Home Id.
An option to filter non-beam packets based on their Node Id when RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE is disabled.
An option to configure beam frame recognition.
An option to receive all beams promiscuously when RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES is enabled.
A value representing all options.
Sentinel value to indicate that a channel (and thus its frequency) are invalid.
Invalid beam TX power value returned when RAIL_ZWAVE_GetLrBeamTxPower() is called after receiving a regular non-long-range beam.
Number of channels in each of Z-Wave's region-based PHYs.
DeprecatedBackwards-compatible define.
DeprecatedBackwards-compatible define.
A value representing no options.
All options are disabled by default.
An option to configure promiscuous mode, accepting non-beam packets regardless of their Home Id.
An option to filter non-beam packets based on their Node Id when SL_RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE is disabled.
An option to configure beam frame recognition.
An option to receive all beams promiscuously when SL_RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES is enabled.
A value representing all options.
Sentinel value to indicate that a channel (and thus its frequency) are invalid.
Invalid beam TX power value returned when sl_rail_zwave_get_rx_beam_details() is called after receiving a regular non-long-range beam.
Number of channels in each of Z-Wave's region-based PHYs.
Enumeration Documentation#
RAIL_ZWAVE_Options_t#
RAIL_ZWAVE_Options_t
Z-Wave options.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_options_t.
| Enumerator | |
|---|---|
| RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE_SHIFT | Shift position of RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE bit. |
| RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES_SHIFT | Shift position of RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES bit. |
| RAIL_ZWAVE_OPTION_NODE_ID_FILTERING_SHIFT | Shift position of RAIL_ZWAVE_OPTION_NODE_ID_FILTERING bit. |
| RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE_SHIFT | Shift position of RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE bit. |
RAIL_ZWAVE_NodeId_t#
RAIL_ZWAVE_NodeId_t
A Z-Wave Node Id.
This data type is 12 bits wide when using the ZWave Long Range PHY, and 8 bits wide otherwise.
Note
When using the Long Range PHY, values 0xFA1..0xFFE are reserved. Otherwise, values 0xE9..0xFE are reserved.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_node_id_t.
| Enumerator | |
|---|---|
| RAIL_ZWAVE_NODE_ID_NONE | The unknown Node Id for uninitialized nodes. |
| RAIL_ZWAVE_NODE_ID_BROADCAST | The broadcast Node Id. |
| RAIL_ZWAVE_NODE_ID_DEFAULT | Default to the broadcast Node Id. |
| RAIL_ZWAVE_NODE_ID_BROADCAST_LONGRANGE | The Long Range broadcast Node Id. |
| RAIL_ZWAVE_NODE_ID_DEFAULT_LONGRANGE | Default to the Long Range broadcast Node Id. |
RAIL_ZWAVE_HomeId_t#
RAIL_ZWAVE_HomeId_t
A Z-Wave Home Id.
Note
Home Ids in the range 0x54000000..0x55FFFFFF are illegal.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_home_id_t.
| Enumerator | |
|---|---|
| RAIL_ZWAVE_HOME_ID_UNKNOWN | The unknown Home Id. |
| RAIL_ZWAVE_HOME_ID_DEFAULT | An impossible and unlikely Home Id. |
RAIL_ZWAVE_HomeIdHash_t#
RAIL_ZWAVE_HomeIdHash_t
A Z-Wave Home Id hash.
Note
Certain values (as shown) are illegal.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_home_id_hash_t.
| Enumerator | |
|---|---|
| RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_1 | An illegal Home Id hash value. |
| RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_2 | An illegal Home Id hash value. |
| RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_3 | An illegal Home Id hash value. |
| RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE | Illegal Home Id hash value that suppresses checking the Home Id hash field of beam packets. |
| RAIL_ZWAVE_HOME_ID_HASH_DEFAULT | Default to don't care. |
RAIL_ZWAVE_Baud_t#
RAIL_ZWAVE_Baud_t
Z-Wave supported baud rates or PHYs.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_baud_t.
| Enumerator | |
|---|---|
| RAIL_ZWAVE_BAUD_9600 | 9.6 kbps baud rate. |
| RAIL_ZWAVE_BAUD_40K | 40 kbps baud rate. |
| RAIL_ZWAVE_BAUD_100K | 100 kbps baud rate. |
| RAIL_ZWAVE_LR | Long Range PHY. |
| RAIL_ZWAVE_ENERGY_DETECT | Energy detection PHY. |
| RAIL_ZWAVE_BAUD_INVALID | Sentinel value for invalid baud rate. |
RAIL_ZWAVE_RegionId_t#
RAIL_ZWAVE_RegionId_t
Z-Wave region identifications.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_id_t.
| Enumerator | |
|---|---|
| RAIL_ZWAVE_REGIONID_UNKNOWN | Unknown/Invalid. |
| RAIL_ZWAVE_REGIONID_EU | European Union. |
| RAIL_ZWAVE_REGIONID_US | United States. |
| RAIL_ZWAVE_REGIONID_ANZ | Australia/New Zealand. |
| RAIL_ZWAVE_REGIONID_HK | Hong Kong. |
| RAIL_ZWAVE_REGIONID_MY | Malaysia. |
| RAIL_ZWAVE_REGIONID_IN | India. |
| RAIL_ZWAVE_REGIONID_JP | Japan. |
| RAIL_ZWAVE_REGIONID_RU | Russian Federation. |
| RAIL_ZWAVE_REGIONID_IL | Israel. |
| RAIL_ZWAVE_REGIONID_KR | Korea. |
| RAIL_ZWAVE_REGIONID_CN | China. |
| RAIL_ZWAVE_REGIONID_US_LR1 | United States, with first long range PHY. |
| RAIL_ZWAVE_REGIONID_US_LR2 | United States, with second long range PHY. |
| RAIL_ZWAVE_REGIONID_US_LR3 | United States, with third long range PHY. |
| RAIL_ZWAVE_REGIONID_US_LR_END_DEVICE | DeprecatedThis RAIL 2.x backwards compatible enum value has been eliminated in RAIL 3; use SL_RAIL_ZWAVE_REGION_ID_US_LR_3. |
| RAIL_ZWAVE_REGIONID_EU_LR1 | European Union, with first long range PHY. |
| RAIL_ZWAVE_REGIONID_EU_LR2 | European Union, with second long range PHY. |
| RAIL_ZWAVE_REGIONID_EU_LR3 | European Union, with third long range PHY. |
| RAIL_ZWAVE_REGIONID_EU_LR_END_DEVICE | DeprecatedThis RAIL 2.x backwards compatible enum value has been eliminated in RAIL 3, use SL_RAIL_ZWAVE_REGION_ID_EU_LR_3. |
| RAIL_ZWAVE_REGIONID_COUNT | Count of known regions. |
sl_rail_zwave_options_t#
sl_rail_zwave_options_t
Z-Wave options.
| Enumerator | |
|---|---|
| SL_RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE_SHIFT | Shift position of SL_RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE bit. |
| SL_RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES_SHIFT | Shift position of SL_RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES bit. |
| SL_RAIL_ZWAVE_OPTION_NODE_ID_FILTERING_SHIFT | Shift position of SL_RAIL_ZWAVE_OPTION_NODE_ID_FILTERING bit. |
| SL_RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE_SHIFT | Shift position of SL_RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE bit. |
sl_rail_zwave_node_id_t#
sl_rail_zwave_node_id_t
A Z-Wave Node Id.
This data type is 12 bits wide when using the ZWave Long Range PHY, and 8 bits wide otherwise.
Note
When using the Long Range PHY, values 0xFA1..0xFFE are reserved. Otherwise, values 0xE9..0xFE are reserved.
| Enumerator | |
|---|---|
| SL_RAIL_ZWAVE_NODE_ID_NONE | The unknown Node Id for uninitialized nodes. |
| SL_RAIL_ZWAVE_NODE_ID_BROADCAST | The broadcast Node Id. |
| SL_RAIL_ZWAVE_NODE_ID_DEFAULT | Default to the broadcast Node Id. |
| SL_RAIL_ZWAVE_NODE_ID_LONG_RANGE_BROADCAST | The Long Range broadcast Node Id. |
| SL_RAIL_ZWAVE_NODE_ID_LONG_RANGE_DEFAULT | Default to the Long Range broadcast Node Id. |
sl_rail_zwave_home_id_t#
sl_rail_zwave_home_id_t
A Z-Wave Home Id.
Note
Home Ids in the range 0x54000000..0x55FFFFFF are illegal.
| Enumerator | |
|---|---|
| SL_RAIL_ZWAVE_HOME_ID_UNKNOWN | The unknown Home Id. |
| SL_RAIL_ZWAVE_HOME_ID_DEFAULT | An impossible and unlikely Home Id. |
sl_rail_zwave_home_id_hash_t#
sl_rail_zwave_home_id_hash_t
A Z-Wave Home Id hash.
Note
Certain values (as shown) are illegal.
| Enumerator | |
|---|---|
| SL_RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_0 | An illegal Home Id hash value. |
| SL_RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_1 | An illegal Home Id hash value. |
| SL_RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_2 | An illegal Home Id hash value. |
| SL_RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE | Illegal Home Id hash value that suppresses checking the Home Id hash field of beam packets. |
| SL_RAIL_ZWAVE_HOME_ID_HASH_DEFAULT | Default to don't care. |
sl_rail_zwave_baud_t#
sl_rail_zwave_baud_t
Z-Wave supported baud rates or PHYs.
| Enumerator | |
|---|---|
| SL_RAIL_ZWAVE_BAUD_9600 | 9.6 kbps baud rate. |
| SL_RAIL_ZWAVE_BAUD_40_K | 40 kbps baud rate. |
| SL_RAIL_ZWAVE_BAUD_100_K | 100 kbps baud rate. |
| SL_RAIL_ZWAVE_BAUD_LR | Long Range PHY. |
| SL_RAIL_ZWAVE_BAUD_INVALID | Sentinel value for invalid baud rate. |
sl_rail_zwave_phy_t#
sl_rail_zwave_phy_t
The Z-Wave PHY identifier (aka PTI radio configuration id).
| Enumerator | |
|---|---|
| SL_RAIL_ZWAVE_PHY_9P6_KBPS | |
| SL_RAIL_ZWAVE_PHY_9P6_KBPS_CONCURRENT | |
| SL_RAIL_ZWAVE_PHY_40_KBPS | |
| SL_RAIL_ZWAVE_PHY_40_KBPS_BEAM | |
| SL_RAIL_ZWAVE_PHY_100_KBPS | |
| SL_RAIL_ZWAVE_PHY_100_KBPS_LOWSIDE | |
| SL_RAIL_ZWAVE_PHY_100_KBPS_BEAM | |
| SL_RAIL_ZWAVE_PHY_100_KBPS_LOWSIDE_BEAM | |
| SL_RAIL_ZWAVE_PHY_LONG_RANGE | |
| SL_RAIL_ZWAVE_PHY_LONG_RANGE_BEAM | |
sl_rail_zwave_region_id_t#
sl_rail_zwave_region_id_t
Z-Wave region identifications.
| Enumerator | |
|---|---|
| SL_RAIL_ZWAVE_REGION_ID_UNKNOWN | Unknown/Invalid. |
| SL_RAIL_ZWAVE_REGION_ID_EU | European Union. |
| SL_RAIL_ZWAVE_REGION_ID_US | United States. |
| SL_RAIL_ZWAVE_REGION_ID_ANZ | Australia/New Zealand. |
| SL_RAIL_ZWAVE_REGION_ID_HK | Hong Kong. |
| SL_RAIL_ZWAVE_REGION_ID_MY | Malaysia. |
| SL_RAIL_ZWAVE_REGION_ID_IN | India. |
| SL_RAIL_ZWAVE_REGION_ID_JP | Japan. |
| SL_RAIL_ZWAVE_REGION_ID_RU | Russian Federation. |
| SL_RAIL_ZWAVE_REGION_ID_IL | Israel. |
| SL_RAIL_ZWAVE_REGION_ID_KR | Korea. |
| SL_RAIL_ZWAVE_REGION_ID_CN | China. |
| SL_RAIL_ZWAVE_REGION_ID_US_LR_1 | United States, with first long range PHY. |
| SL_RAIL_ZWAVE_REGION_ID_US_LR_2 | United States, with second long range PHY. |
| SL_RAIL_ZWAVE_REGION_ID_US_LR_3 | United States, with third long range PHY. |
| SL_RAIL_ZWAVE_REGION_ID_EU_LR_1 | European Union, with first long range PHY. |
| SL_RAIL_ZWAVE_REGION_ID_EU_LR_2 | European Union, with second long range PHY. |
| SL_RAIL_ZWAVE_REGION_ID_EU_LR_3 | European Union, with third long range PHY. |
| SL_RAIL_ZWAVE_REGION_ID_COUNT | Count of known regions. |
Typedef Documentation#
RAIL_RxChannelHoppingParameters_t#
RAIL_RxChannelHoppingParameters_t [(4U)]
Rx channel hopping on-channel time for all Z-Wave channels in a region.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_rx_channel_hopping_parameters_t.
sl_rail_zwave_rx_channel_hopping_parameters_t#
sl_rail_zwave_rx_channel_hopping_parameters_t [(4U)]
Rx channel hopping on-channel time for all Z-Wave channels in a region.
Variable Documentation#
RAIL_ZWAVE_REGION_EU#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_EU
EU-European Union.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_eu.
RAIL_ZWAVE_REGION_US#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US
US-United States.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_us.
RAIL_ZWAVE_REGION_ANZ#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_ANZ
ANZ-Australia/New Zealand.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_anz.
RAIL_ZWAVE_REGION_HK#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_HK
HK-Hong Kong.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_hk.
RAIL_ZWAVE_REGION_MY#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_MY
MY-Malaysia.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_my.
RAIL_ZWAVE_REGION_IN#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_IN
IN-India.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_in.
RAIL_ZWAVE_REGION_JP#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_JP
JP-Japan.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_jp.
RAIL_ZWAVE_REGION_JPED#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_JPED
JP-Japan Energy-Detect.
DeprecatedThis RAIL 2.x region config has been eliminated in RAIL 3; it only applied to devices no longer supported.
RAIL_ZWAVE_REGION_RU#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_RU
RU-Russia.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_ru.
RAIL_ZWAVE_REGION_IL#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_IL
IL-Israel.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_il.
RAIL_ZWAVE_REGION_KR#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_KR
KR-Korea.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_kr.
RAIL_ZWAVE_REGION_KRED#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_KRED
KR-Korea Energy-Detect.
DeprecatedThis RAIL 2.x region config has been eliminated in RAIL 3; it only applied to devices no longer supported.
RAIL_ZWAVE_REGION_CN#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_CN
CN-China.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_cn.
RAIL_ZWAVE_REGION_US_LR1#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US_LR1
US-Long Range 1.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_us_lr_1.
RAIL_ZWAVE_REGION_US_LR2#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US_LR2
US-Long Range 2.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_us_lr_2.
RAIL_ZWAVE_REGION_US_LR3#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US_LR3
US-Long Range 3.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_us_lr_3.
RAIL_ZWAVE_REGION_EU_LR1#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_EU_LR1
EU-Long Range 1.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_eu_lr_1.
RAIL_ZWAVE_REGION_EU_LR2#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_EU_LR2
EU-Long Range 2.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_eu_lr_2.
RAIL_ZWAVE_REGION_EU_LR3#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_EU_LR3
EU-Long Range 3.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_eu_lr_3.
RAIL_ZWAVE_REGION_INVALID#
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_INVALID
Invalid Region.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_region_invalid.
sl_rail_zwave_region_eu#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_eu
EU-European Union.
sl_rail_zwave_region_us#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_us
US-United States.
sl_rail_zwave_region_anz#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_anz
ANZ-Australia/New Zealand.
sl_rail_zwave_region_us_lr_1#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_us_lr_1
US-Long Range 1.
sl_rail_zwave_region_us_lr_2#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_us_lr_2
US-Long Range 2.
sl_rail_zwave_region_us_lr_3#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_us_lr_3
US-Long Range 3.
sl_rail_zwave_region_eu_lr_1#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_eu_lr_1
EU-Long Range 1.
sl_rail_zwave_region_eu_lr_2#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_eu_lr_2
EU-Long Range 2.
sl_rail_zwave_region_eu_lr_3#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_eu_lr_3
EU-Long Range 3.
sl_rail_zwave_region_invalid#
const sl_rail_zwave_region_config_t sl_rail_zwave_region_invalid
Invalid Region.
sl_rail_zwave_region_cfg#
const sl_rail_zwave_region_config_t* const sl_rail_zwave_region_cfg[SL_RAIL_ZWAVE_REGION_ID_COUNT]
An array of region configurations indexed by sl_rail_zwave_region_id_t.
Function Documentation#
RAIL_ZWAVE_ConfigRegion#
RAIL_Status_t RAIL_ZWAVE_ConfigRegion (RAIL_Handle_t railHandle, const RAIL_ZWAVE_RegionConfig_t * regionCfg)
Switch the Z-Wave region.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const RAIL_ZWAVE_RegionConfig_t * | [in] | regionCfg | A pointer to a Z-Wave channel configuration for the selected region. |
Returns
Status code indicating success of the function call.
Note
Setting a new Z-Wave Region will default any Low Power values to Normal Power values for the region. Z-Wave Region configuration must always be followed by a Low Power setup in case one desires to have the Low Power Acking functionality.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_config_region().
RAIL_ZWAVE_PerformIrcal#
RAIL_Status_t RAIL_ZWAVE_PerformIrcal (RAIL_Handle_t railHandle, RAIL_ZWAVE_IrcalVal_t * pIrCalVals, bool forceIrcal)
Perform image rejection calibration on all valid channels of a Z-Wave region.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_ZWAVE_IrcalVal_t * | [inout] | pIrCalVals | An application-provided pointer of type RAIL_ZWAVE_IrcalVal_t. This is populated with image rejection calibration values, if not NULL or initialized with RAIL_CAL_INVALID_VALUE or if forceIrcal is true. |
| bool | [in] | forceIrcal | If true, will always perform image rejection calibration and not use previously cached values. |
Returns
Status code indicating success of the function call.
Note
This function also calibrates for beam detection and should be called before RAIL_ZWAVE_ReceiveBeam() and after the Z-Wave region has been configured via RAIL_ZWAVE_ConfigRegion(). Channel hopping must be disabled otherwise this function will return RAIL_STATUS_INVALID_CALL.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_perform_ir_cal().
RAIL_ZWAVE_Init#
RAIL_Status_t RAIL_ZWAVE_Init (RAIL_Handle_t railHandle, const RAIL_ZWAVE_Config_t * config)
Initialize RAIL for Z-Wave features.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const RAIL_ZWAVE_Config_t * | [in] | config | A pointer to a Z-Wave configuration structure. |
Returns
Status code indicating success of the function call.
This function is the entry point for working with Z-Wave within RAIL. It sets up relevant hardware acceleration for Z-Wave-specific features, such as Home Id filtering and beam packets (as specified in the configuration) and allows users to select the relevant Z-Wave region-specific PHY via RAIL_ZWAVE_ConfigRegion().
DeprecatedRAIL 2.x synonym of sl_rail_zwave_init().
RAIL_ZWAVE_Deinit#
RAIL_Status_t RAIL_ZWAVE_Deinit (RAIL_Handle_t railHandle)
De-initialize Z-Wave 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 Z-Wave hardware acceleration features. This function should only be called when the radio is idle.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_deinit().
RAIL_ZWAVE_IsEnabled#
bool RAIL_ZWAVE_IsEnabled (RAIL_Handle_t railHandle)
Return whether Z-Wave hardware acceleration is currently enabled.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
true if Z-Wave hardware acceleration was enabled to start with and false otherwise.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_is_enabled().
RAIL_ZWAVE_ConfigOptions#
RAIL_Status_t RAIL_ZWAVE_ConfigOptions (RAIL_Handle_t railHandle, RAIL_ZWAVE_Options_t mask, RAIL_ZWAVE_Options_t options)
Configure Z-Wave options.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_ZWAVE_Options_t | [in] | mask | A bitmask containing which options should be modified. |
| RAIL_ZWAVE_Options_t | [in] | options | A bitmask containing desired configuration settings. Bit positions for each option are found in the RAIL_ZWAVE_Options_t. |
Returns
Status code indicating success of the function call.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_config_options().
RAIL_ZWAVE_SetNodeId#
RAIL_Status_t RAIL_ZWAVE_SetNodeId (RAIL_Handle_t railHandle, RAIL_ZWAVE_NodeId_t nodeId)
Inform RAIL of the Z-Wave node's Node Id for receive filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_ZWAVE_NodeId_t | [in] | nodeId | A Z-Wave Node Id. |
Returns
Status code indicating success of the function call.
Note
Until this API is called, RAIL will assume the Node Id is RAIL_ZWAVE_NODE_ID_DEFAULT.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_set_node_id().
RAIL_ZWAVE_SetHomeId#
RAIL_Status_t RAIL_ZWAVE_SetHomeId (RAIL_Handle_t railHandle, RAIL_ZWAVE_HomeId_t homeId, RAIL_ZWAVE_HomeIdHash_t homeIdHash)
Inform RAIL of the Z-Wave node's Home Id and its hash for receive filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_ZWAVE_HomeId_t | [in] | homeId | A Z-Wave Home Id. |
| RAIL_ZWAVE_HomeIdHash_t | [in] | homeIdHash | The hash of the Home Id expected in beam frames. If this is RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE, beam frame detection will not check the Home Id hash in a received beam frame at all, and RAIL_EVENT_ZWAVE_BEAM will trigger based solely on the Node Id in the beam frame. |
Returns
Status code indicating success of the function call.
Note
Until this API is called, RAIL will assume the Home Id is an illegal one of RAIL_ZWAVE_HOME_ID_DEFAULT, and its hash is RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_set_home_id().
RAIL_ZWAVE_GetBeamNodeId#
RAIL_Status_t RAIL_ZWAVE_GetBeamNodeId (RAIL_Handle_t railHandle, RAIL_ZWAVE_NodeId_t * pNodeId)
Get the Node Id of the most recently seen beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_ZWAVE_NodeId_t * | [out] | pNodeId | A pointer to RAIL_ZWAVE_NodeId_t to populate. |
Returns
Status code indicating success of the function call.
Note
This is best called while handling the RAIL_EVENT_ZWAVE_BEAM event; if multiple beams are received only the most recent beam's NodeId is provided.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_zwave_get_rx_beam_details() using sl_rail_zwave_beam_details_t::node_id.
RAIL_ZWAVE_GetBeamHomeIdHash#
RAIL_Status_t RAIL_ZWAVE_GetBeamHomeIdHash (RAIL_Handle_t railHandle, RAIL_ZWAVE_HomeIdHash_t * pBeamHomeIdHash)
Get the Home Id hash of the most recently seen beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_ZWAVE_HomeIdHash_t * | [out] | pBeamHomeIdHash | A pointer to RAIL_ZWAVE_HomeIdHash_t to populate. |
Returns
Status code indicating success of the function call.
Note
This is best called while handling the RAIL_EVENT_ZWAVE_BEAM event; if multiple beams are received only the most recent beam's Home Id hash is provided.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_zwave_get_rx_beam_details() using sl_rail_zwave_beam_details_t::home_id_hash.
RAIL_ZWAVE_GetBeamChannelIndex#
RAIL_Status_t RAIL_ZWAVE_GetBeamChannelIndex (RAIL_Handle_t railHandle, uint8_t * pChannelIndex)
Get the channel hopping index of the most recently seen beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint8_t * | [out] | pChannelIndex | A pointer to a uint8_t to populate with the channel hopping index. If channel-hopping was off at the time the beam packet was received, RAIL_CHANNEL_HOPPING_INVALID_INDEX is provided. |
Returns
Status code indicating success of the function call.
Note
This is best called while handling the RAIL_EVENT_ZWAVE_BEAM event; if multiple beams are received only the most recent beam's channel hopping index is provided.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_zwave_get_rx_beam_details() using sl_rail_zwave_beam_details_t::channel_index.
RAIL_ZWAVE_GetLrBeamTxPower#
RAIL_Status_t RAIL_ZWAVE_GetLrBeamTxPower (RAIL_Handle_t railHandle, uint8_t * pLrBeamTxPower)
Get the TX power used by the transmitter of the most recently seen long range beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint8_t * | [out] | pLrBeamTxPower | An application provided pointer to a uint8_t to be populated with the TX power of the latest long range beam. This will be set to RAIL_ZWAVE_LR_BEAM_TX_POWER_INVALID if this API is called after receiving a regular non-long-range beam. |
Returns
Status code indicating success of the function call. This function will return RAIL_STATUS_INVALID_STATE if called after receiving a regular (non-long-range) beam.
Note
This is best called while handling the RAIL_EVENT_ZWAVE_BEAM event; if multiple beams are received only the most recent long range beam's TX power is provided.
The following table shows long range beam TX power value to dBm value mapping:
Tx Power Value | Description |
|---|---|
0 | -6 dBm |
1 | -2 dBm |
2 | +2 dBm |
3 | +6 dBm |
4 | +10 dBm |
5 | +13 dBm |
6 | +16 dBm |
7 | +19 dBm |
8 | +21 dBm |
9 | +23 dBm |
10 | +25 dBm |
11 | +26 dBm |
12 | +27 dBm |
13 | +28 dBm |
14 | +29 dBm |
15 | +30 dBm |
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_zwave_get_rx_beam_details() using sl_rail_zwave_beam_details_t::lr_tx_power.
RAIL_ZWAVE_GetBeamRssi#
RAIL_Status_t RAIL_ZWAVE_GetBeamRssi (RAIL_Handle_t railHandle, int8_t * pBeamRssi)
Get the RSSI of the received beam frame.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| int8_t * | [out] | pBeamRssi | An application provided pointer to a int8_t to be populated with the latest beam's RSSI, in dBm. |
Returns
Status code indicating success of the function call. This function will return RAIL_STATUS_INVALID_STATE if called without ever having received a beam.
Note
This is best called while handling the RAIL_EVENT_ZWAVE_BEAM event; if multiple beams are received only the most recent beam's RSSI is provided.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_zwave_get_rx_beam_details() using sl_rail_zwave_beam_details_t::rssi_dbm.
RAIL_ZWAVE_SetTxLowPower#
RAIL_Status_t RAIL_ZWAVE_SetTxLowPower (RAIL_Handle_t railHandle, uint8_t powerLevel)
Set the Raw Low Power settings.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint8_t | [in] | powerLevel | Desired low power raw level. |
Returns
Status code indicating success of the function call.
Low Power settings are required during Ack transmissions when the Low Power Bit is set. This setting is only valid for one subsequent transmission, after which all transmissions will be at the nominal power setting, until re-invoked.
DeprecatedThis RAIL 2.x function has been eliminated.
RAIL_ZWAVE_GetTxLowPower#
RAIL_TxPowerLevel_t RAIL_ZWAVE_GetTxLowPower (RAIL_Handle_t railHandle)
Get the TX low power in raw units (see rail_chip_specific.h for value ranges).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
The chip-specific RAIL_TxPowerLevel_t raw value of the low transmit power.
This API returns the low raw power value that was set by RAIL_ZWAVE_SetTxLowPower().
Calling this function before configuring the Low Power PA (i.e., before a successful call to RAIL_ZWAVE_SetTxLowPowerDbm() or RAIL_ZWAVE_SetTxLowPower()) will return a low power value that is the same as the nominal power. Also, calling this function before configuring the PA (i.e., before a successful call to RAIL_ConfigTxPower()) will return RAIL_TX_POWER_LEVEL_INVALID.
DeprecatedThis RAIL 2.x function has been eliminated.
RAIL_ZWAVE_SetTxLowPowerDbm#
RAIL_Status_t RAIL_ZWAVE_SetTxLowPowerDbm (RAIL_Handle_t railHandle, RAIL_TxPower_t power)
Set the Low Power settings in deci-dBm.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_TxPower_t | [in] | power | Desired low power in deci-dBm. |
Returns
Status code indicating success of the function call.
Low Power settings are required during Ack transmissions when the Low Power Bit is set. This setting is only valid for one subsequent transmission, after which all transmissions will be at the nominal power setting, until re-invoked.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_set_tx_low_power_dbm().
RAIL_ZWAVE_GetTxLowPowerDbm#
RAIL_TxPower_t RAIL_ZWAVE_GetTxLowPowerDbm (RAIL_Handle_t railHandle)
Get the TX low power in terms of deci-dBm.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
The chip-specific RAIL_TxPower_t value of the low transmit power in deci-dBm.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_get_tx_low_power_dbm().
RAIL_ZWAVE_ReceiveBeam#
RAIL_Status_t RAIL_ZWAVE_ReceiveBeam (RAIL_Handle_t railHandle, uint8_t * beamDetectIndex, const RAIL_SchedulerInfo_t * schedulerInfo)
Implement beam detection and reception algorithms.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint8_t * | [out] | beamDetectIndex | A pointer to an indicator of whether or not a beam was detected at all, regardless of if it was received, generally for use only by instruction from Silicon Labs. Can be NULL. |
| const RAIL_SchedulerInfo_t * | [in] | schedulerInfo | A pointer to information to allow the radio scheduler to place this operation appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions. Note that Z-Wave currently does not support multiprotocol, so this scheduler info exists to future proof the API for when it does. |
Returns
Status code indicating success of the function call. Reasons for failure include an un-idled radio or a non-Japan non-Korea region configured before calling this function.
This function takes care of all configuration and radio setup to detect and receive beams in the current Z-Wave region. If a beam is detected, RAIL will provide the usual RAIL_EVENT_ZWAVE_BEAM event during which time users can process the beam as expected. However, normal packets may also be received during this time (also triggering RAIL_EVENTS_RX_COMPLETION events), in which case, this API may need to be re-called to receive a beam. Users should also listen for RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE, which will indicate that no beam is heard. At that point, the radio will be automatically idled. Until one of these events is received, users should not try to reconfigure radio settings or start another radio operation. If an application needs to do some other operation or configuration, it must first call RAIL_Idle() and wait for the radio to idle.
Note
: The radio must be idle before calling this function.
: RAIL_ConfigRxChannelHopping() must have been called successfully in Z-Wave before this function is called to provide a valid memory buffer for internal use (see RAIL_RxChannelHoppingConfig_t::buffer).
: This function alters radio functionality substantially. After calling it, the user should call RAIL_ZWAVE_ConfigRegion(), RAIL_ConfigRxChannelHopping(), RAIL_EnableRxChannelHopping(), and RAIL_SetRxTransitions() to reset these parameters to whatever behaviors were desired before calling this function. Additionally, this function will idle the radio upon on exit.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_receive_beam().
RAIL_ZWAVE_ConfigBeamRx#
RAIL_Status_t RAIL_ZWAVE_ConfigBeamRx (RAIL_Handle_t railHandle, const RAIL_ZWAVE_BeamRxConfig_t * config)
Configure the receive algorithm used in RAIL_ZWAVE_ReceiveBeam().
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const RAIL_ZWAVE_BeamRxConfig_t * | [in] | config | A pointer to a configuration for the beam detection algorithm. |
Returns
Status code indicating success of the function call.
Warnings
This function should not be used without direct instruction by Silicon Labs.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_config_beam_rx().
RAIL_ZWAVE_SetDefaultRxBeamConfig#
RAIL_Status_t RAIL_ZWAVE_SetDefaultRxBeamConfig (RAIL_Handle_t railHandle)
Set the default RX beam configuration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
Note
This function resets any changes made to the beam configuration via RAIL_ZWAVE_ConfigBeamRx() and the default beam configuration will be in effect on subsequent call(s) to RAIL_ZWAVE_ReceiveBeam().
DeprecatedRAIL 2.x synonym of sl_rail_zwave_set_default_rx_beam_config().
RAIL_ZWAVE_GetRxBeamConfig#
RAIL_Status_t RAIL_ZWAVE_GetRxBeamConfig (RAIL_ZWAVE_BeamRxConfig_t * pConfig)
Get the current RX beam configuration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_ZWAVE_BeamRxConfig_t * | [out] | pConfig | A pointer to RAIL_ZWAVE_BeamRxConfig_t to be populated with the current beam configuration. |
Returns
Status code indicating success of the function call.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_get_rx_beam_config().
RAIL_ZWAVE_ConfigRxChannelHopping#
RAIL_Status_t RAIL_ZWAVE_ConfigRxChannelHopping (RAIL_Handle_t railHandle, RAIL_RxChannelHoppingConfig_t * config)
Configure the channel hop timings for use in Z-Wave RX channel hop configuration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_RxChannelHoppingConfig_t * | [inout] | config | A pointer to a configuration for Z-Wave RX channel hopping. This structure must be allocated in application global read-write memory. RAIL will populate fields within or referenced by this structure during its operation. Be sure to allocate RAIL_RxChannelHoppingConfigEntry_t entries[] for RAIL_NUM_ZWAVE_CHANNELS. Be sure to set RAIL_RxChannelHoppingConfig_t::numberOfChannels to the desired number of channels. |
Returns
Status code indicating success of the function call.
Warnings
This function should not be used without direct instruction by Silicon Labs.
Note
: This API must be called before RAIL_EnableRxChannelHopping(). This API must never be called while the radio is on with RX Duty Cycle or Channel Hopping enabled.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_config_rx_channel_hopping().
RAIL_ZWAVE_GetRegion#
RAIL_ZWAVE_RegionId_t RAIL_ZWAVE_GetRegion (RAIL_Handle_t railHandle)
Get the Z-Wave region.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
The RAIL_ZWAVE_RegionId_t value.
Note
RAIL_ZWAVE_ConfigRegion() must have been called successfully before this function is called. Otherwise, RAIL_ZWAVE_REGIONID_UNKNOWN is returned.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_get_region().
RAIL_ZWAVE_SetLrAckData#
RAIL_Status_t RAIL_ZWAVE_SetLrAckData (RAIL_Handle_t railHandle, const RAIL_ZWAVE_LrAckData_t * pLrAckData)
Write the Auto-Ack FIFO for the next outgoing Z-Wave Long Range Ack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| const RAIL_ZWAVE_LrAckData_t * | [in] | pLrAckData | An application provided pointer to a const RAIL_ZWAVE_LrAckData_t to populate the noise floor, TX power and receive rssi bytes of the outgoing Z-Wave Long Range Ack packet. |
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_ZWAVE_LR_ACK_REQUEST_COMMAND. This will return RAIL_STATUS_INVALID_STATE if it is too late to write the outgoing Ack. When successful, the ackData will only be sent once. Subsequent packets needing an Z-Wave Long Range Ack will each need to call this function to write the Ack information.
DeprecatedRAIL 2.x synonym of sl_rail_zwave_set_lr_ack_data().
sl_rail_zwave_config_region#
sl_rail_status_t sl_rail_zwave_config_region (sl_rail_handle_t rail_handle, const sl_rail_zwave_region_config_t * p_region_config)
Switch the Z-Wave region.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const sl_rail_zwave_region_config_t * | [in] | p_region_config | A pointer to a Z-Wave channel configuration for the selected region. |
Returns
Status code indicating success of the function call.
Note
Setting a new Z-Wave Region will default any Low Power values to Normal Power values for the region. Z-Wave Region configuration must always be followed by a Low Power setup in case one desires to have the Low Power Acking functionality.
sl_rail_zwave_perform_ir_cal#
sl_rail_status_t sl_rail_zwave_perform_ir_cal (sl_rail_handle_t rail_handle, sl_rail_zwave_ir_cal_val_t * p_ir_cal_vals, bool force_ir_cal)
Perform image rejection calibration on all valid channels of a Z-Wave region.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_zwave_ir_cal_val_t * | [inout] | p_ir_cal_vals | An application-provided pointer of type sl_rail_zwave_ir_cal_val_t. This is populated with image rejection calibration values, if not NULL or initialized with SL_RAIL_CAL_INVALID_VALUE or if force_ir_cal is true. |
| bool | [in] | force_ir_cal | If true, will always perform image rejection calibration and not use previously cached values. |
Returns
Status code indicating success of the function call.
Note
This function also calibrates for beam detection and should be called before sl_rail_zwave_receive_beam() and after the Z-Wave region has been configured via sl_rail_zwave_config_region(). Channel hopping must be disabled otherwise this function will return SL_RAIL_STATUS_INVALID_CALL.
sl_rail_zwave_init#
sl_rail_status_t sl_rail_zwave_init (sl_rail_handle_t rail_handle, const sl_rail_zwave_config_t * p_config)
Initialize RAIL for Z-Wave features.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const sl_rail_zwave_config_t * | [in] | p_config | A pointer to a Z-Wave configuration structure. |
Returns
Status code indicating success of the function call.
This function is the entry point for working with Z-Wave within RAIL. It sets up relevant hardware acceleration for Z-Wave-specific features, such as Home Id filtering and beam packets (as specified in the configuration) and allows users to select the relevant Z-Wave region-specific PHY via sl_rail_zwave_config_region().
sl_rail_zwave_deinit#
sl_rail_status_t sl_rail_zwave_deinit (sl_rail_handle_t rail_handle)
De-initialize Z-Wave 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 Z-Wave hardware acceleration features. This function should only be called when the radio is idle.
sl_rail_zwave_is_enabled#
bool sl_rail_zwave_is_enabled (sl_rail_handle_t rail_handle)
Return whether Z-Wave 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 Z-Wave hardware acceleration was enabled to start with and false otherwise.
sl_rail_zwave_config_options#
sl_rail_status_t sl_rail_zwave_config_options (sl_rail_handle_t rail_handle, sl_rail_zwave_options_t mask, sl_rail_zwave_options_t options)
Configure Z-Wave options.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_zwave_options_t | [in] | mask | A bitmask containing which options should be modified. |
| sl_rail_zwave_options_t | [in] | options | A bitmask containing desired configuration settings. Bit positions for each option are found in the sl_rail_zwave_options_t. |
Returns
Status code indicating success of the function call.
sl_rail_zwave_set_node_id#
sl_rail_status_t sl_rail_zwave_set_node_id (sl_rail_handle_t rail_handle, sl_rail_zwave_node_id_t node_id)
Inform RAIL of the Z-Wave node's Node Id for receive filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_zwave_node_id_t | [in] | node_id | A Z-Wave Node Id. |
Returns
Status code indicating success of the function call.
Note
Until this API is called, RAIL will assume the Node Id is SL_RAIL_ZWAVE_NODE_ID_DEFAULT.
sl_rail_zwave_set_home_id#
sl_rail_status_t sl_rail_zwave_set_home_id (sl_rail_handle_t rail_handle, sl_rail_zwave_home_id_t home_id, sl_rail_zwave_home_id_hash_t home_id_hash)
Inform RAIL of the Z-Wave node's Home Id and its hash for receive filtering.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_zwave_home_id_t | [in] | home_id | A Z-Wave Home Id. |
| sl_rail_zwave_home_id_hash_t | [in] | home_id_hash | The hash of the home_id expected in beam frames. If this is SL_RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE, beam frame detection will not check the Home Id hash in a received beam frame at all, and SL_RAIL_EVENT_ZWAVE_BEAM will trigger based solely on the Node Id in the beam frame. |
Returns
Status code indicating success of the function call.
Note
Until this API is called, RAIL will assume the Home Id is an illegal one of SL_RAIL_ZWAVE_HOME_ID_DEFAULT, and its hash is SL_RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE.
sl_rail_zwave_get_rx_beam_details#
sl_rail_status_t sl_rail_zwave_get_rx_beam_details (sl_rail_handle_t rail_handle, sl_rail_zwave_beam_details_t * p_beam_details)
Get detailed information about a Z-Wave beam frame that triggered SL_RAIL_EVENT_ZWAVE_BEAM.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_zwave_beam_details_t * | [out] | p_beam_details | An application provided pointer to sl_rail_zwave_beam_details_t to populate the Node Id, Home Id hash, channel hopping index, RSSI, and TX Power (for long range beam only) of the received beam frame. |
Returns
Status code indicating success of the function call.
Note
This is best called while handling the SL_RAIL_EVENT_ZWAVE_BEAM event; if multiple beams are received only the most recent beam's details are provided.
sl_rail_zwave_beam_details_t::channel_index will be set to SL_RAIL_CHANNEL_HOPPING_INVALID_INDEX if channel-hopping was off at the time the beam packet was received.
sl_rail_zwave_beam_details_t::lr_tx_power will be set to SL_RAIL_ZWAVE_LR_BEAM_TX_POWER_INVALID if this API is called after receiving a regular non Long Range beam.
sl_rail_zwave_set_tx_low_power_dbm#
sl_rail_status_t sl_rail_zwave_set_tx_low_power_dbm (sl_rail_handle_t rail_handle, sl_rail_tx_power_t power_ddbm)
Set the Low Power settings in deci-dBm.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_tx_power_t | [in] | power_ddbm | Desired low power in deci-dBm. |
Returns
Status code indicating success of the function call.
Low Power settings are required during Ack transmissions when the Low Power Bit is set. This setting is only valid for one subsequent transmission, after which all transmissions will be at the nominal power setting, until re-invoked.
sl_rail_zwave_get_tx_low_power_dbm#
sl_rail_tx_power_t sl_rail_zwave_get_tx_low_power_dbm (sl_rail_handle_t rail_handle)
Get the TX low power in terms of deci-dBm.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A RAIL instance handle. |
Returns
The chip-specific sl_rail_tx_power_t value of the low transmit power in deci-dBm.
sl_rail_zwave_receive_beam#
sl_rail_status_t sl_rail_zwave_receive_beam (sl_rail_handle_t rail_handle, uint8_t * p_beam_detect_index, const sl_rail_scheduler_info_t * p_scheduler_info)
Implement beam detection and reception algorithms.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| uint8_t * | [out] | p_beam_detect_index | A pointer to an indicator of whether or not a beam was detected at all, regardless of if it was received, generally for use only by instruction from Silicon Labs. Can be NULL. |
| const sl_rail_scheduler_info_t * | [in] | p_scheduler_info | A pointer to information to allow the radio scheduler to place this operation appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions. Note that Z-Wave currently does not support multiprotocol, so this scheduler info exists to future proof the API for when it does. |
Returns
Status code indicating success of the function call. Reasons for failure include an un-idled radio or a non-Japan non-Korea region configured before calling this function.
This function takes care of all configuration and radio setup to detect and receive beams in the current Z-Wave region. If a beam is detected, RAIL will provide the usual SL_RAIL_EVENT_ZWAVE_BEAM event during which time users can process the beam as expected. However, normal packets may also be received during this time (also triggering SL_RAIL_EVENTS_RX_COMPLETION events), in which case, this API may need to be re-called to receive a beam. Users should also listen for SL_RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE, which will indicate that no beam is heard. At that point, the radio will be automatically idled. Until one of these events is received, users should not try to reconfigure radio settings or start another radio operation. If an application needs to do some other operation or configuration, it must first call sl_rail_idle() and wait for the radio to idle.
Note
: The radio must be idle before calling this function.
: sl_rail_config_rx_channel_hopping() must have been called successfully in Z-Wave before this function is called to provide a valid memory buffer for internal use (see sl_rail_rx_channel_hopping_config_t::p_buffer).
: This function alters radio functionality substantially. After calling it, the user should call sl_rail_zwave_config_region(), sl_rail_config_rx_channel_hopping(), sl_rail_enable_rx_channel_hopping(), and sl_rail_set_rx_transitions() to reset these parameters to whatever behaviors were desired before calling this function. Additionally, this function will idle the radio upon on exit.
sl_rail_zwave_config_beam_rx#
sl_rail_status_t sl_rail_zwave_config_beam_rx (sl_rail_handle_t rail_handle, const sl_rail_zwave_beam_rx_config_t * p_config)
Configure the receive algorithm used in sl_rail_zwave_receive_beam().
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const sl_rail_zwave_beam_rx_config_t * | [in] | p_config | A pointer to a configuration for the beam detection algorithm. |
Returns
Status code indicating success of the function call.
Warnings
This function should not be used without direct instruction by Silicon Labs.
sl_rail_zwave_set_default_rx_beam_config#
sl_rail_status_t sl_rail_zwave_set_default_rx_beam_config (sl_rail_handle_t rail_handle)
Set the default RX beam configuration.
| 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.
Note
This function resets any changes made to the beam configuration via sl_rail_zwave_config_beam_rx() and the default beam configuration will be in effect on subsequent call(s) to sl_rail_zwave_receive_beam().
sl_rail_zwave_get_rx_beam_config#
sl_rail_status_t sl_rail_zwave_get_rx_beam_config (sl_rail_handle_t rail_handle, sl_rail_zwave_beam_rx_config_t * p_config)
Get the current RX beam configuration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_zwave_beam_rx_config_t * | [out] | p_config | A pointer to sl_rail_zwave_beam_rx_config_t to be populated with the current beam configuration. |
Returns
Status code indicating success of the function call.
sl_rail_zwave_config_rx_channel_hopping#
sl_rail_status_t sl_rail_zwave_config_rx_channel_hopping (sl_rail_handle_t rail_handle, sl_rail_rx_channel_hopping_config_t * p_config)
Configure the channel hop timings for use in Z-Wave RX channel hop configuration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_rx_channel_hopping_config_t * | [inout] | p_config | A pointer to a configuration for Z-Wave RX channel hopping. This structure must be allocated in application global read-write memory. RAIL will populate fields within or referenced by this structure during its operation. Be sure to allocate sl_rail_rx_channel_hopping_config_entry_t entries[] for SL_RAIL_NUM_ZWAVE_CHANNELS. Be sure to set sl_rail_rx_channel_hopping_config_t::number_of_channels to the desired number of channels. |
Returns
Status code indicating success of the function call.
Warnings
This function should not be used without direct instruction by Silicon Labs.
Note
: This API must be called before sl_rail_enable_rx_channel_hopping(). This API must never be called while the radio is on with RX Duty Cycle or Channel Hopping enabled.
sl_rail_zwave_get_region#
sl_rail_zwave_region_id_t sl_rail_zwave_get_region (sl_rail_handle_t rail_handle)
Get the Z-Wave region.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
The sl_rail_zwave_region_id_t value.
Note
sl_rail_zwave_config_region() must have been called successfully before this function is called. Otherwise, SL_RAIL_ZWAVE_REGION_ID_UNKNOWN is returned.
sl_rail_zwave_set_lr_ack_data#
sl_rail_status_t sl_rail_zwave_set_lr_ack_data (sl_rail_handle_t rail_handle, const sl_rail_zwave_lr_ack_data_t * p_lr_ack_data)
Write the Auto-Ack FIFO for the next outgoing Z-Wave Long Range Ack.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| const sl_rail_zwave_lr_ack_data_t * | [in] | p_lr_ack_data | An application provided pointer to a const sl_rail_zwave_lr_ack_data_t to populate the noise floor, TX power and receive rssi bytes of the outgoing Z-Wave Long Range Ack packet. |
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_ZWAVE_LR_ACK_REQUEST_COMMAND. This will return SL_RAIL_STATUS_INVALID_STATE if it is too late to write the outgoing Ack. When successful, the p_lr_ack_data will only be sent once. Subsequent packets needing an Z-Wave Long Range Ack will each need to call this function to write the Ack information.