Zpal-radio

Defines a platform abstraction layer for the Z-Wave radio. More...

Collaboration diagram for Zpal-radio:

Topics
	Number of Channels

Data Structures
struct	zpal_radio_transmit_parameter_t
	Parameters required when transmitting a frame. More...
struct	zpal_radio_rx_parameters_t
	Structure with radio parameters for a received frame. More...
struct	zpal_radio_receive_frame_t
	Z-Wave receive frame. More...
struct	zpal_radio_network_stats_t
	Network statistics structure. More...
struct	zpal_radio_rf_channel_statistic_t
	rf channel statistics structure More...
struct	zpal_radio_profile_t
	Radio Profile containing region, baud rate, and wakeup interval for this device. More...

Macros
#define	ZPAL_RADIO_INVALID_RSSI_DBM   (-128)
	The RSSI value is invalid.
#define	ZPAL_RADIO_RSSI_NOT_AVAILABLE   (127)
	The RSSI value is not available, probably because it has not been measured yet.
#define	ZW_TX_POWER_10DBM   100
	10 dBm transmit power definition.
#define	ZW_TX_POWER_14DBM   140
	14 dBm transmit power definition.
#define	ZW_TX_POWER_20DBM   200
	20 dBm transmit power definition.
#define	REGION_2CH_NUM   = (REGION_2CH_END - REGION_2CH_FIRST)
	Number of 2 channel regions.
#define	REGION_3CH_NUM   = (REGION_3CH_END - REGION_3CH_FIRST)
	Number of 3 channel regions.

Typedefs
typedef uint16_t	node_id_t
	Node ID type.
typedef int16_t	zpal_tx_power_t
	Parameter type to store deci dBm values.
typedef void(*	zpal_radio_callback_t) (zpal_radio_event_t event)
	Callback type used for radio events.
typedef void(*	zpal_radio_receive_handler_t) (zpal_radio_rx_parameters_t *rx_parameters, zpal_radio_receive_frame_t *frame)
	Function pointer declaration for handling of received frames.

Enumerations
enum	zpal_radio_mode_t {   ZPAL_RADIO_MODE_NON_LISTENING ,   ZPAL_RADIO_MODE_ALWAYS_LISTENING ,   ZPAL_RADIO_MODE_FLIRS }
	Defines the different radio modes supported by Z-Wave. More...
enum	zpal_radio_wakeup_t {   ZPAL_RADIO_WAKEUP_NEVER_LISTEN ,   ZPAL_RADIO_WAKEUP_ALWAYS_LISTEN ,   ZPAL_RADIO_WAKEUP_EVERY_250ms ,   ZPAL_RADIO_WAKEUP_EVERY_1000ms }
	Wakeup interval for the radio. A FLiRS node will use 250 or 1000 ms interval, all other nodes should be configured as always listening. More...
enum	zpal_radio_crc_t {   ZPAL_RADIO_CRC_NONE ,   ZPAL_RADIO_CRC_8_BIT_XOR ,   ZPAL_RADIO_CRC_16_BIT_CCITT }
	Enumeration containing supported checksum types in Z-Wave. More...
enum	zpal_radio_speed_t {   ZPAL_RADIO_SPEED_UNDEFINED ,   ZPAL_RADIO_SPEED_9600 ,   ZPAL_RADIO_SPEED_40K ,   ZPAL_RADIO_SPEED_100K ,   ZPAL_RADIO_SPEED_100KLR }
	Enumeration containing supported baud rates. More...
enum	zpal_radio_lr_channel_t {   ZPAL_RADIO_LR_CHANNEL_UNINITIALIZED ,   ZPAL_RADIO_LR_CHANNEL_A ,   ZPAL_RADIO_LR_CHANNEL_B ,   ZPAL_RADIO_LR_CHANNEL_UNKNOWN ,   ZPAL_RADIO_LR_CHANNEL_AUTO = 255 }
	Enumeration containing Long Range Channels. More...
enum	zpal_radio_zwave_channel_t {   ZPAL_RADIO_ZWAVE_CHANNEL_0 = 0 ,   ZPAL_RADIO_ZWAVE_CHANNEL_1 = 1 ,   ZPAL_RADIO_ZWAVE_CHANNEL_2 = 2 ,   ZPAL_RADIO_ZWAVE_CHANNEL_3 = 3 ,   ZPAL_RADIO_ZWAVE_CHANNEL_4 = 4 ,   ZPAL_RADIO_ZWAVE_CHANNEL_UNKNOWN = 0xFF }
	Enumeration containing Z-Wave channels. More...
enum	zpal_radio_protocol_mode_t {   ZPAL_RADIO_PROTOCOL_MODE_1 ,   ZPAL_RADIO_PROTOCOL_MODE_2 ,   ZPAL_RADIO_PROTOCOL_MODE_3 ,   ZPAL_RADIO_PROTOCOL_MODE_4 ,   ZPAL_RADIO_PROTOCOL_MODE_UNDEFINED = 0xFF }
	Enumeration containing Z-Wave channels known as protocol modes. More...
enum	zpal_radio_lr_channel_config_t {   ZPAL_RADIO_LR_CH_CFG_NO_LR ,   ZPAL_RADIO_LR_CH_CFG1 ,   ZPAL_RADIO_LR_CH_CFG2 ,   ZPAL_RADIO_LR_CH_CFG3 ,   ZPAL_RADIO_LR_CH_CFG_COUNT }
	List of LR channel configurations. Used to select the correct phy configuration. More...
enum	zpal_radio_region_t {   REGION_2CH_FIRST = 0 ,   REGION_EU = REGION_2CH_FIRST ,   REGION_US ,   REGION_ANZ ,   REGION_HK ,   REGION_DEPRECATED_4 ,   REGION_IN = 5 ,   REGION_IL ,   REGION_RU ,   REGION_CN ,   REGION_US_LR ,   REGION_DEPRECATED_10 ,   REGION_EU_LR ,   REGION_2CH_END ,   REGION_3CH_FIRST = 32 ,   REGION_JP = REGION_3CH_FIRST ,   REGION_KR ,   REGION_3CH_END ,   REGION_DEPRECATED_48 = 48 ,   REGION_UNDEFINED = 0xFE ,   REGION_DEFAULT = 0xFF }
	Enumeration official Z-Wave regions. More...
