Z-Wave configuration routines.

Data Structures
struct	RAIL_ZWAVE_Config_t
	A configuration structure for Z-Wave in RAIL.

struct	RAIL_ZWAVE_ChannelConfig_t
	A configuration structure for Z-Wave channels.

Macros
#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_OPTIONS_ALL 0xFFFFFFFFU
	A value representing all options.

Typedefs
typedef RAIL_ZWAVE_ChannelConfig_t	RAIL_ZWAVE_RegionConfig_t [3]
	Each Z-Wave region supports 3 channels.

Enumerations
enum	RAIL_ZWAVE_Options_t { RAIL_ZWAVE_OPTION_PROMISCUOUS_MODE_SHIFT = 0, RAIL_ZWAVE_OPTION_DETECT_BEAM_FRAMES_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 }
	Z-Wave supported baudrates.

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)
	Initializes RAIL for Z-Wave features.

RAIL_Status_t	RAIL_ZWAVE_Deinit ( RAIL_Handle_t railHandle)
	De-initializes 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)
	Configures Z-Wave options.

RAIL_Status_t	RAIL_ZWAVE_SetNodeId ( RAIL_Handle_t railHandle, RAIL_ZWAVE_NodeId_t nodeId)
	Informs 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)
	Gets 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)
	Gets the channel hopping index of the most recently seen Beam frame that targeted this node.

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_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_CN
	CN-China", RAIL_ZWAVE_REGION_CN.

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

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

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

#define RAIL_ZWAVE_OPTIONS_DEFAULT RAIL_ZWAVE_OPTIONS_NONE

All options are disabled by default.

Definition at line 101 of file rail_zwave.h .

Enumeration Type Documentation

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

Definition at line 206 of file rail_zwave.h .

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

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

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

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.

Definition at line 86 of file rail_zwave.h .

Function Documentation

RAIL_Status_t RAIL_ZWAVE_ConfigOptions	(	RAIL_Handle_t	`railHandle,`
		RAIL_ZWAVE_Options_t	`mask,`
		RAIL_ZWAVE_Options_t	`options`
	)

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

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.

RAIL_Status_t RAIL_ZWAVE_Deinit ( RAIL_Handle_t railHandle )

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

RAIL_Status_t RAIL_ZWAVE_GetBeamChannelIndex	(	RAIL_Handle_t	`railHandle,`
		uint8_t *	`pChannelIndex`
	)

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

RAIL_Status_t RAIL_ZWAVE_GetBeamNodeId	(	RAIL_Handle_t	`railHandle,`
		RAIL_ZWAVE_NodeId_t *	`pNodeId`
	)

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

RAIL_Status_t RAIL_ZWAVE_Init	(	RAIL_Handle_t	`railHandle,`
		const RAIL_ZWAVE_Config_t *	`config`
	)

Initializes 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 ZWave within RAIL. It will set up relevant hardware acceleration for Z-Wave specific features like HomeId filtering and beam packets (as specified in the config) and allows users to select the relevant Z-Wave region-specific phy via RAIL_ZWAVE_ConfigRegion .

bool RAIL_ZWAVE_IsEnabled ( RAIL_Handle_t railHandle )

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

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

RAIL_Status_t RAIL_ZWAVE_SetNodeId	(	RAIL_Handle_t	`railHandle,`
		RAIL_ZWAVE_NodeId_t	`nodeId`
	)

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

Z-Wave RAIL API > Protocol-specific

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

Z-Wave
RAIL API > Protocol-specific