Zpal-radio#

zpal_radio_listen_t#

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

zpal_radio_crc_t#

zpal_radio_crc_t

Enumeration containing supported checksum types in Z-Wave.

zpal_radio_speed_t#

zpal_radio_speed_t

Enumeration containing supported baud rates.

zpal_radio_lr_channel_t#

zpal_radio_lr_channel_t

Enumeration containing Long Range Channels.

zpal_radio_zwave_channel_t#

zpal_radio_zwave_channel_t

Enumeration containing Z-Wave channels.

zpal_radio_protocol_mode_t#

zpal_radio_protocol_mode_t

Enumeration containing Z-Wave channels known as protocol modes.

zpal_radio_lr_channel_config_t#

zpal_radio_lr_channel_config_t

List of LR channel configuration.

Used to select the correct phy configuration.

zpal_radio_region_t#

zpal_radio_region_t

Enumeration official Z-Wave regions.

zpal_radio_tx_power_t#

zpal_radio_tx_power_t

Enumeration containing Tx power settings.

zpal_radio_header_type_t#

zpal_radio_header_type_t

Z-Wave Frame header format types.

zpal_radio_event_t#

zpal_radio_event_t

Enumeratio radio events.

zpal_radio_application_t#

zpal_radio_application_t

zpal_radio_status_t#

zpal_radio_status_t

node_id_t#

typedef uint16_t node_id_t

Node ID type.

zpal_tx_power_decidbm_t#

typedef int16_t zpal_tx_power_decidbm_t

Parameter type to store deci dBm values.

zpal_tx_power_t#

typedef zpal_tx_power_decidbm_t zpal_tx_power_t

Deprecateduse zpal_tx_power_decidbm_t instead

zpal_radio_stay_awake_id_t#

typedef uint32_t zpal_radio_stay_awake_id_t

Parameter type to store stay awake ids.

zpal_radio_beam_info_t#

typedef struct _zpal_radio_beam_info_t_ zpal_radio_beam_info_t

zpal_radio_callback_t#

typedef void(* zpal_radio_callback_t) (const zpal_radio_event_t event) )(const zpal_radio_event_t event)

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

zpal_radio_status_callback_t#

typedef void(* zpal_radio_status_callback_t) (const zpal_radio_status_t state) )(const zpal_radio_status_t state)

zpal_radio_set_network_ids#

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

Sets the home ID & the node ID.

zpal_radio_init#

zpal_status_t zpal_radio_init (const zpal_radio_profile_t *const profile)

Initializes the radio hardware with the specified configuration profile.

This function sets up the radio module based on the provided profile, ensuring it is ready for operation. The profile contains necessary configuration parameters such as frequency, and other radio-specific settings.

Note

• Ensure that the profile is valid and all required fields are set before invoking this function to avoid undefined behavior.

Returns

• ZPAL_STATUS_OK if the zpal radio layer is ready ZPAL_STATUS_INVALID_ARGUMENT if profile is NULL.

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.

Returns

• ZPAL_STATUS_OK if the region was successfully changed and ZPAL_STATUS_FAIL otherwise.

zpal_radio_get_region#

zpal_radio_region_t zpal_radio_get_region (void )

Function for getting REGION runtime.

Returns

• Current region.

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

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

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)

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

Returns

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

zpal_radio_start_receive#

zpal_status_t zpal_radio_start_receive (void )

Starts the receiver and enables reception of frames.

If the receiver is already started, nothing will happen.

zpal_radio_is_data_available#

bool zpal_radio_is_data_available (void )

Checks if data is available for processing in the radio module.

This function determines whether there is any data available in the radio module that can be processed or retrieved.

Returns

• True if data is available, false otherwise.

zpal_radio_restart_if_rx_in_progress#

zpal_status_t zpal_radio_restart_if_rx_in_progress (void )

Restart the radio if a frame reception is in progress.

The radio is restarted once the frame is completed.

If a frame reception is in progress, the function wait for the end of the frame then restart the radio (in Rx mode). In other case, the function does nothing

