Z-Wave
RAIL API > Protocol-specific

Z-Wave configuration routines.

Data Structures

struct  RAIL_ZWAVE_Config_t
 A configuration structure for Z-Wave in RAIL.
 
struct  RAIL_ZWAVE_BeamRxConfig_t
 Configuration structure for Z-Wave Beam Detection.
 
struct  RAIL_ZWAVE_RegionConfig_t
 Each Z-Wave region supports 3 channels.

Macros

#define RAIL_NUM_ZWAVE_CHANNELS   (3U)
 Number of channels in each of Z-Wave's region-based PHYs.
 
#define RAIL_ZWAVE_OPTIONS_NONE   0U
 A value representing no options.
 
#define RAIL_ZWAVE_OPTIONS_DEFAULT   RAIL_ZWAVE_OPTIONS_NONE
 All options are disabled by default.
 
#define RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE   (1u << RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE_SHIFT)
 An option to configure promiscuous mode, accepting packets regardless of HomeId.
 
#define RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES   (1u << RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES_SHIFT)
 An option to configure Beam frame recognition.
 
#define RAIL_ZWAVE_OPTION_NODE_ID_FILTERING   (1u << RAIL_ZWAVE_OPTION_NODE_ID_FILTERING_SHIFT)
 An option to filter packets based on Node ID when not promiscuous.
 
#define RAIL_ZWAVE_OPTIONS_ALL   0xFFFFFFFFU
 A value representing all options.

Enumerations

enum  RAIL_ZWAVE_Options_t {
  RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE_SHIFT = 0,
  RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES_SHIFT,
  RAIL_ZWAVE_OPTION_NODE_ID_FILTERING_SHIFT
}
 Z-Wave options.
 
enum  RAIL_ZWAVE_NodeId_t {
  RAIL_ZWAVE_NODE_ID_NONE = 0x00U,
  RAIL_ZWAVE_NODE_ID_BROADCAST = 0xFFU,
  RAIL_ZWAVE_NODE_ID_DEFAULT = RAIL_ZWAVE_NODE_ID_BROADCAST
}
 A Z-Wave Node Id.
 
enum  RAIL_ZWAVE_HomeId_t {
  RAIL_ZWAVE_HOME_ID_UNKNOWN = 0x00000000U,
  RAIL_ZWAVE_HOME_ID_DEFAULT = 0x54545454U
}
 A Z-Wave Home Id.
 
enum  RAIL_ZWAVE_HomeIdHash_t {
  RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_1 = 0x0AU,
  RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_2 = 0x4AU,
  RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_3 = 0x55U,
  RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE = 0x55U,
  RAIL_ZWAVE_HOME_ID_HASH_DEFAULT = RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE
}
 A Z-Wave Home Id hash.
 
enum  RAIL_ZWAVE_Baud_t {
  RAIL_ZWAVE_BAUD_9600,
  RAIL_ZWAVE_BAUD_40K,
  RAIL_ZWAVE_BAUD_100K,
  RAIL_ZWAVE_ENERGY_DETECT
}
 Z-Wave supported baudrates.
 
enum  RAIL_ZWAVE_RegionId_t {
  RAIL_ZWAVE_REGIONID_UNKNOWN,
  RAIL_ZWAVE_REGIONID_EU,
  RAIL_ZWAVE_REGIONID_US,
  RAIL_ZWAVE_REGIONID_ANZ,
  RAIL_ZWAVE_REGIONID_HK,
  RAIL_ZWAVE_REGIONID_MY,
  RAIL_ZWAVE_REGIONID_IN,
  RAIL_ZWAVE_REGIONID_JP,
  RAIL_ZWAVE_REGIONID_RU,
  RAIL_ZWAVE_REGIONID_IL,
  RAIL_ZWAVE_REGIONID_KR,
  RAIL_ZWAVE_REGIONID_CN,
  RAIL_ZWAVE_REGIONID_COUNT
}
 Z-Wave region identifications.

Functions

RAIL_Status_t RAIL_ZWAVE_ConfigRegion (RAIL_Handle_t railHandle, const RAIL_ZWAVE_RegionConfig_t *regionCfg)
 Switch the Z-Wave region.
 
RAIL_Status_t RAIL_ZWAVE_Init (RAIL_Handle_t railHandle, const RAIL_ZWAVE_Config_t *config)
 Initialize RAIL for Z-Wave features.
 
RAIL_Status_t RAIL_ZWAVE_Deinit (RAIL_Handle_t railHandle)
 De-initialize Z-Wave hardware acceleration.
 
