Z-Wave#

RAIL_ZWAVE_Options_t#

RAIL_ZWAVE_Options_t

Z-Wave options.

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.

RAIL_ZWAVE_HomeId_t#

RAIL_ZWAVE_HomeId_t

A Z-Wave Home ID.

Note

• Home IDs in the range 0x54000000..0x55FFFFFF are illegal.

RAIL_ZWAVE_HomeIdHash_t#

RAIL_ZWAVE_HomeIdHash_t

A Z-Wave Home ID hash.

Note

• Certain values (as shown) are illegal.

RAIL_ZWAVE_Baud_t#

RAIL_ZWAVE_Baud_t

Z-Wave supported baudrates or PHYs.

RAIL_ZWAVE_RegionId_t#

RAIL_ZWAVE_RegionId_t

Z-Wave region identifications.

RAIL_RxChannelHoppingParameters_t#

RAIL_RxChannelHoppingParameters_t [(4U)]

Rx channel hopping on-channel time for all Z-Wave channels in a region.

RAIL_ZWAVE_REGION_EU#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_EU

EU-European Union, RAIL_ZWAVE_REGION_EU.

RAIL_ZWAVE_REGION_US#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US

US-United States, RAIL_ZWAVE_REGION_US.

RAIL_ZWAVE_REGION_ANZ#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_ANZ

ANZ-Australia/New Zealand, RAIL_ZWAVE_REGION_ANZ.

RAIL_ZWAVE_REGION_HK#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_HK

HK-Hong Kong, RAIL_ZWAVE_REGION_HK.

RAIL_ZWAVE_REGION_MY#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_MY

MY-Malaysia, RAIL_ZWAVE_REGION_MY.

RAIL_ZWAVE_REGION_IN#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_IN

IN-India, RAIL_ZWAVE_REGION_IN.

RAIL_ZWAVE_REGION_JP#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_JP

JP-Japan, RAIL_ZWAVE_REGION_JP.

RAIL_ZWAVE_REGION_JPED#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_JPED

JP-Japan, RAIL_ZWAVE_REGION_JP.

RAIL_ZWAVE_REGION_RU#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_RU

RU-Russia, RAIL_ZWAVE_REGION_RU.

RAIL_ZWAVE_REGION_IL#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_IL

IL-Israel, RAIL_ZWAVE_REGION_IL.

RAIL_ZWAVE_REGION_KR#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_KR

KR-Korea, RAIL_ZWAVE_REGION_KR.

RAIL_ZWAVE_REGION_KRED#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_KRED

KR-Korea, RAIL_ZWAVE_REGION_KR.

RAIL_ZWAVE_REGION_CN#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_CN

CN-China, RAIL_ZWAVE_REGION_CN.

RAIL_ZWAVE_REGION_US_LR1#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US_LR1

US-Long Range 1, RAIL_ZWAVE_REGION_US_LR1.

RAIL_ZWAVE_REGION_US_LR2#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US_LR2

US-Long Range 2, RAIL_ZWAVE_REGION_US_LR2.

RAIL_ZWAVE_REGION_US_LR_END_DEVICE#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US_LR_END_DEVICE

US-Long Range End Device, RAIL_ZWAVE_REGION_US_LR_END_DEVICE.

RAIL_ZWAVE_REGION_INVALID#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_INVALID

Invalid Region.

RAIL_ZWAVE_ConfigRegion#

RAIL_Status_t RAIL_ZWAVE_ConfigRegion (RAIL_Handle_t railHandle, const RAIL_ZWAVE_RegionConfig_t *regionCfg)

Switch the Z-Wave 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_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.

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.

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.

Returns

• A 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 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_Deinit#

RAIL_Status_t RAIL_ZWAVE_Deinit (RAIL_Handle_t railHandle)

De-initialize Z-Wave hardware acceleration.

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_IsEnabled#

bool RAIL_ZWAVE_IsEnabled (RAIL_Handle_t railHandle)

Return whether Z-Wave hardware acceleration is currently enabled.

Returns

• True if Z-Wave hardware acceleration was enabled to start with and false otherwise.

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.

Returns

• Status code indicating success of the function call.

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.

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_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 HomeId and its hash for receive filtering.

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_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 triggered RAIL_EVENT_ZWAVE_BEAM.

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_GetBeamHomeIdHash#

RAIL_Status_t RAIL_ZWAVE_GetBeamHomeIdHash (RAIL_Handle_t railHandle, RAIL_ZWAVE_HomeIdHash_t *pBeamHomeIdHash)

Get the HomeIdHash of the most recently seen beam frame that triggered RAIL_EVENT_ZWAVE_BEAM.

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 HomeIdHash is provided.

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.

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

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:

