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

Modules#

RAIL_ZWAVE_Config_t

RAIL_ZWAVE_LrAckData_t

RAIL_ZWAVE_BeamRxConfig_t

RAIL_ZWAVE_RegionConfig_t

RAIL_ZWAVE_IrcalVal_t

Enumerations#

enum
RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE_SHIFT = 0
RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES_SHIFT
RAIL_ZWAVE_OPTION_NODE_ID_FILTERING_SHIFT
RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE_SHIFT
}

Z-Wave options.

enum
RAIL_ZWAVE_NODE_ID_NONE = 0x00U
RAIL_ZWAVE_NODE_ID_BROADCAST = 0xFFU
RAIL_ZWAVE_NODE_ID_DEFAULT = RAIL_ZWAVE_NODE_ID_BROADCAST
RAIL_ZWAVE_NODE_ID_BROADCAST_LONGRANGE = 0xFFFU
RAIL_ZWAVE_NODE_ID_DEFAULT_LONGRANGE = RAIL_ZWAVE_NODE_ID_BROADCAST_LONGRANGE
}

A Z-Wave Node ID.

enum
RAIL_ZWAVE_HOME_ID_UNKNOWN = 0x00000000U
RAIL_ZWAVE_HOME_ID_DEFAULT = 0x54545454U
}

A Z-Wave Home ID.

enum
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_9600
RAIL_ZWAVE_BAUD_40K
RAIL_ZWAVE_BAUD_100K
RAIL_ZWAVE_LR
RAIL_ZWAVE_ENERGY_DETECT = RAIL_ZWAVE_LR
RAIL_ZWAVE_BAUD_INVALID
}

Z-Wave supported baudrates or PHYs.

enum
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_US_LR1
RAIL_ZWAVE_REGIONID_US_LR2
RAIL_ZWAVE_REGIONID_US_LR_END_DEVICE
RAIL_ZWAVE_REGIONID_COUNT
}

Z-Wave region identifications.

Typedefs#

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

Variables#

EU-European Union, RAIL_ZWAVE_REGION_EU.

US-United States, RAIL_ZWAVE_REGION_US.

ANZ-Australia/New Zealand, RAIL_ZWAVE_REGION_ANZ.

HK-Hong Kong, RAIL_ZWAVE_REGION_HK.

MY-Malaysia, RAIL_ZWAVE_REGION_MY.

IN-India, RAIL_ZWAVE_REGION_IN.

JP-Japan, RAIL_ZWAVE_REGION_JP.

JP-Japan, RAIL_ZWAVE_REGION_JP.

RU-Russia, RAIL_ZWAVE_REGION_RU.

IL-Israel, RAIL_ZWAVE_REGION_IL.

KR-Korea, RAIL_ZWAVE_REGION_KR.

KR-Korea, RAIL_ZWAVE_REGION_KR.

CN-China, RAIL_ZWAVE_REGION_CN.

US-Long Range 1, RAIL_ZWAVE_REGION_US_LR1.

US-Long Range 2, RAIL_ZWAVE_REGION_US_LR2.

US-Long Range End Device, RAIL_ZWAVE_REGION_US_LR_END_DEVICE.

Functions#

RAIL_ZWAVE_ConfigRegion(RAIL_Handle_t railHandle, const RAIL_ZWAVE_RegionConfig_t *regionCfg)

Switch the Z-Wave region.

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.

RAIL_ZWAVE_Init(RAIL_Handle_t railHandle, const RAIL_ZWAVE_Config_t *config)

Initialize RAIL for Z-Wave features.

RAIL_ZWAVE_Deinit(RAIL_Handle_t railHandle)

De-initialize Z-Wave hardware acceleration.

bool
RAIL_ZWAVE_IsEnabled(RAIL_Handle_t railHandle)

Return whether Z-Wave hardware acceleration is currently enabled.

RAIL_ZWAVE_ConfigOptions(RAIL_Handle_t railHandle, RAIL_ZWAVE_Options_t mask, RAIL_ZWAVE_Options_t options)

Configure Z-Wave options.

RAIL_ZWAVE_SetNodeId(RAIL_Handle_t railHandle, RAIL_ZWAVE_NodeId_t nodeId)

Inform RAIL of the Z-Wave node's NodeId for receive filtering.

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.

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.

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.

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.

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.

RAIL_ZWAVE_GetBeamRssi(RAIL_Handle_t railHandle, int8_t *pBeamRssi)

Get the RSSI of the received beam frame.

RAIL_ZWAVE_SetTxLowPower(RAIL_Handle_t railHandle, uint8_t powerLevel)

Set the Raw Low Power settings.

RAIL_ZWAVE_SetTxLowPowerDbm(RAIL_Handle_t railHandle, RAIL_TxPower_t powerLevel)

Set the Low Power settings in dBm.

RAIL_ZWAVE_GetTxLowPower(RAIL_Handle_t railHandle)

Get the TX low power in raw units (see rail_chip_specific.h for value ranges).

RAIL_ZWAVE_GetTxLowPowerDbm(RAIL_Handle_t railHandle)

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

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

Implement beam detection and reception algorithms.