bool RAIL_ZWAVE_IsEnabled (RAIL_Handle_t railHandle)
 Returns whether Z-Wave hardware acceleration is currently enabled.
 
RAIL_Status_t RAIL_ZWAVE_ConfigOptions (RAIL_Handle_t railHandle, RAIL_ZWAVE_Options_t mask, RAIL_ZWAVE_Options_t options)
 Configure Z-Wave options.
 
RAIL_Status_t RAIL_ZWAVE_SetNodeId (RAIL_Handle_t railHandle, RAIL_ZWAVE_NodeId_t nodeId)
 Inform RAIL of the Z-Wave node's NodeId for receive filtering purposes.
 
RAIL_Status_t RAIL_ZWAVE_SetHomeId (RAIL_Handle_t railHandle, RAIL_ZWAVE_HomeId_t homeId, RAIL_ZWAVE_HomeIdHash_t homeIdHash)
 Informs RAIL of the Z-Wave node's HomeId and its hash for receive filtering purposes.
 
RAIL_Status_t RAIL_ZWAVE_GetBeamNodeId (RAIL_Handle_t railHandle, RAIL_ZWAVE_NodeId_t *pNodeId)
 Get the NodeId of the most recently seen Beam frame that targeted this node.
 
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 targeted this node.
 
RAIL_Status_t RAIL_ZWAVE_SetTxLowPower (RAIL_Handle_t railHandle, uint8_t powerLevel)
 Sets the Raw Low Power settings.
 
RAIL_Status_t RAIL_ZWAVE_SetTxLowPowerDbm (RAIL_Handle_t railHandle, RAIL_TxPower_t powerLevel)
 Set the Low Power settings in dBm.
 
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).
 
RAIL_TxPower_t RAIL_ZWAVE_GetTxLowPowerDbm (RAIL_Handle_t railHandle)
 Get the TX low power in terms of deci-dBm instead of raw power level.
 
RAIL_Status_t RAIL_ZWAVE_ReceiveBeam (RAIL_Handle_t railHandle, uint8_t *beamDetectIndex, const RAIL_SchedulerInfo_t *schedulerInfo)
 This function is used to implement beam detection and reception algorithms.
 
RAIL_Status_t RAIL_ZWAVE_ConfigBeamRx (RAIL_Handle_t railHandle, RAIL_ZWAVE_BeamRxConfig_t *config)
 Configure the receive algorithm used in RAIL_ZWAVE_ReceiveBeam.

Variables

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_EU
 EU-European Union", RAIL_ZWAVE_REGION_EU.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US
 US-United States", RAIL_ZWAVE_REGION_US.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_ANZ
 ANZ-Australia/New Zealand", RAIL_ZWAVE_REGION_ANZ.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_HK
 HK-Hong Kong", RAIL_ZWAVE_REGION_HK.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_MY
 MY-Malaysia", RAIL_ZWAVE_REGION_MY.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_IN
 IN-India", RAIL_ZWAVE_REGION_IN.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_JP
 JP-Japan", RAIL_ZWAVE_REGION_JP.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_JPED
 JP-Japan", RAIL_ZWAVE_REGION_JP.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_RU
 RU-Russia", RAIL_ZWAVE_REGION_RU.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_IL
 IL-Israel", RAIL_ZWAVE_REGION_IL.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_KR
 KR-Korea", RAIL_ZWAVE_REGION_KR.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_KRED
 KR-Korea", RAIL_ZWAVE_REGION_KR.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_CN
 CN-China", RAIL_ZWAVE_REGION_CN.
 
const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_INVALID
 Invalid Region.

Detailed Description

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 beamNodeId 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);
}

Macro Definition Documentation

◆ RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES

#define RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES   (1u << RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES_SHIFT)

An option to configure Beam frame recognition.

Defaults to false. When true, Beam frames that are broadcast or match the NodeId and HomeIdHash values will trigger RAIL_EVENT_ZWAVE_BEAM event, in addition to RAIL_EVENT_RX_PACKET_ABORTED which occurs for every received Beam frame.

Note
This option takes precedence over RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE when receiving a beam frame. If this option is false, beam frames are not considered special and will be received as if they were normal Z-Wave frames, assuredly triggering RAIL_EVENT_RX_FRAME_ERROR.

Definition at line 142 of file rail_zwave.h.

◆ RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE

#define RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE   (1u << RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE_SHIFT)

An option to configure promiscuous mode, accepting packets regardless of HomeId.

Defaults to false, filtering packets based on the HomeId. When true, such filtering is disabled.

Definition at line 127 of file rail_zwave.h.

◆ RAIL_ZWAVE_OPTIONS_DEFAULT