enum	zpal_radio_tx_power_t {   ZPAL_RADIO_TX_POWER_DEFAULT ,   ZPAL_RADIO_TX_POWER_MINUS1_DBM ,   ZPAL_RADIO_TX_POWER_MINUS2_DBM ,   ZPAL_RADIO_TX_POWER_MINUS3_DBM ,   ZPAL_RADIO_TX_POWER_MINUS4_DBM ,   ZPAL_RADIO_TX_POWER_MINUS5_DBM ,   ZPAL_RADIO_TX_POWER_MINUS6_DBM ,   ZPAL_RADIO_TX_POWER_MINUS7_DBM ,   ZPAL_RADIO_TX_POWER_MINUS8_DBM ,   ZPAL_RADIO_TX_POWER_MINUS9_DBM ,   ZPAL_RADIO_TX_POWER_UNINITIALIZED = 126 ,   ZPAL_RADIO_TX_POWER_REDUCED = 127 }
	Enumeration containing Tx power settings. More...
enum	zpal_radio_header_type_t {   ZPAL_RADIO_HEADER_TYPE_2CH ,   ZPAL_RADIO_HEADER_TYPE_3CH ,   ZPAL_RADIO_HEADER_TYPE_LR ,   ZPAL_RADIO_HEADER_TYPE_UNDEFINED }
	Z-Wave Frame header format types. More...
enum	zpal_radio_event_t {   ZPAL_RADIO_EVENT_NONE ,   ZPAL_RADIO_EVENT_RX_COMPLETE ,   ZPAL_RADIO_EVENT_TX_COMPLETE ,   ZPAL_RADIO_EVENT_RX_BEAM_COMPLETE ,   ZPAL_RADIO_EVENT_TX_BEAM_COMPLETE ,   ZPAL_RADIO_EVENT_RX_ABORT ,   ZPAL_RADIO_EVENT_TX_FAIL ,   ZPAL_RADIO_EVENT_TX_FAIL_LBT ,   ZPAL_RADIO_EVENT_RXTX_CALIBRATE ,   ZPAL_RADIO_EVENT_MASK = 0x1F ,   ZPAL_RADIO_EVENT_FLAG_SUCCESS = 0x80 ,   ZPAL_RADIO_EVENT_TX_TIMEOUT = 254 ,   ZPAL_RADIO_EVENT_RX_TIMEOUT = 255 }
	Enumeratio radio events. More...
enum	zpal_radio_status_t {   ZPAL_RADIO_STATUS_IDLE ,   ZPAL_RADIO_STATUS_RX ,   ZPAL_RADIO_STATUS_TX ,   ZPAL_RADIO_STATUS_TX_BEAM ,   ZPAL_RADIO_STATUS_RX_BEAM }
	Radio status. More...

Functions
void	zpal_radio_set_network_ids (uint32_t home_id, node_id_t node_id, zpal_radio_mode_t mode, uint8_t home_id_hash)
	Sets the home ID, the node ID and the radio mode.
void	zpal_radio_init (zpal_radio_profile_t *const profile)
	Initializes the radio.
zpal_status_t	zpal_radio_change_region (zpal_radio_region_t eRegion, zpal_radio_lr_channel_config_t eLrChCfg)
	Function used to change region and Long Range mode at the same time.
zpal_radio_region_t	zpal_radio_get_region (void)
	Function for getting REGION runtime.
zpal_status_t	zpal_radio_transmit (zpal_radio_transmit_parameter_t const *const tx_parameters, uint8_t frame_header_length, uint8_t const *const frame_header_buffer, uint8_t frame_payload_length, uint8_t const *const frame_payload_buffer, uint8_t use_lbt, int8_t tx_power)
	Function for transmitting a Z-Wave frame though the radio.
zpal_status_t	zpal_radio_transmit_beam (zpal_radio_transmit_parameter_t const *const tx_parameters, uint8_t beam_data_len, uint8_t const *const beam_data, int8_t tx_power)
	Function for transmitting a Z-Wave Beam frame though the radio.
void	zpal_radio_start_receive ()
	Starts the receiver and enables reception of frames.
void	zpal_radio_get_last_received_frame (void)
	Function to get last received frame. If a frame is received, zpal_radio_receive_handler_t will be invoked.
void	zpal_radio_power_down (void)
	Powers down the radio transceiver.
zpal_radio_protocol_mode_t	zpal_radio_get_protocol_mode (void)
	Function to get the protocol mode used in the configured region.
zpal_radio_zwave_channel_t	zpal_radio_get_last_beam_channel (void)
	Get last beam channel. Retrieve the channel on which we have last received a beam on.
int8_t	zpal_radio_get_last_beam_rssi (void)
	Get last beam RSSI. Retrieve the RSSI of the last beam received.
void	zpal_radio_set_lbt_level (uint8_t channel, int8_t level)
	Function for setting the LBT RSSI level.
void	zpal_radio_enable_rx_broadcast_beam (bool enable)
	Enable or disables reception of broadcast beam. Enable or disable FLiRS broadcast address.
void	zpal_radio_clear_tx_timers (void)
	Function for clearing current Channel Transmit timers.
void	zpal_radio_clear_network_stats (void)
	Function for clearing current Network statistics.
void	zpal_radio_rf_channel_statistic_clear (zpal_radio_zwave_channel_t zwavechannel)
	Function for clearing specified rf channel statistics.
bool	zpal_radio_rf_channel_statistic_get (zpal_radio_zwave_channel_t zwavechannel, zpal_radio_rf_channel_statistic_t *p_radio_channel_statistic)
void	zpal_radio_rf_channel_statistic_tx_channel_set (zpal_radio_zwave_channel_t zwavechannel)
	Function for setting the zwavechannel used when calling zpal_radio_rf_channel_statistic_tx_frames, zpal_radio_rf_channel_statistic_tx_retries and zpal_radio_rf_channel_statistic_tx_lbt_failures.
void	zpal_radio_rf_channel_statistic_tx_frames (void)
	Function for incrementing the rf channel tx frame statistic.
void	zpal_radio_rf_channel_statistic_tx_retries (void)
	Function for incrementing the rf channel tx retries statistic.
void	zpal_radio_rf_channel_statistic_tx_lbt_failures (void)
	Function for incrementing the rf channel tx lbt failures.
void	zpal_radio_rf_channel_statistic_background_rssi_average_update (zpal_radio_zwave_channel_t zwavechannel, int8_t rssi)
	Function for updating the rf channel background noise rssi average statistic.