Returns

• ZPAL_STATUS_OK if the radio ready in receiver mode ZPAL_STATUS_BUSY if the radio is not in Rx. ZPAL_STATUS_FAIL if the function has failed to restart the radio

zpal_radio_get_last_received_frame#

zpal_status_t zpal_radio_get_last_received_frame (zpal_radio_receive_frame_t * frame)

Function to get the last received frame.

This function retrieves the oldest received Z-Wave frame from the radio module. The frame data is stored in the provided structure.

Returns

• ZPAL_STATUS_OK if a valid frame is available and retrieved. ZPAL_STATUS_FAIL if no frame is available or an error occurred.

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

void zpal_radio_set_lbt_level (uint8_t channel, int8_t level)

Function for setting the LBT RSSI level.

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.

zpal_radio_clear_tx_timers#

void zpal_radio_clear_tx_timers (void )

Function for clearing current Channel Transmit timers.

zpal_radio_clear_network_stats#

void zpal_radio_clear_network_stats (void )

Function for clearing current Network statistics.

zpal_radio_get_background_rssi#

zpal_status_t zpal_radio_get_background_rssi (uint8_t channel, int8_t * rssi)

Returns the 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. ZPAL_STATUS_INVALID_ARGUMENT if rssi is NULL.

zpal_radio_get_default_tx_power#

zpal_tx_power_decidbm_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_idle#

zpal_status_t zpal_radio_idle (void )

Puts the radio into an idle state.

This function transitions the radio to an idle state where it is neither transmitting nor receiving. It can be used to conserve power or prepare the radio for a new operation.

zpal_radio_abort#

zpal_status_t zpal_radio_abort (void )

Aborts any ongoing radio operation.

This function halts any current transmission or reception activity and brings the radio to an idle state. It can be used to immediately stop the radio's operation in case of an error or when a higher-priority operation needs to be performed.

zpal_radio_shutdown#

zpal_status_t zpal_radio_shutdown (void )

Shuts down the radio hardware.

This function powers down the radio hardware, ensuring it is in a low-power state. It should be called when the radio is no longer needed to conserve energy.

Note

• This function is definitive and should be used with caution. Once called, the radio cannot be restarted without reinitializing it.

zpal_radio_reset_after_beam_receive#

zpal_status_t zpal_radio_reset_after_beam_receive (bool start_receiver)

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

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

zpal_tx_power_decidbm_t zpal_radio_get_minimum_lr_tx_power (void )

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

Returns

• Minimum TX power in deci dBm.

zpal_radio_get_maximum_lr_tx_power#

zpal_tx_power_decidbm_t zpal_radio_get_maximum_lr_tx_power (void )

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

Returns

• Maximum TX power in deci dBm.

zpal_radio_disable_debug#

zpal_status_t zpal_radio_disable_debug (void )

Disable the radio debug mode.

This function disables the radio debug mode

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

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

zpal_status_t zpal_radio_set_long_range_channel_auto_mode (bool enable)

Function to set the Long Range Channel selction mode.

Returns

• ZPAL_STATUS_OK if the mode was successfully set, ZPAL_STATUS_FAIL otherwise.

zpal_radio_is_region_supported#

bool zpal_radio_is_region_supported (zpal_radio_region_t region)

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

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, bool cca)

Check if transmission is allowed for specified channel.

Returns

• True if node shall use Long Range channel only.

zpal_radio_attenuate#

bool zpal_radio_attenuate (zpal_radio_tx_power_t adjust_tx_power)

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

Returns

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

zpal_radio_get_maximum_tx_power#

zpal_tx_power_decidbm_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_limit_lr_power_to_capability#

zpal_tx_power_decidbm_t zpal_radio_limit_lr_power_to_capability (zpal_tx_power_decidbm_t requested_power)

Function to adjust the requested tx power for Long Range.

This function ensures that the requested power is within the allowed range

Returns

• The adjusted tx power in deci dBm.