#define RAIL_ZWAVE_OPTIONS_DEFAULT   RAIL_ZWAVE_OPTIONS_NONE

All options are disabled by default.

Definition at line 120 of file rail_zwave.h.

Enumeration Type Documentation

◆ RAIL_ZWAVE_Baud_t

enum RAIL_ZWAVE_Baud_t

Z-Wave supported baudrates.

Enumerator
RAIL_ZWAVE_BAUD_9600 

9.6kbps baudrate

RAIL_ZWAVE_BAUD_40K 

40kbps baudrate

RAIL_ZWAVE_BAUD_100K 

100kbps baudrate

RAIL_ZWAVE_ENERGY_DETECT 

Energy detection phy.

Definition at line 242 of file rail_zwave.h.

◆ RAIL_ZWAVE_HomeId_t

enum RAIL_ZWAVE_HomeId_t

A Z-Wave Home Id.

Note
Home Id's in the range 0x54000000..0x55FFFFFF are illegal.
Enumerator
RAIL_ZWAVE_HOME_ID_UNKNOWN 

The unknown HomeId.

RAIL_ZWAVE_HOME_ID_DEFAULT 

An impossible and unlikely HomeId.

Definition at line 181 of file rail_zwave.h.

◆ RAIL_ZWAVE_HomeIdHash_t

enum RAIL_ZWAVE_HomeIdHash_t

A Z-Wave Home Id hash.

Note
Certain values (as shown) are illegal.
Enumerator
RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_1 

An illegal HomeIdHash value.

RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_2 

An illegal HomeIdHash value.

RAIL_ZWAVE_HOME_ID_HASH_ILLEGAL_3 

An illegal HomeIdHash value.

RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE 

Illegal HomeIdHash value that suppresses checking the HomeIdHash field of Beam packets.

RAIL_ZWAVE_HOME_ID_HASH_DEFAULT 

Default to don't care.

Definition at line 198 of file rail_zwave.h.

◆ RAIL_ZWAVE_NodeId_t

enum RAIL_ZWAVE_NodeId_t

A Z-Wave Node Id.

Note
Values 0xE9..0xFE are reserved.
Enumerator
RAIL_ZWAVE_NODE_ID_NONE 

The unknown NodeId for uninitialized nodes.

RAIL_ZWAVE_NODE_ID_BROADCAST 

The broadcast NodeId.

RAIL_ZWAVE_NODE_ID_DEFAULT 

Default to the broadcast NodeId.

Definition at line 160 of file rail_zwave.h.

◆ RAIL_ZWAVE_Options_t

enum RAIL_ZWAVE_Options_t

Z-Wave options.

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.

Definition at line 103 of file rail_zwave.h.

◆ RAIL_ZWAVE_RegionId_t

enum RAIL_ZWAVE_RegionId_t

Z-Wave region identifications.

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_COUNT 

Count of known regions, must be last.

Definition at line 260 of file rail_zwave.h.

Function Documentation

◆ RAIL_ZWAVE_ConfigBeamRx()

RAIL_Status_t RAIL_ZWAVE_ConfigBeamRx ( RAIL_Handle_t  railHandle,
RAIL_ZWAVE_BeamRxConfig_t *  config 
)

Configure the receive algorithm used in RAIL_ZWAVE_ReceiveBeam.

This function should not be used without direct instruction by Silicon Labs.

Parameters
[in]railHandleA RAIL instance handle.
[in]configConfiguration for beam detection algorithm.
Returns
Status code indicating success of the function call.

◆ 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.

Parameters
[in]railHandleA handle of RAIL instance.
[in]maskA bitmask containing which options should be modified.
[in]optionsA 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.

◆ RAIL_ZWAVE_ConfigRegion()

RAIL_Status_t RAIL_ZWAVE_ConfigRegion ( RAIL_Handle_t  railHandle,
const RAIL_ZWAVE_RegionConfig_t *  regionCfg 
)

Switch the Z-Wave region.

Parameters
[in]railHandleA handle of RAIL instance.
[in]regionCfgZ-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.

◆ RAIL_ZWAVE_Deinit()

RAIL_Status_t RAIL_ZWAVE_Deinit ( RAIL_Handle_t  railHandle)

De-initialize Z-Wave hardware acceleration.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
A 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.

◆ 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 targeted this node.

Parameters
[in]railHandleA handle of RAIL instance.
[out]pChannelIndexA 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 emplaced.
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.

◆ RAIL_ZWAVE_GetBeamNodeId()

RAIL_Status_t RAIL_ZWAVE_GetBeamNodeId ( RAIL_Handle_t  railHandle,
RAIL_ZWAVE_NodeId_t *  pNodeId 
)

