zpal_radio.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: Silicon Laboratories Inc. <https://www.silabs.com/>
//
// SPDX-License-Identifier: BSD-3-Clause
 
#ifndef ZPAL_RADIO_H_
#define ZPAL_RADIO_H_
 
#include <stdbool.h>
#include <stdint.h>
#include "zpal_status.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define ZPAL_RADIO_INVALID_RSSI_DBM (-128)
 
#define ZPAL_RADIO_RSSI_NOT_AVAILABLE (127)
 
#define ZW_TX_POWER_10DBM  100 
#define ZW_TX_POWER_14DBM  140 
#define ZW_TX_POWER_20DBM  200 
 
#define ZPAL_RADIO_NUM_CHANNELS                 3 
#define ZPAL_RADIO_NUM_CHANNELS_LR_CH_CFG_1_2   4 
#define ZPAL_RADIO_NUM_CHANNELS_LR_CH_CFG3      2 
 
 
typedef uint16_t node_id_t;
 
typedef int16_t zpal_tx_power_t;
 
typedef enum
{
  ZPAL_RADIO_MODE_NON_LISTENING,    
  ZPAL_RADIO_MODE_ALWAYS_LISTENING, 
  ZPAL_RADIO_MODE_FLIRS,            
} zpal_radio_mode_t;
 
typedef enum
{
  ZPAL_RADIO_WAKEUP_NEVER_LISTEN,  
  ZPAL_RADIO_WAKEUP_ALWAYS_LISTEN, 
  ZPAL_RADIO_WAKEUP_EVERY_250ms,   
  ZPAL_RADIO_WAKEUP_EVERY_1000ms,  
} zpal_radio_wakeup_t;
 
typedef enum
{
  ZPAL_RADIO_CRC_NONE,         
  ZPAL_RADIO_CRC_8_BIT_XOR,    
  ZPAL_RADIO_CRC_16_BIT_CCITT, 
} zpal_radio_crc_t;
 
typedef enum
{
  ZPAL_RADIO_SPEED_UNDEFINED, 
  ZPAL_RADIO_SPEED_9600,      
  ZPAL_RADIO_SPEED_40K,       
  ZPAL_RADIO_SPEED_100K,      
  ZPAL_RADIO_SPEED_100KLR,    
} zpal_radio_speed_t;
 
typedef enum
{
  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,   
} zpal_radio_lr_channel_t;
 
typedef enum
{
  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,    
} zpal_radio_zwave_channel_t;
 
typedef enum
{
  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, 
} zpal_radio_protocol_mode_t;
 
 
typedef enum
{
  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  
} zpal_radio_lr_channel_config_t;
 
typedef enum
{
  REGION_2CH_FIRST = 0,                             
  REGION_EU = REGION_2CH_FIRST,                     
  REGION_US,                                        
  REGION_ANZ,                                       
  REGION_HK,                                        
  REGION_DEPRECATED_4,                              
                                                    // Malaysian products now use ANZ region.
  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,                            
} zpal_radio_region_t;
 
#define REGION_2CH_NUM = (REGION_2CH_END - REGION_2CH_FIRST)    
#define REGION_3CH_NUM = (REGION_3CH_END - REGION_3CH_FIRST)    
 
typedef enum
{
  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,        
} zpal_radio_tx_power_t;
 
typedef struct
{
  zpal_radio_speed_t speed;              
  zpal_radio_zwave_channel_t channel_id; 
  zpal_radio_crc_t crc;                  
  uint8_t preamble;                      
  uint8_t preamble_length;               
  uint8_t start_of_frame;                
  uint8_t repeats;                       
} zpal_radio_transmit_parameter_t;
 
typedef enum
{
  ZPAL_RADIO_HEADER_TYPE_2CH,       
  ZPAL_RADIO_HEADER_TYPE_3CH,       
  ZPAL_RADIO_HEADER_TYPE_LR,        
  ZPAL_RADIO_HEADER_TYPE_UNDEFINED, 
} zpal_radio_header_type_t;
 
typedef struct
{
  zpal_radio_speed_t speed;                       
  zpal_radio_zwave_channel_t channel_id;          
  zpal_radio_header_type_t channel_header_format; 
  int8_t rssi;                                    
} zpal_radio_rx_parameters_t;
 
typedef enum
{
  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             
} zpal_radio_event_t;
 
typedef enum
{
  ZPAL_RADIO_STATUS_IDLE,                       
  ZPAL_RADIO_STATUS_RX,                         
  ZPAL_RADIO_STATUS_TX,                         
  ZPAL_RADIO_STATUS_TX_BEAM,                    
  ZPAL_RADIO_STATUS_RX_BEAM                     
} zpal_radio_status_t;
 
typedef void (*zpal_radio_callback_t)(zpal_radio_event_t event);
 
typedef struct
{
  uint8_t frame_content_length; 
  uint8_t frame_content[];      
} zpal_radio_receive_frame_t;
 
typedef void (*zpal_radio_receive_handler_t)(zpal_radio_rx_parameters_t *rx_parameters, zpal_radio_receive_frame_t *frame);
 
typedef struct
{
  uint32_t tx_frames;          
  uint32_t tx_lbt_back_offs;   
  uint32_t rx_frames;          
  uint32_t rx_lrc_errors;      
  uint32_t rx_crc_errors;      
  uint32_t rx_foreign_home_id; 
  uint32_t tx_time_channel_0;  
  uint32_t tx_time_channel_1;  
  uint32_t tx_time_channel_2;  
  uint32_t tx_time_channel_3;  
  uint32_t tx_time_channel_4;  
} zpal_radio_network_stats_t;
 