RAIL_ZWAVE_ConfigBeamRx(RAIL_Handle_t railHandle, RAIL_ZWAVE_BeamRxConfig_t *config)

Configure the receive algorithm used in RAIL_ZWAVE_ReceiveBeam.

RAIL_ZWAVE_SetDefaultRxBeamConfig(RAIL_Handle_t railHandle)

Set the default RX beam configuration.

RAIL_ZWAVE_GetRxBeamConfig(RAIL_ZWAVE_BeamRxConfig_t *pConfig)

Get the current RX beam configuration.

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.

RAIL_ZWAVE_GetRegion(RAIL_Handle_t railHandle)

Get the Z-Wave region.

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.

Macros#

#define

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

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

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

#define

A value representing all options.

#define

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

#define

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

#define

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.

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.


Definition at line 99 of file protocol/zwave/rail_zwave.h

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.

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.

RAIL_ZWAVE_NODE_ID_BROADCAST_LONGRANGE

The Long Range broadcast NodeId.

RAIL_ZWAVE_NODE_ID_DEFAULT_LONGRANGE

Default to the Long Range broadcast NodeId.


Definition at line 181 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_HomeId_t#

RAIL_ZWAVE_HomeId_t

A Z-Wave Home ID.

Note

  • Home IDs 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 217 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_HomeIdHash_t#

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 234 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_Baud_t#

RAIL_ZWAVE_Baud_t

Z-Wave supported baudrates or PHYs.

Enumerator
RAIL_ZWAVE_BAUD_9600

9.6kbps baudrate

RAIL_ZWAVE_BAUD_40K

40kbps baudrate

RAIL_ZWAVE_BAUD_100K

100kbps baudrate

RAIL_ZWAVE_LR

Long Range PHY.

RAIL_ZWAVE_ENERGY_DETECT

Energy detection PHY.

RAIL_ZWAVE_BAUD_INVALID

Sentinel value for invalid baud rate.


Definition at line 278 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_RegionId_t#

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

United States long range end device PHY for both LR frequencies.

RAIL_ZWAVE_REGIONID_COUNT

Count of known regions, must be last.


Definition at line 336 of file protocol/zwave/rail_zwave.h

Typedef Documentation#

RAIL_RxChannelHoppingParameters_t#

RAIL_RxChannelHoppingParameters_t [(4U)]

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


Definition at line 458 of file protocol/zwave/rail_zwave.h

Variable Documentation#

RAIL_ZWAVE_REGION_EU#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_EU

EU-European Union, RAIL_ZWAVE_REGION_EU.


Definition at line 878 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_US#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US

US-United States, RAIL_ZWAVE_REGION_US.


Definition at line 881 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_ANZ#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_ANZ

ANZ-Australia/New Zealand, RAIL_ZWAVE_REGION_ANZ.


Definition at line 884 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_HK#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_HK

HK-Hong Kong, RAIL_ZWAVE_REGION_HK.


Definition at line 887 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_MY#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_MY

MY-Malaysia, RAIL_ZWAVE_REGION_MY.


Definition at line 890 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_IN#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_IN

IN-India, RAIL_ZWAVE_REGION_IN.


Definition at line 893 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_JP#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_JP

JP-Japan, RAIL_ZWAVE_REGION_JP.


Definition at line 896 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_JPED#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_JPED

JP-Japan, RAIL_ZWAVE_REGION_JP.


Definition at line 899 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_RU#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_RU

RU-Russia, RAIL_ZWAVE_REGION_RU.


Definition at line 902 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_IL#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_IL

IL-Israel, RAIL_ZWAVE_REGION_IL.


Definition at line 905 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_KR#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_KR

KR-Korea, RAIL_ZWAVE_REGION_KR.


Definition at line 908 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_KRED#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_KRED

KR-Korea, RAIL_ZWAVE_REGION_KR.


Definition at line 911 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_CN#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_CN

CN-China, RAIL_ZWAVE_REGION_CN.


Definition at line 914 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_US_LR1#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US_LR1

US-Long Range 1, RAIL_ZWAVE_REGION_US_LR1.


Definition at line 917 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_US_LR2#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_US_LR2

US-Long Range 2, RAIL_ZWAVE_REGION_US_LR2.


Definition at line 920 of file protocol/zwave/rail_zwave.h

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.


Definition at line 923 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_REGION_INVALID#

const RAIL_ZWAVE_RegionConfig_t RAIL_ZWAVE_REGION_INVALID

Invalid Region.


Definition at line 926 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

[in]regionCfg

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.


Definition at line 472 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

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

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


Definition at line 494 of file protocol/zwave/rail_zwave.h

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]railHandle

A handle of RAIL instance.

[in]config

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


Definition at line 510 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_Deinit#

RAIL_Status_t RAIL_ZWAVE_Deinit (RAIL_Handle_t railHandle)

De-initialize Z-Wave hardware acceleration.

Parameters
[in]railHandle

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


Definition at line 522 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_IsEnabled#

bool RAIL_ZWAVE_IsEnabled (RAIL_Handle_t railHandle)

Return whether Z-Wave hardware acceleration is currently enabled.

Parameters
[in]railHandle