void	zpal_radio_rf_channel_statistic_end_device_rssi_average_update (zpal_radio_zwave_channel_t zwavechannel, int8_t rssi)
	Function for updating the rf channel end device noise rssi average statistic.
zpal_status_t	zpal_radio_get_background_rssi (uint8_t channel, int8_t *rssi)
	Returns the background RSSI.
zpal_tx_power_t	zpal_radio_get_default_tx_power (void)
	Function for getting the default tx power in deci dBm.
uint8_t	zpal_radio_get_reduce_tx_power (void)
	Function for getting the current reduce RF tx power compared to the default normal power in dBm.
void	zpal_radio_enable_flirs (void)
	Allows the radio to go into FLiRS receive mode.
bool	zpal_radio_is_flirs_enabled (void)
	Returns whether FLiRS mode is enabled in the radio.
void	zpal_radio_start_receive_after_power_down (bool wait_for_beam)
	Starts the receiver after power down.
void	zpal_radio_abort (void)
	Turn radio off without changing configuration.
void	zpal_radio_reset_after_beam_receive (bool start_receiver)
	Resets the radio configuration to receive mode after having received a beam.
bool	zpal_radio_is_fragmented_beam_enabled (void)
	Returns whether use of fragmented beams is enabled or not for the active region.
void	zpal_radio_calibrate (void)
	Calibrates the radio. Z-Wave expects the radio ZPAL implementation to generate a ZPAL_RADIO_EVENT_RXTX_CALIBRATE event when calibration is required. The event will invoke this function in non-interrupt context.
bool	zpal_radio_is_lbt_enabled (void)
	Returns whether listen before talk (LBT) is enabled.
uint16_t	zpal_radio_get_beam_startup_time (void)
	Returns the time it takes to start transmission of wake up beams. Includes time spent on LBT.
node_id_t	zpal_radio_get_beam_node_id (void)
	Returns the node ID associated with most recently received beam frame.
zpal_tx_power_t	zpal_radio_get_minimum_lr_tx_power (void)
	Returns the minimum transmit power for Z-Wave Long Range.
zpal_tx_power_t	zpal_radio_get_maximum_lr_tx_power (void)
	Returns the maximum transmit power for Z-Wave Long Range.
bool	zpal_radio_is_debug_enabled (void)
	Returns whether debug is enabled or disabled.
const zpal_radio_profile_t *	zpal_radio_get_rf_profile (void)
	a getter on the current rf profile. Function return a pointer (instead of a struct) to reduce RAM memory usage and execution time. The pointer target a const structure because it should not be used to modify the content of the structure.
zpal_radio_lr_channel_config_t	zpal_radio_get_lr_channel_config (void)
	Function to read current Long Range Channel Configuration.
zpal_radio_lr_channel_t	zpal_radio_get_primary_long_range_channel (void)
	Function to read current Primary Long Range Channel.
void	zpal_radio_set_primary_long_range_channel (zpal_radio_lr_channel_t channel)
	Function to set the Primary Long Range Channel.
bool	zpal_radio_get_long_range_channel_auto_mode (void)
	Function to read current Long Range Channel selection mode.
void	zpal_radio_set_long_range_channel_auto_mode (bool enable)
	Function to set the Long Range Channel selction mode.
void	zpal_radio_set_long_range_lock (bool lock)
	Function to the set Long Range channel Locked status.
bool	zpal_radio_is_long_range_locked (void)
	Function to read the Long Range channel Locked status.
bool	zpal_radio_is_region_supported (const zpal_radio_region_t region)
	Function to check if the stack implementation supports a given region.
int8_t	zpal_radio_get_flirs_beam_tx_power (void)
	Read the saved tx power of the last received long-range beam.
bool	zpal_radio_is_transmit_allowed (uint8_t channel, uint8_t frame_length, uint8_t frame_priority)
	Check if transmission is allowed for specified channel.
bool	zpal_radio_attenuate (uint8_t adjust_tx_power)
	Function to reduce Tx power of classic non-listening devices.
zpal_tx_power_t	zpal_radio_get_maximum_tx_power (void)
	Return the maximum board supported tx power for classic z-wave.
void	zpal_radio_request_calibration (bool forced)
	Function to radio calibration.

Detailed Description

Defines a platform abstraction layer for the Z-Wave radio.

The ZPAL Radio module contains several APIs which are required to be implemented.

A user of this radio module shall first define all parameters of the Z-Wave Radio Profile (i.e., zpal_radio_profile_t) and initialise the radio using zpal_radio_init API.

After the initialisation of the radio is executed, the user can use any of the radio APIs to execute radio related paradigm for instance

• zpal_radio_transmit shall be used to transmit a Z-Wave frame on radio
• zpal_radio_start_receive shall be used to enable the reception of Z-Wave frame

The radio API assumes that the radio will return to receive mode with channel hopping enabled after transmitting a frame.

Initialization of the radio

void
RXHandlerFromISR(zpal_radio_event_t rxStatus)
{
   // Rx handle in ISR context
}
 
void
TXHandlerFromISR(zpal_radio_event_t txStatus)
{
  // Tx complete handle in ISR context
}
 
void
RegionChangeHandler(zpal_radio_event_t regionChangeStatus)
{
  // Region changed, make sure region specific data and statistics are cleared
}
 
void
RadioAssertHandler(zpal_radio_event_t assertVal)
{
  // Radio driver or hardware asserted, handle it
}
 
initialize_radio()
{
  static zpal_radio_profile_t RfProfile;
  static zpal_radio_network_stats_t sNetworkStatistic = {0};
  static uint8_t network_homeid[4] = {0xDE, 0xAD, 0xBE, 0xEF};
 
  // Set radio for US always on mode
  static zpal_radio_profile_t RfProfile = {.region = REGION_US,
                                    .wakeup = ZPAL_RADIO_WAKEUP_ALWAYS_LISTEN,
                                    .listen_before_talk_threshold = ELISTENBEFORETALKTRESHOLD_DEFAULT,
                                    .tx_power_max = 0,
                                    .tx_power_adjust = 33,
                                    .tx_power_max_lr = 140,
                                    .home_id = &network_homeid,
                                    .rx_cb = RXHandlerFromISR,
                                    .tx_cb = TXHandlerFromISR,
                                    .region_change_cb = RegionChangeHandler,
                                    .assert_cb = RadioAssertHandler,
                                    .network_stats = &sNetworkStatistic,
                                    .radio_debug_enable = false,
                                    .primary_lr_channel = ZPAL_RADIO_LR_CHANNEL_A};
 
  zpal_radio_init(RfProfile);
}