typedef struct
{
  uint32_t rf_channel_tx_frames;                  
  uint32_t rf_channel_tx_retries;                 
  uint32_t rf_channel_tx_lbt_failures;            
  uint32_t rf_channel_rx_foreign_homeid;          
  uint32_t rf_channel_rx_crc_error;               
  int8_t   rf_channel_background_rssi_average;    
  int8_t   rf_channel_end_device_rssi_average;    
} zpal_radio_rf_channel_statistic_t;
 
typedef struct
{
  zpal_radio_region_t region;                      
  zpal_radio_wakeup_t wakeup;                      
  zpal_radio_lr_channel_t primary_lr_channel;      
  bool lr_channel_auto_mode;                       
  zpal_radio_lr_channel_config_t active_lr_channel_config; 
  int8_t listen_before_talk_threshold;             
  zpal_tx_power_t tx_power_max;                    
  zpal_tx_power_t tx_power_adjust;                 
  zpal_tx_power_t tx_power_max_lr;                 
  uint8_t *home_id;                                
  zpal_radio_callback_t rx_cb;                     
  zpal_radio_callback_t tx_cb;                     
  zpal_radio_callback_t region_change_cb;          
  zpal_radio_callback_t assert_cb;                 
  zpal_radio_network_stats_t *network_stats;       
  uint8_t radio_debug_enable;                      
  zpal_radio_receive_handler_t receive_handler_cb; 
} zpal_radio_profile_t;
 
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);
 
void zpal_radio_init(zpal_radio_profile_t * const profile);
 
zpal_status_t zpal_radio_change_region(zpal_radio_region_t eRegion, zpal_radio_lr_channel_config_t eLrChCfg);
 
zpal_radio_region_t zpal_radio_get_region(void);
 
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);
 
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);
 
void zpal_radio_start_receive();
 
void zpal_radio_get_last_received_frame(void);
 
void zpal_radio_power_down(void);
 
zpal_radio_protocol_mode_t zpal_radio_get_protocol_mode(void);
 
zpal_radio_zwave_channel_t zpal_radio_get_last_beam_channel(void);
 
int8_t zpal_radio_get_last_beam_rssi(void);
 
void zpal_radio_set_lbt_level(uint8_t channel, int8_t level);
 
void zpal_radio_enable_rx_broadcast_beam(bool enable);
 
void zpal_radio_clear_tx_timers(void);
 
void zpal_radio_clear_network_stats(void);
 
void zpal_radio_rf_channel_statistic_clear(zpal_radio_zwave_channel_t zwavechannel);
 
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);
 
void zpal_radio_rf_channel_statistic_tx_frames(void);
 
void zpal_radio_rf_channel_statistic_tx_retries(void);
 
void zpal_radio_rf_channel_statistic_tx_lbt_failures(void);
 
void zpal_radio_rf_channel_statistic_background_rssi_average_update(zpal_radio_zwave_channel_t zwavechannel, int8_t rssi);
 
void zpal_radio_rf_channel_statistic_end_device_rssi_average_update(zpal_radio_zwave_channel_t zwavechannel, int8_t rssi);
 
zpal_status_t zpal_radio_get_background_rssi(uint8_t channel, int8_t *rssi);
 
zpal_tx_power_t zpal_radio_get_default_tx_power(void);
 
uint8_t zpal_radio_get_reduce_tx_power(void);
 
void zpal_radio_enable_flirs(void);
 
bool zpal_radio_is_flirs_enabled(void);
 
void zpal_radio_start_receive_after_power_down(bool wait_for_beam);
 
void zpal_radio_abort(void);
 
void zpal_radio_reset_after_beam_receive(bool start_receiver);
 
bool zpal_radio_is_fragmented_beam_enabled(void);
 
void zpal_radio_calibrate(void);
 
bool zpal_radio_is_lbt_enabled(void);
 
uint16_t zpal_radio_get_beam_startup_time(void);
 
node_id_t zpal_radio_get_beam_node_id(void);
 
zpal_tx_power_t zpal_radio_get_minimum_lr_tx_power(void);
 
zpal_tx_power_t zpal_radio_get_maximum_lr_tx_power(void);
 
bool zpal_radio_is_debug_enabled(void);
 
const zpal_radio_profile_t * zpal_radio_get_rf_profile(void);
 
zpal_radio_lr_channel_config_t zpal_radio_get_lr_channel_config(void);
 
zpal_radio_lr_channel_t zpal_radio_get_primary_long_range_channel(void);
 
void zpal_radio_set_primary_long_range_channel(zpal_radio_lr_channel_t channel);
 
bool zpal_radio_get_long_range_channel_auto_mode(void);
 
void zpal_radio_set_long_range_channel_auto_mode(bool enable);
 
void zpal_radio_set_long_range_lock(bool lock);
 
bool zpal_radio_is_long_range_locked(void);
 
bool zpal_radio_is_region_supported(const zpal_radio_region_t region);
 
int8_t zpal_radio_get_flirs_beam_tx_power(void);
 
bool zpal_radio_is_transmit_allowed(uint8_t channel, uint8_t frame_length, uint8_t frame_priority);
 
bool zpal_radio_attenuate(uint8_t adjust_tx_power);
 
zpal_tx_power_t zpal_radio_get_maximum_tx_power(void);
 
void zpal_radio_request_calibration(bool forced);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZPAL_RADIO_H_ */