zpal_radio_request_calibration#

void zpal_radio_request_calibration (bool forced)

Function to radio calibration.

zpal_radio_get_last_beam_info#

zpal_status_t zpal_radio_get_last_beam_info (zpal_radio_beam_info_t * beamInfo)

Retrieves information about the last received beam.

Returns

• ZPAL_STATUS_OK if the beam information was successfully retrieved, ZPAL_STATUS_INVALID_ARGUMENT if beamInfo is NULL.

zpal_radio_rf_channel_statistic_store_background_rssi_average#

void zpal_radio_rf_channel_statistic_store_background_rssi_average (zpal_radio_zwave_channel_t zwavechannel, int8_t averagerssi)

Stores the average RSSI (Received Signal Strength Indicator) for a given Z-Wave channel.

This function stores the background RSSI average for the specified Z-Wave channel.

zpal_radio_request_stay_awake#

zpal_status_t zpal_radio_request_stay_awake (uint32_t msecs, zpal_radio_stay_awake_id_t * id)

Requests the radio to stay awake for a specified number of milliseconds.

Returns

• ZPAL_STATUS_OK if the request was successful, ZPAL_STATUS_INVALID_ARGUMENT if the duration exceeds the maximum supported value or another error occurs.

Note

• Duration Limit: Maximum duration is limited by INT32_MAX ticks in the underlying sleeptimer. The actual maximum milliseconds depends on the platform's sleeptimer frequency. At the default 32768 Hz, this is approximately 18.2 hours (1,092,266 ms). Requests exceeding this limit will fail. For indefinite duration, use ZPAL_RADIO_STAY_AWAKE_ALWAYS instead.

• Timer Synchronization: This API uses platform-specific timers (hardware-based on Silicon Labs). When combining with OS-level timers (e.g., FreeRTOS ctimer), ensure stay_awake duration exceeds the OS timeout to account for scheduler latency. Example: if ctimer fires at 240ms, set stay_awake to 440ms (240 + 200ms margin). This prevents device to shutoff radio and eventually sleep before callback execution on low-power devices.

zpal_radio_revoke_stay_awake#

zpal_status_t zpal_radio_revoke_stay_awake (zpal_radio_stay_awake_id_t * id)

Revokes a previous stay-awake request, allowing the radio to sleep as normal.

Note

• The pointer to the identifier is set to 0 after revocation.

• Radio will transition to off or flirs mode if there are no other active stay-awake requests.

zpal_radio_update_stay_awake#

zpal_status_t zpal_radio_update_stay_awake (zpal_radio_stay_awake_id_t * id, uint32_t new_msecs)

Lengthens the current stay-awake period.

Returns

• ZPAL_STATUS_OK if the request was successful, ZPAL_STATUS_INVALID_ARGUMENT if the duration exceeds the maximum supported value or another error occurs.

Note

• Duration Limit: Maximum duration is limited by INT32_MAX ticks in the underlying sleeptimer. See zpal_radio_request_stay_awake() for details.

• This function is equivalent to revoking the previous request and creating a new one.

zpal_radio_get_wakeup_status#

zpal_radio_status_t zpal_radio_get_wakeup_status (void )

Getter of wakeup state of the radio.

Returns

• Current wakeup state of the radio

zpal_radio_set_status_callback#

zpal_status_t zpal_radio_set_status_callback (zpal_radio_status_callback_t callback)

Registers a callback function to be invoked on radio state changes.

This function sets the callback that will be called whenever the radio state changes. The callback function should match the signature defined by zpal_radio_state_callback_t.

Returns

• zpal_status_t Returns status code indicating success or failure of the operation.

zpal_radio_set_joinable#

zpal_status_t zpal_radio_set_joinable (bool is_joinable)

Inform the ZPAL radio layer that the node has been correctly included in a network.

Correctly included means that the node is joinable with tuple (homeid, nodeid).

Returns

• zpal_status_t Returns status code indicating success or failure of the operation. ZPAL_STATUS_OK if the operation was successful.