Transmitting a frame

#define TX_FAILED          0
#define TX_FRAME_SUCCESS   1
#define TX_BEAM_SUCCESS    2
 
static const zpal_radio_transmit_parameter_t TxParameter100kCh1 = {.speed = ZPAL_RADIO_SPEED_100K,
                                                                   .channel_id = 0,
                                                                   .crc = ZPAL_RADIO_CRC_16_BIT_CCITT,
                                                                   .preamble = 0x55,
                                                                   .preamble_length = 40,
                                                                   .start_of_frame = 0xF0,
                                                                   .repeats = 0};
 
zpal_status_t transmit_frame()
{
  // Singlecast MAC header from node 1 to node 2
  uint8_t header_buffer[9] = {0xDE, 0xAD, 0xBE, 0xEF, 0x01, 0x41, 0x01, 14, 0x02};
  // Basic set On frame
  uint8_t payload_buffer[3] = {0x20, 0x01, 0xFF};
 
  return zpal_radio_transmit(&TxParameter100kCh1,         // use 100kbps FSK profile
                             9,
                             (uint8_t *)&header_buffer,
                             3,
                             (uint8_t *)&payload_buffer,
                             true,                        // Do LBT before transmit
                             0);                          // Transmit power 0dBm
}
 
void
TXHandlerFromISR(zpal_radio_event_t txStatus)
{
  uint8_t status;
 
  if ((ZPAL_RADIO_EVENT_TX_FAIL == txStatus) || (ZPAL_RADIO_EVENT_TX_FAIL_LBT == txStatus))
  {
    status = TX_FAILED;
  }
  else if (txStatus & ZPAL_RADIO_EVENT_FLAG_BEAM)
  {
    status = TX_BEAM_SUCCESS;
  }
  else
  {
    status = TX_FRAME_SUCCESS;
  }
  / Get out of ISR context and handle transmit complete
  HandleTransmitComplete(status);
}

Receiving a frame

#define RX_ABORT                 0
#define RX_BEAM                  1
#define RX_FRAME                 2
#define RX_CALIBRATION_NEEDED    3
 
void
RXHandlerFromISR(zpal_radio_event_t rxStatus)
{
  uint8_t status;
 
  switch (rxStatus)
  {
    case ZPAL_RADIO_EVENT_RX_BEAM:
      // Beam received
      status = RX_BEAM;
      break;
    case ZPAL_RADIO_EVENT_RX_ABORT:
      // Receive was aborted due to an error in the frame
      status = RX_ABORT;
      break;
    case ZPAL_RADIO_EVENT_RX:
      // Valid frame received
      status = RX_FRAME;
      break;
    case ZPAL_RADIO_EVENT_RXTX_CALIBRATE:
      // Radio reports that calibration is needed
      status = RX_CALIBRATION_NEEDED;
      break;
  }
 
  / Get out of ISR context and handle frame
  HandleFrame(status);
}

Macro Definition Documentation

REGION_2CH_NUM

#define REGION_2CH_NUM   = (REGION_2CH_END - REGION_2CH_FIRST)

Number of 2 channel regions.

REGION_3CH_NUM

#define REGION_3CH_NUM   = (REGION_3CH_END - REGION_3CH_FIRST)

Number of 3 channel regions.

ZPAL_RADIO_INVALID_RSSI_DBM

#define ZPAL_RADIO_INVALID_RSSI_DBM   (-128)

The RSSI value is invalid.

ZPAL_RADIO_RSSI_NOT_AVAILABLE

#define ZPAL_RADIO_RSSI_NOT_AVAILABLE   (127)

The RSSI value is not available, probably because it has not been measured yet.

ZW_TX_POWER_10DBM

#define ZW_TX_POWER_10DBM   100

10 dBm transmit power definition.

ZW_TX_POWER_14DBM

#define ZW_TX_POWER_14DBM   140

14 dBm transmit power definition.

ZW_TX_POWER_20DBM

#define ZW_TX_POWER_20DBM   200

20 dBm transmit power definition.

Typedef Documentation

node_id_t

typedef uint16_t node_id_t

Node ID type.

zpal_radio_callback_t

typedef void(* zpal_radio_callback_t) (zpal_radio_event_t event)

Callback type used for radio events.

Parameters

event

The radio event that caused the callback to be invoked.

zpal_radio_receive_handler_t

typedef void(* zpal_radio_receive_handler_t) (zpal_radio_rx_parameters_t *rx_parameters, zpal_radio_receive_frame_t *frame)

Function pointer declaration for handling of received frames.

When a frame is received this function will be invoked in order to process the frame.

Parameters

[in]	rx_parameters	Pointer to the structure with channel and rssi values.
[in]	frame	Pointer to the received frame. The frame is expected to be located in Z-Wave stack reserved memory and allocated throughout lifetime of stack processing. Application should copy payload data if required for unsynchronized data processing.

zpal_tx_power_t

typedef int16_t zpal_tx_power_t

Parameter type to store deci dBm values.

Enumeration Type Documentation

zpal_radio_crc_t

enum zpal_radio_crc_t

Enumeration containing supported checksum types in Z-Wave.

Enumerator
ZPAL_RADIO_CRC_NONE	No checksum.
ZPAL_RADIO_CRC_8_BIT_XOR	8 bit XOR checksum.
ZPAL_RADIO_CRC_16_BIT_CCITT	16 bit CRC-CCITT checksum.

zpal_radio_event_t

enum zpal_radio_event_t

Enumeratio radio events.

Enumerator
ZPAL_RADIO_EVENT_NONE	No radio event.
ZPAL_RADIO_EVENT_RX_COMPLETE	Frame received.
ZPAL_RADIO_EVENT_TX_COMPLETE	Transmit complete.
ZPAL_RADIO_EVENT_RX_BEAM_COMPLETE	Beam received.
ZPAL_RADIO_EVENT_TX_BEAM_COMPLETE	Beam sent.
ZPAL_RADIO_EVENT_RX_ABORT	Receive was aborted.
ZPAL_RADIO_EVENT_TX_FAIL	Transmit failed.
ZPAL_RADIO_EVENT_TX_FAIL_LBT	Transmit failed because of an LBT failure.
ZPAL_RADIO_EVENT_RXTX_CALIBRATE	Radio needs calibration.
ZPAL_RADIO_EVENT_MASK	Radio event mask.
ZPAL_RADIO_EVENT_FLAG_SUCCESS	Indicates a successful event.
ZPAL_RADIO_EVENT_TX_TIMEOUT	Transmit timeout.
ZPAL_RADIO_EVENT_RX_TIMEOUT	Indicates Rx event started but never completed after 10 secs.