Get the NodeId of the most recently seen Beam frame that targeted this node.

Parameters
[in]railHandleA handle of RAIL instance.
[out]pNodeIdA 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.

◆ 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).

Parameters
[in]railHandleA 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 the low power value same as the nominal power. Also, calling this function before configuring the PA (i.e., before a successful call to RAIL_ConfigTxPower) will return an error (RAIL_TX_POWER_LEVEL_INVALID).

◆ RAIL_ZWAVE_GetTxLowPowerDbm()

RAIL_TxPower_t RAIL_ZWAVE_GetTxLowPowerDbm ( RAIL_Handle_t  railHandle)

Get the TX low power in terms of deci-dBm instead of raw power level.

Parameters
[in]railHandleA RAIL instance handle.
Returns
The chip-specific RAIL_TxPower_t value of the low transmit power in deci-dBm.

◆ 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.

Parameters
[in]railHandleA handle of RAIL instance.
[in]configA Z-Wave configuration structure.
Returns
A status code indicating success of the function call.

This function is the entry point for working with Z-Wave within RAIL. It will set up relevant hardware acceleration for Z-Wave-specific features, such as HomeId 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.

◆ RAIL_ZWAVE_IsEnabled()

bool RAIL_ZWAVE_IsEnabled ( RAIL_Handle_t  railHandle)

Returns whether Z-Wave hardware acceleration is currently enabled.

Parameters
[in]railHandleA handle of RAIL instance.
Returns
True if Z-Wave hardware acceleration was enabled to start with and false otherwise.

◆ RAIL_ZWAVE_ReceiveBeam()

RAIL_Status_t RAIL_ZWAVE_ReceiveBeam ( RAIL_Handle_t  railHandle,
uint8_t *  beamDetectIndex,
const RAIL_SchedulerInfo_t *  schedulerInfo 
)

This function is used to implement beam detection and reception algorithms.

It will take 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 normal. However, normal packets may also be received during this time (thus 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, and that the radio can be turned off until the next time the user wants to listen for beams. Until one of these events are received, users should not try to attempt 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.
Parameters
[in]railHandleA RAIL instance handle.
[out]beamDetectIndexIndicator 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.
[out]schedulerInfoWhile Z-Wave is currently not supported in RAIL Multiprotocol, this scheduler info is added to future proof against any future version of multiprotocol which may support it. For now, this argument can be NULL.
Returns
status indicating whether or not the radio was able to configure beam packet detection/reception. Reasons for failure include an un-idled radio or a non Japan or Korea region configured before calling this function.

◆ RAIL_ZWAVE_SetHomeId()

RAIL_Status_t RAIL_ZWAVE_SetHomeId ( RAIL_Handle_t  railHandle,
RAIL_ZWAVE_HomeId_t  homeId,
RAIL_ZWAVE_HomeIdHash_t  homeIdHash 
)

Informs RAIL of the Z-Wave node's HomeId and its hash for receive filtering purposes.

Parameters
[in]railHandleA handle of RAIL instance.
[in]homeIdA Z-Wave Home Id.
[in]homeIdHashThe 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 HomeIdHash in a received Beam frame at all, and RAIL_EVENT_ZWAVE_BEAM will trigger based solely on the nodeId in the Beam frame.
Returns
Status code indicating success of the function call.
Note
Until this API is called, RAIL will assume the HomeId is an illegal one of RAIL_ZWAVE_HOME_ID_DEFAULT, and its hash is RAIL_ZWAVE_HOME_ID_HASH_DONT_CARE.

◆ 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 NodeId for receive filtering purposes.

Parameters
[in]railHandleA handle of RAIL instance.
[in]nodeIdA Z-Wave Node Id.
Returns
Status code indicating success of the function call.
Note
Until this API is called, RAIL will assume the NodeId is RAIL_ZWAVE_NODE_ID_DEFAULT.

◆ RAIL_ZWAVE_SetTxLowPower()

RAIL_Status_t RAIL_ZWAVE_SetTxLowPower ( RAIL_Handle_t  railHandle,
uint8_t  powerLevel 
)

Sets the Raw Low Power settings.

Parameters
[in]railHandleA handle of RAIL instance.
[in]powerLevelDesired 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.

◆ RAIL_ZWAVE_SetTxLowPowerDbm()

RAIL_Status_t RAIL_ZWAVE_SetTxLowPowerDbm ( RAIL_Handle_t  railHandle,
RAIL_TxPower_t  powerLevel 
)

Set the Low Power settings in dBm.

Parameters
[in]railHandleA handle of RAIL instance.
[in]powerLevelDesired low power level 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.