Z-Wave

RAIL API > Protocol-specific

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 138 of file rail_zwave.h.

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 123 of file rail_zwave.h.

All options are disabled by default.

Definition at line 116 of file rail_zwave.h.

Z-Wave supported baudrates or PHYs.

Definition at line 257 of file rail_zwave.h.

A Z-Wave Home ID.

Note

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

Definition at line 196 of file rail_zwave.h.

A Z-Wave Home Id hash.

Note

Certain values (as shown) are illegal.

Definition at line 213 of file rail_zwave.h.

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.

Definition at line 160 of file rail_zwave.h.

Z-Wave options.

Definition at line 99 of file rail_zwave.h.

Z-Wave region identifications.

Definition at line 286 of file rail_zwave.h.

Configure the receive algorithm used in RAIL_ZWAVE_ReceiveBeam.

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

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	config	Configuration for beam detection algorithm.

Returns

Status code indicating success of the function call.

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.

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.

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.

Parameters

[in]	railHandle	A RAIL instance handle.
[in,out]	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.

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.

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.

Get the channel hopping index of the most recently seen Beam frame that targeted this node.

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

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

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.

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.

Get the TX power used to transmit the long range beam frame.

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:

Get the Z-Wave region.

Parameters

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

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.

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

Parameters

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

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.

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

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.

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 at which point the radio will be automatically idled. 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]	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.

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.

Set the default Rx beam configuration.

Parameters

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

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

Parameters

[in]	railHandle	A handle of RAIL instance.
[in]	homeId	A Z-Wave Home Id.
[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 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.

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.

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

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

Until this API is called, RAIL will assume the NodeId is RAIL_ZWAVE_NODE_ID_DEFAULT.

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.

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.