zpal_radio_header_type_t

enum zpal_radio_header_type_t

Z-Wave Frame header format types.

Enumerator
ZPAL_RADIO_HEADER_TYPE_2CH	2 Channel header format.
ZPAL_RADIO_HEADER_TYPE_3CH	3 Channel header format.
ZPAL_RADIO_HEADER_TYPE_LR	LR Channel header format.
ZPAL_RADIO_HEADER_TYPE_UNDEFINED	Undefined Channel header format.

zpal_radio_lr_channel_config_t

enum zpal_radio_lr_channel_config_t

List of LR channel configurations. Used to select the correct phy configuration.

Enumerator
ZPAL_RADIO_LR_CH_CFG_NO_LR	used if region does not support Long range or end device included in classic network. Phy is configured to listen only on classic Z-Wave channels.
ZPAL_RADIO_LR_CH_CFG1	used by controller with primary channel A and not included end device Phy is configured to listen on classic Z-Wave channels and Long Range channel A.
ZPAL_RADIO_LR_CH_CFG2	used only by controller with primary channel B Phy is configured to listen on classic Z-Wave channels and Long Range channel B.
ZPAL_RADIO_LR_CH_CFG3	used only by end device when included in a LR network. Phy is configured to listen only on Long Range channels A & B.
ZPAL_RADIO_LR_CH_CFG_COUNT	enumeration items count

zpal_radio_lr_channel_t

enum zpal_radio_lr_channel_t

Enumeration containing Long Range Channels.

Enumerator
ZPAL_RADIO_LR_CHANNEL_UNINITIALIZED	Long Range Channel setting not initialized.
ZPAL_RADIO_LR_CHANNEL_A	Long Range Channel A.
ZPAL_RADIO_LR_CHANNEL_B	Long Range Channel B.
ZPAL_RADIO_LR_CHANNEL_UNKNOWN	Long Range Channel Unknown.
ZPAL_RADIO_LR_CHANNEL_AUTO	Long Range automatically selected Channel.

zpal_radio_mode_t

enum zpal_radio_mode_t

Defines the different radio modes supported by Z-Wave.

Enumerator
ZPAL_RADIO_MODE_NON_LISTENING	The radio is not listening unless configured to for a period.
ZPAL_RADIO_MODE_ALWAYS_LISTENING	The radio is always listening.
ZPAL_RADIO_MODE_FLIRS	The radio is frequently listening.

zpal_radio_protocol_mode_t

enum zpal_radio_protocol_mode_t

Enumeration containing Z-Wave channels known as protocol modes.

Enumerator
ZPAL_RADIO_PROTOCOL_MODE_1	2 Channel Protocol Mode.
ZPAL_RADIO_PROTOCOL_MODE_2	3 Channel Protocol Mode.
ZPAL_RADIO_PROTOCOL_MODE_3	4 Channel Protocol Mode - Combination of 2 Channel (9.6kb/40kb, 100kb) and Long Range Channel.
ZPAL_RADIO_PROTOCOL_MODE_4	2 Long Range Channel Protocol Mode - End Device.
ZPAL_RADIO_PROTOCOL_MODE_UNDEFINED	Protocol mode undefined means invalid region code.

zpal_radio_region_t

enum zpal_radio_region_t

Enumeration official Z-Wave regions.

Enumerator
REGION_2CH_FIRST	First 2 channels region (with 3 data rates)
REGION_EU	Radio is located in Region EU. 2 Channel region.
REGION_US	Radio is located in Region US. 2 Channel region.
REGION_ANZ	Radio is located in Region Australia/New Zealand. 2 Channel region.
REGION_HK	Radio is located in Region Hong Kong. 2 Channel region.
REGION_DEPRECATED_4	Deprecated value, should never be used.
REGION_IN	Radio is located in Region India. 2 Channel region.
REGION_IL	Radio is located in Region Israel. 2 Channel region.
REGION_RU	Radio is located in Region Russia. 2 Channel region.
REGION_CN	Radio is located in Region China. 2 Channel region.
REGION_US_LR	Radio is located in Region US. 2 Channel LR region.
REGION_DEPRECATED_10	Deprecated value, should never be used.
REGION_EU_LR	Radio is located in Region EU. 2 Channel LR region.
REGION_2CH_END	end of 2 channels regions (with 3 data rates)
REGION_3CH_FIRST	First 3 channels region (with 1 data rate)
REGION_JP	Radio is located in Region Japan. 3 Channel region.
REGION_KR	Radio is located in Region Korea. 3 Channel region.
REGION_3CH_END	end of 3 channels regions (with 1 data rate)
REGION_DEPRECATED_48	Deprecated value, should never be used.
REGION_UNDEFINED	Undefined region.
REGION_DEFAULT	Radio is located in Library Default Region EU. 2 Channel region.

zpal_radio_speed_t

enum zpal_radio_speed_t

Enumeration containing supported baud rates.

Enumerator
ZPAL_RADIO_SPEED_UNDEFINED	Undefined baud rate.
ZPAL_RADIO_SPEED_9600	9.6 kbps
ZPAL_RADIO_SPEED_40K	40 kbps
ZPAL_RADIO_SPEED_100K	100 kbps
ZPAL_RADIO_SPEED_100KLR	100 kbps for long range

zpal_radio_status_t

enum zpal_radio_status_t

Radio status.

Enumerator
ZPAL_RADIO_STATUS_IDLE	Radio is idling.
ZPAL_RADIO_STATUS_RX	RX in progress.
ZPAL_RADIO_STATUS_TX	TX in progress.
ZPAL_RADIO_STATUS_TX_BEAM	Beam TX in progress.
ZPAL_RADIO_STATUS_RX_BEAM	Beam RX in progress.

zpal_radio_tx_power_t

enum zpal_radio_tx_power_t

Enumeration containing Tx power settings.