A handle of RAIL instance.

Returns

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


Definition at line 531 of file protocol/zwave/rail_zwave.h

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]railHandle

A handle of RAIL instance.

[in]mask

A bitmask containing which options should be modified.

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


Definition at line 542 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

[in]nodeId

A Z-Wave Node ID.

Returns

  • Status code indicating success of the function call.

Note


Definition at line 556 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

[in]homeId

A Z-Wave HomeId.

[in]homeIdHash

The hash of the HomeId 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


Definition at line 575 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

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


Definition at line 591 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

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


Definition at line 606 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

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


Definition at line 624 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

[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

-6dBm

1

-2dBm

2

+2dBm

3

+6dBm

4

+10dBm

5

+13dBm

6

+16dBm

7

+19dBm

8

+21dBm

9

+23Bm

10

+25dBm

11

+26dBm

12

+27dBm

13

+28dBm

14

+29dBm

15

+30dBm


Definition at line 667 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_GetBeamRssi#

RAIL_Status_t RAIL_ZWAVE_GetBeamRssi (RAIL_Handle_t railHandle, int8_t * pBeamRssi)

Get the RSSI of the received beam frame.

Parameters
[in]railHandle

A handle of RAIL instance.

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


Definition at line 684 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_SetTxLowPower#

RAIL_Status_t RAIL_ZWAVE_SetTxLowPower (RAIL_Handle_t railHandle, uint8_t powerLevel)

Set the Raw Low Power settings.

Parameters
[in]railHandle

A handle of RAIL instance.

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


Definition at line 699 of file protocol/zwave/rail_zwave.h

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]railHandle

A handle of RAIL instance.

[in]powerLevel

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


Definition at line 714 of file protocol/zwave/rail_zwave.h

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]railHandle

A RAIL instance handle.

Returns

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


Definition at line 736 of file protocol/zwave/rail_zwave.h

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]railHandle

A RAIL instance handle.

Returns

  • The chip-specific RAIL_TxPower_t value of the low transmit power in deci-dBm.


Definition at line 745 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[out]beamDetectIndex

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.

[out]schedulerInfo

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

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

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.


Definition at line 790 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

Configuration for beam detection algorithm.

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

Returns

  • Status code indicating success of the function call.


Definition at line 802 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_SetDefaultRxBeamConfig#

RAIL_Status_t RAIL_ZWAVE_SetDefaultRxBeamConfig (RAIL_Handle_t railHandle)

Set the default RX beam configuration.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call.

Note


Definition at line 814 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_GetRxBeamConfig#

RAIL_Status_t RAIL_ZWAVE_GetRxBeamConfig (RAIL_ZWAVE_BeamRxConfig_t * pConfig)

Get the current RX beam configuration.

Parameters
[out]pConfig

A pointer to RAIL_ZWAVE_BeamRxConfig_t to be populated with the current beam configuration.

Returns

  • A status code indicating success of the function call.


Definition at line 823 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]config

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.

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.


Definition at line 843 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_GetRegion#

RAIL_ZWAVE_RegionId_t RAIL_ZWAVE_GetRegion (RAIL_Handle_t railHandle)

Get the Z-Wave region.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

Note


Definition at line 855 of file protocol/zwave/rail_zwave.h

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.

Parameters
[in]railHandle

A handle of RAIL instance.

[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

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


Definition at line 874 of file protocol/zwave/rail_zwave.h

Macro Definition Documentation#

RAIL_ZWAVE_OPTIONS_NONE#

#define RAIL_ZWAVE_OPTIONS_NONE
Value:
0U

A value representing no options.


Definition at line 115 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_OPTIONS_DEFAULT#

#define RAIL_ZWAVE_OPTIONS_DEFAULT
Value:
RAIL_ZWAVE_OPTIONS_NONE

All options are disabled by default.


Definition at line 118 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE#

#define RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE
Value:
  (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.


Definition at line 125 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_OPTION_NODE_ID_FILTERING#

#define RAIL_ZWAVE_OPTION_NODE_ID_FILTERING
Value:
  (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


Definition at line 135 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES#

#define RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES
Value:
  (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


Definition at line 152 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE#

#define RAIL_ZWAVE_OPTION_PROMISCUOUS_BEAM_MODE
Value:
  (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


Definition at line 165 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_OPTIONS_ALL#

#define RAIL_ZWAVE_OPTIONS_ALL
Value:
0xFFFFFFFFU

A value representing all options.


Definition at line 169 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_FREQ_INVALID#

#define RAIL_ZWAVE_FREQ_INVALID
Value:
0xFFFFFFFFUL

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


Definition at line 320 of file protocol/zwave/rail_zwave.h

RAIL_ZWAVE_LR_BEAM_TX_POWER_INVALID#

#define RAIL_ZWAVE_LR_BEAM_TX_POWER_INVALID
Value:
(0xFFU)

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


Definition at line 393 of file protocol/zwave/rail_zwave.h

RAIL_NUM_ZWAVE_CHANNELS#

#define RAIL_NUM_ZWAVE_CHANNELS
Value:
(4U)

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


Definition at line 429 of file protocol/zwave/rail_zwave.h