RAIL_ZWAVE_GetBeamRssi#

RAIL_Status_t RAIL_ZWAVE_GetBeamRssi (RAIL_Handle_t railHandle, int8_t *pBeamRssi)

Get the RSSI of the received beam frame.

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.

RAIL_ZWAVE_SetTxLowPower#

RAIL_Status_t RAIL_ZWAVE_SetTxLowPower (RAIL_Handle_t railHandle, uint8_t powerLevel)

Set the Raw Low Power settings.

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.

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

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.

Returns

• The chip-specific RAIL_TxPower_t value of the low transmit power in deci-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.

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

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 non-Korea region configured before calling this function.

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.

Returns

• Status code indicating success of the function call.

RAIL_ZWAVE_SetDefaultRxBeamConfig#

RAIL_Status_t RAIL_ZWAVE_SetDefaultRxBeamConfig (RAIL_Handle_t railHandle)

Set the default RX beam configuration.

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.

RAIL_ZWAVE_GetRxBeamConfig#

RAIL_Status_t RAIL_ZWAVE_GetRxBeamConfig (RAIL_ZWAVE_BeamRxConfig_t *pConfig)

Get the current RX beam configuration.

Returns

• A status code indicating success of the function call.

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.

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

Returns

• Status code indicating success of the function call.

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.

RAIL_ZWAVE_GetRegion#

RAIL_ZWAVE_RegionId_t RAIL_ZWAVE_GetRegion (RAIL_Handle_t railHandle)

Get the Z-Wave region.

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.

RAIL_ZWAVE_SetLrAckData#

RAIL_Status_t RAIL_ZWAVE_SetLrAckData (RAIL_Handle_t railHandle, const RAIL_ZWAVE_LrAckData_t *pLrAckData)

Write the AutoACK FIFO for the next outgoing Z-Wave Long Range ACK.

Returns

• A status code indicating success of the function call.

This function sets the AutoACK data to use in acknowledging the frame being received. It must only be called while processing the 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.

RAIL_ZWAVE_OPTIONS_NONE#

#define RAIL_ZWAVE_OPTIONS_NONE

0U

A value representing no options.

RAIL_ZWAVE_OPTIONS_DEFAULT#

#define RAIL_ZWAVE_OPTIONS_DEFAULT

RAIL_ZWAVE_OPTIONS_NONE

All options are disabled by default.

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 non-beam packets regardless of their HomeId.

By default packets are filtered by their HomeId. When true, such filtering is disabled.

RAIL_ZWAVE_OPTION_NODE_ID_FILTERING#

#define RAIL_ZWAVE_OPTION_NODE_ID_FILTERING

(1u << RAIL_ZWAVE_OPTION_NODE_ID_FILTERING_SHIFT)

An option to filter non-beam packets based on their NodeId when RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE is disabled.

Note

• This option has no effect when RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE is enabled.

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.

By default beams are not considered special and will be received as if they were normal Z-Wave frames, assuredly triggering RAIL_EVENT_RX_FRAME_ERROR. When true, beam frames that are broadcast or match the NodeId and HomeIdHash values will trigger RAIL_EVENT_ZWAVE_BEAM event. (All beams additionally trigger RAIL_EVENT_RX_PACKET_ABORTED regardless of NodeId / HomeIdHash values.)

Note

• This option takes precedence over RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE when receiving a beam frame. For promiscuous beam handling see related RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE option.

RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE#

#define RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE

(1u << RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE_SHIFT)

An option to receive all beams promiscuously when RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES is enabled.

When true, beam frames are received regardless of their NodeId or HomeIdHash resulting in RAIL_EVENT_ZWAVE_BEAM (and also RAIL_EVENT_RX_PACKET_ABORTED) for each beam frame.

Note

• This option has no effect when RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES is disabled.

RAIL_ZWAVE_OPTIONS_ALL#

#define RAIL_ZWAVE_OPTIONS_ALL

0xFFFFFFFFU

A value representing all options.

RAIL_ZWAVE_FREQ_INVALID#

#define RAIL_ZWAVE_FREQ_INVALID

0xFFFFFFFFUL

Sentinel value to indicate that a channel (and thus its frequency) are invalid.

RAIL_ZWAVE_LR_BEAM_TX_POWER_INVALID#

#define RAIL_ZWAVE_LR_BEAM_TX_POWER_INVALID

(0xFFU)

Invalid beam TX power value returned when RAIL_ZWAVE_GetLrBeamTxPower is called after receiving a regular non-long-range beam.

RAIL_NUM_ZWAVE_CHANNELS#

#define RAIL_NUM_ZWAVE_CHANNELS

(4U)

Number of channels in each of Z-Wave's region-based PHYs.