Enumerator
ZPAL_RADIO_TX_POWER_DEFAULT	Default, max TX power.
ZPAL_RADIO_TX_POWER_MINUS1_DBM	-1 dBm TX power.
ZPAL_RADIO_TX_POWER_MINUS2_DBM	-2 dBm TX power.
ZPAL_RADIO_TX_POWER_MINUS3_DBM	-3 dBm TX power.
ZPAL_RADIO_TX_POWER_MINUS4_DBM	-4 dBm TX power.
ZPAL_RADIO_TX_POWER_MINUS5_DBM	-5 dBm TX power.
ZPAL_RADIO_TX_POWER_MINUS6_DBM	-6 dBm TX power.
ZPAL_RADIO_TX_POWER_MINUS7_DBM	-7 dBm TX power.
ZPAL_RADIO_TX_POWER_MINUS8_DBM	-8 dBm TX power.
ZPAL_RADIO_TX_POWER_MINUS9_DBM	-9 dBm TX power.
ZPAL_RADIO_TX_POWER_UNINITIALIZED	The TX power is uninitialized.
ZPAL_RADIO_TX_POWER_REDUCED	Default reduced TX power.

zpal_radio_wakeup_t

enum zpal_radio_wakeup_t

Wakeup interval for the radio. A FLiRS node will use 250 or 1000 ms interval, all other nodes should be configured as always listening.

Enumerator
ZPAL_RADIO_WAKEUP_NEVER_LISTEN	Node is not listening (Only listen when application requests it).
ZPAL_RADIO_WAKEUP_ALWAYS_LISTEN	Node is always listening.
ZPAL_RADIO_WAKEUP_EVERY_250ms	Node wakes up every 250 ms interval to listen for a wakeup beam.
ZPAL_RADIO_WAKEUP_EVERY_1000ms	Node wakes up every 1000 ms interval to listen for a wakeup beam.

zpal_radio_zwave_channel_t

enum zpal_radio_zwave_channel_t

Enumeration containing Z-Wave channels.

Enumerator
ZPAL_RADIO_ZWAVE_CHANNEL_0	Z-Wave channel 0.
ZPAL_RADIO_ZWAVE_CHANNEL_1	Z-Wave channel 1.
ZPAL_RADIO_ZWAVE_CHANNEL_2	Z-Wave channel 2.
ZPAL_RADIO_ZWAVE_CHANNEL_3	Z-Wave channel 3.
ZPAL_RADIO_ZWAVE_CHANNEL_4	Z-Wave channel 4.
ZPAL_RADIO_ZWAVE_CHANNEL_UNKNOWN	Z-Wave channel Unknown.

Function Documentation

zpal_radio_abort()

void zpal_radio_abort

(

void

)

Turn radio off without changing configuration.

zpal_radio_attenuate()

bool zpal_radio_attenuate

(

uint8_t

adjust_tx_power

)

Function to reduce Tx power of classic non-listening devices.

Parameters

[in]

adjust_tx_power

Reduces the devices default Tx power in dB. Valid range: 0-9 dB.

Returns

True when reduction is allowed, false for listening devices and out of range input.

zpal_radio_calibrate()

void zpal_radio_calibrate

(

void

)

Calibrates the radio. Z-Wave expects the radio ZPAL implementation to generate a ZPAL_RADIO_EVENT_RXTX_CALIBRATE event when calibration is required. The event will invoke this function in non-interrupt context.

zpal_radio_change_region()

zpal_status_t zpal_radio_change_region	(	zpal_radio_region_t	eRegion,
		zpal_radio_lr_channel_config_t	eLrChCfg )

Function used to change region and Long Range mode at the same time.

Parameters

[in]	eRegion	Region to change to.
[in]	eLrChCfg	long range mode to change to (in case of no LR region, should be set to ZPAL_RADIO_LR_CH_CFG_NO_LR).

Returns

ZPAL_STATUS_OK if the region was successfully changed and ZPAL_STATUS_FAIL otherwise.

zpal_radio_clear_network_stats()

void zpal_radio_clear_network_stats

(

void

)

Function for clearing current Network statistics.

zpal_radio_clear_tx_timers()

void zpal_radio_clear_tx_timers

(

void

)

Function for clearing current Channel Transmit timers.

zpal_radio_enable_flirs()

void zpal_radio_enable_flirs

(

void

)

Allows the radio to go into FLiRS receive mode.

zpal_radio_enable_rx_broadcast_beam()

void zpal_radio_enable_rx_broadcast_beam

(

bool

enable

)

Enable or disables reception of broadcast beam. Enable or disable FLiRS broadcast address.

Parameters

[in]

enable

true to enable FLiRS broadcast address, false to disable.

zpal_radio_get_background_rssi()

zpal_status_t zpal_radio_get_background_rssi	(	uint8_t	channel,
		int8_t *	rssi )

Returns the background RSSI.

Parameters

[in]	channel	uint8_t channel Id for measurement.
[out]	rssi	pointer to background RSSI.

Returns

ZPAL_STATUS_OK if a valid RSSI value is available and read. ZPAL_STATUS_FAIL if an RSSI value cannot be read. The value of *rssi is invalid. Reasons for failure includes radio not being initiailized. Other vendor specific failures might occur as well. ZPAL_STATUS_BUSY if the radio is actually busy. The value of *rssi is invalid. ZPAL_STATUS_INVALID_ARGUMENT if rssi is NULL.

zpal_radio_get_beam_node_id()

node_id_t zpal_radio_get_beam_node_id

(

void

)

Returns the node ID associated with most recently received beam frame.

Returns

Node ID associated with the most recently received beam frame.

zpal_radio_get_beam_startup_time()

uint16_t zpal_radio_get_beam_startup_time

(

void

)

Returns the time it takes to start transmission of wake up beams. Includes time spent on LBT.

Returns

startup time in milli seconds.

zpal_radio_get_default_tx_power()

zpal_tx_power_t zpal_radio_get_default_tx_power

(

void

)

Function for getting the default tx power in deci dBm.

Returns

The default RF TX power in deci dBm

zpal_radio_get_flirs_beam_tx_power()

int8_t zpal_radio_get_flirs_beam_tx_power

(

void

)

Read the saved tx power of the last received long-range beam.

Returns

The tx power of the last received long-range beam.

zpal_radio_get_last_beam_channel()

zpal_radio_zwave_channel_t zpal_radio_get_last_beam_channel

(

void

)

