Z-Wave
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_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.
|
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 , 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 } |
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.
|
|
RAIL_Status_t | RAIL_ZWAVE_SetTxLowPower ( RAIL_Handle_t railHandle, uint8_t powerLevel) |
Set 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) |
Gets 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) |
Gets the TX low power in terms of deci-dBm instead of raw power level.
|
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.
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
126
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
111
of file
rail_zwave.h
.
#define RAIL_ZWAVE_OPTIONS_DEFAULT RAIL_ZWAVE_OPTIONS_NONE |
All options are disabled by default.
Definition at line
104
of file
rail_zwave.h
.
Enumeration Type Documentation
enum RAIL_ZWAVE_Baud_t |
enum RAIL_ZWAVE_HomeId_t |
A Z-Wave Home Id hash.
- Note
- Certain values (as shown) are illegal.
Definition at line
182
of file
rail_zwave.h
.
enum RAIL_ZWAVE_NodeId_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
87
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.
- 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_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_TxPowerLevel_t RAIL_ZWAVE_GetTxLowPower | ( | RAIL_Handle_t |
railHandle
|
) |
Gets 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).
RAIL_TxPower_t RAIL_ZWAVE_GetTxLowPowerDbm | ( | RAIL_Handle_t |
railHandle
|
) |
Gets 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.
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 .
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.
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.