Get last beam channel. Retrieve the channel on which we have last received a beam on.

Returns

Last beam channel.

zpal_radio_get_last_beam_rssi()

int8_t zpal_radio_get_last_beam_rssi

(

void

)

Get last beam RSSI. Retrieve the RSSI of the last beam received.

Returns

Last beam rssi.

zpal_radio_get_last_received_frame()

void zpal_radio_get_last_received_frame

(

void

)

Function to get last received frame. If a frame is received, zpal_radio_receive_handler_t will be invoked.

zpal_radio_get_long_range_channel_auto_mode()

bool zpal_radio_get_long_range_channel_auto_mode

(

void

)

Function to read current Long Range Channel selection mode.

Returns

true for automatically slected channel, false for manually selected channel

zpal_radio_get_lr_channel_config()

zpal_radio_lr_channel_config_t zpal_radio_get_lr_channel_config

(

void

)

Function to read current Long Range Channel Configuration.

Returns

current long rang channel configuration (ZPAL_RADIO_LR_Ch_CFG if region without lr)

zpal_radio_get_maximum_lr_tx_power()

zpal_tx_power_t zpal_radio_get_maximum_lr_tx_power

(

void

)

Returns the maximum transmit power for Z-Wave Long Range.

Returns

Maximum TX power in dBm.

zpal_radio_get_maximum_tx_power()

zpal_tx_power_t zpal_radio_get_maximum_tx_power

(

void

)

Return the maximum board supported tx power for classic z-wave.

Returns

The maximum board supported tx power in deci dBm.

zpal_radio_get_minimum_lr_tx_power()

zpal_tx_power_t zpal_radio_get_minimum_lr_tx_power

(

void

)

Returns the minimum transmit power for Z-Wave Long Range.

Returns

Minimum TX power in dBm.

zpal_radio_get_primary_long_range_channel()

zpal_radio_lr_channel_t zpal_radio_get_primary_long_range_channel

(

void

)

Function to read current Primary Long Range Channel.

Returns

ZPAL_RADIO_LR_CHANNEL_A or ZPAL_RADIO_LR_CHANNEL_B.

zpal_radio_get_protocol_mode()

zpal_radio_protocol_mode_t zpal_radio_get_protocol_mode

(

void

)

Function to get the protocol mode used in the configured region.

Returns

Protocol mode used in the configured region.

zpal_radio_get_reduce_tx_power()

uint8_t zpal_radio_get_reduce_tx_power

(

void

)

Function for getting the current reduce RF tx power compared to the default normal power in dBm.

Returns

The current reduce RF TX power in dBm.

zpal_radio_get_region()

zpal_radio_region_t zpal_radio_get_region

(

void

)

Function for getting REGION runtime.

Returns

Current region.

zpal_radio_get_rf_profile()

const zpal_radio_profile_t * zpal_radio_get_rf_profile

(

void

)

a getter on the current rf profile. Function return a pointer (instead of a struct) to reduce RAM memory usage and execution time. The pointer target a const structure because it should not be used to modify the content of the structure.

Returns

pointer on the current rf profile.

zpal_radio_init()

void zpal_radio_init

(

zpal_radio_profile_t *const

profile

)

Initializes the radio.

Parameters

[in]

profile

Pointer to the profile with information to configure the radio.

zpal_radio_is_debug_enabled()

bool zpal_radio_is_debug_enabled

(

void

)

Returns whether debug is enabled or disabled.

Returns

True if debug is enabled, false otherwise.

zpal_radio_is_flirs_enabled()

bool zpal_radio_is_flirs_enabled

(

void

)

Returns whether FLiRS mode is enabled in the radio.

Returns

True when FLiRS mode is enabled.

zpal_radio_is_fragmented_beam_enabled()

bool zpal_radio_is_fragmented_beam_enabled

(

void

)

Returns whether use of fragmented beams is enabled or not for the active region.

Returns

True if use of fragmented beams is enabled, false otherwise.

zpal_radio_is_lbt_enabled()

bool zpal_radio_is_lbt_enabled

(

void

)

Returns whether listen before talk (LBT) is enabled.

Returns

True if LBT is enabled, false otherwise.

zpal_radio_is_long_range_locked()

bool zpal_radio_is_long_range_locked

(

void

)

Function to read the Long Range channel Locked status.

Returns

True if node shall use Long Range channel only.

zpal_radio_is_region_supported()

bool zpal_radio_is_region_supported

(

const zpal_radio_region_t

region

)

Function to check if the stack implementation supports a given region.

Parameters

[in]

region

Region to check

Returns

True if the region is supported, False if it is not

zpal_radio_is_transmit_allowed()

bool zpal_radio_is_transmit_allowed	(	uint8_t	channel,
		uint8_t	frame_length,
		uint8_t	frame_priority )

Check if transmission is allowed for specified channel.

Parameters

[in]	channel	The channel to check.
[in]	frame_length	The length of the frame to send.
[in]	frame_priority	The Tx priority of the frame.

Returns

True if node shall use Long Range channel only.

Note

In Japan all communication must comply to a max 100ms transmit followed by min 100ms silence period.

Cause a channel shift.

zpal_radio_power_down()

void zpal_radio_power_down

(

void

)

Powers down the radio transceiver.

zpal_radio_request_calibration()

void zpal_radio_request_calibration

(

bool

forced

)

Function to radio calibration.

Parameters

[in]

forced

If true, radio calibration is performed regardless if it is required. If false, radio calibration is performed only if it is required.

zpal_radio_reset_after_beam_receive()

void zpal_radio_reset_after_beam_receive

(

bool

start_receiver

)

Resets the radio configuration to receive mode after having received a beam.

Parameters

[in]

start_receiver

If set to true, the receiver will start listening. Otherwise, it will stay inactive.

zpal_radio_rf_channel_statistic_background_rssi_average_update()

void zpal_radio_rf_channel_statistic_background_rssi_average_update	(	zpal_radio_zwave_channel_t	zwavechannel,
		int8_t	rssi )

Function for updating the rf channel background noise rssi average statistic.

Parameters

zwavechannel	Z-Wave channel on which background noise rssi average should be updated.
rssi	rssi to add to sampleset used for calculating average background noise rssi on specified Z-Wave channel.

zpal_radio_rf_channel_statistic_clear()

void zpal_radio_rf_channel_statistic_clear

(

zpal_radio_zwave_channel_t

zwavechannel

)

Function for clearing specified rf channel statistics.

Parameters

zwavechannel

rf channel for which statistics will be cleared.

zpal_radio_rf_channel_statistic_end_device_rssi_average_update()

void zpal_radio_rf_channel_statistic_end_device_rssi_average_update	(	zpal_radio_zwave_channel_t	zwavechannel,
		int8_t	rssi )

Function for updating the rf channel end device noise rssi average statistic.

Parameters

zwavechannel	Z-Wave channel on which end device noise rssi average should be updated.
rssi	rssi to add to sampleset used for calculating average end device noise rssi on specified Z-Wave channel.

zpal_radio_rf_channel_statistic_get()

bool zpal_radio_rf_channel_statistic_get	(	zpal_radio_zwave_channel_t	zwavechannel,
		zpal_radio_rf_channel_statistic_t *	p_radio_channel_statistic )

Parameters

zwavechannel	zwave channel for which statistics will be returned.
p_radio_channel_statistic	pointer to structure where statistics for specified zwave channel should be copied.

Returns

true If delivered structure has been filled with current statistic for specified zwavechannel.

false If delivered structure has NOT been filled with any channel statistics.

zpal_radio_rf_channel_statistic_tx_channel_set()

void zpal_radio_rf_channel_statistic_tx_channel_set

(

zpal_radio_zwave_channel_t

zwavechannel

)

Function for setting the zwavechannel used when calling zpal_radio_rf_channel_statistic_tx_frames, zpal_radio_rf_channel_statistic_tx_retries and zpal_radio_rf_channel_statistic_tx_lbt_failures.

Parameters

zwavechannel

Z-Wave channel current rf channel statistic 'tx channel' should be set to.

zpal_radio_rf_channel_statistic_tx_frames()

void zpal_radio_rf_channel_statistic_tx_frames

(

void

)

Function for incrementing the rf channel tx frame statistic.

zpal_radio_rf_channel_statistic_tx_lbt_failures()

void zpal_radio_rf_channel_statistic_tx_lbt_failures

(

void

)

Function for incrementing the rf channel tx lbt failures.

zpal_radio_rf_channel_statistic_tx_retries()

void zpal_radio_rf_channel_statistic_tx_retries

(

void

)

Function for incrementing the rf channel tx retries statistic.

zpal_radio_set_lbt_level()

void zpal_radio_set_lbt_level	(	uint8_t	channel,
		int8_t	level )

Function for setting the LBT RSSI level.

Parameters

[in]	channel	uint8_t channel to set LBT threshold for.
[in]	level	int8_t LBT RSSI level in dBm.

zpal_radio_set_long_range_channel_auto_mode()

void zpal_radio_set_long_range_channel_auto_mode

(

bool

enable

)

Function to set the Long Range Channel selction mode.

Parameters

[in]

enable

true to enable the automatically channel selection mode, false to enable the manual channel selection mode

zpal_radio_set_long_range_lock()

void zpal_radio_set_long_range_lock

(

bool

lock

)

Function to the set Long Range channel Locked status.

Parameters

[in]

lock

Long Range channel Locked status.

zpal_radio_set_network_ids()

void zpal_radio_set_network_ids	(	uint32_t	home_id,
		node_id_t	node_id,
		zpal_radio_mode_t	mode,
		uint8_t	home_id_hash )

Sets the home ID, the node ID and the radio mode.

Parameters

[in]	home_id	Network home ID.
[in]	node_id	Network node ID.
[in]	mode	Radio mode: listening, non-listening or FLiRS.
[in]	home_id_hash	Radio mode: listening, non-listening or FLiRS.

zpal_radio_set_primary_long_range_channel()

void zpal_radio_set_primary_long_range_channel

(

zpal_radio_lr_channel_t

channel

)

Function to set the Primary Long Range Channel.

Parameters

[in]

channel

zpal_radio_lr_channel_t Long Range Channel to set as Primary Long Range Channel.

zpal_radio_start_receive()

void zpal_radio_start_receive

(

)

Starts the receiver and enables reception of frames.

This function will start the receiver if the radio is initialized and in a state where the radio can be switched to receive mode immediately. If the radio is transmitting a frame the radio will enter receive mode after the frame has been transmitted. If the receiver is already started, nothing will happen.

zpal_radio_start_receive_after_power_down()

void zpal_radio_start_receive_after_power_down

(

bool

wait_for_beam

)

Starts the receiver after power down.

Parameters

[in]

wait_for_beam

If set to true, the radio will listen for a beam. Otherwise, it will listen normally.

zpal_radio_transmit()

zpal_status_t zpal_radio_transmit	(	zpal_radio_transmit_parameter_t const *const	tx_parameters,
		uint8_t	frame_header_length,
		uint8_t const *const	frame_header_buffer,
		uint8_t	frame_payload_length,
		uint8_t const *const	frame_payload_buffer,
		uint8_t	use_lbt,
		int8_t	tx_power )

Function for transmitting a Z-Wave frame though the radio.

Parameters

[in]	tx_parameters	Parameter setting specifying speed, channel, wakeup, crc for transmission.
[in]	frame_header_length	Length of frame header data to transmit.
[in]	frame_header_buffer	Pointer to data array containing the frame header.
[in]	frame_payload_length	Length of frame payload data to transmit.
[in]	frame_payload_buffer	Pointer to data array containing the frame payload.
[in]	use_lbt	if set to 1, LBT will be done prior radioTransmit.
[in]	tx_power	The RF tx power to use for transmitting in dBm.

Returns

ZPAL_STATUS_OK if the data was successfully transmit, ZPAL_STATUS_BUFFER_FULL when queue is full.

zpal_radio_transmit_beam()

zpal_status_t zpal_radio_transmit_beam	(	zpal_radio_transmit_parameter_t const *const	tx_parameters,
		uint8_t	beam_data_len,
		uint8_t const *const	beam_data,
		int8_t	tx_power )

Function for transmitting a Z-Wave Beam frame though the radio.

Parameters

[in]	tx_parameters	Parameter setting specifying speed, channel, wakeup.
[in]	beam_data_len	Length of the Beam data to transmit.
[in]	beam_data	Pointer to data array containing the BEAM data.
[in]	tx_power	The RF tx power to use for transmitting in dbm.

Returns

ZPAL_STATUS_OK if the data was successfully transmit, ZPAL_STATUS_BUFFER_FULL when queue is full.