Wirepas SDK
wms_radio_config.h File Reference

Detailed Description

Application library for radio power and front end module control.

Library services are accessed via lib_radio_cfg handle.

Definition in file wms_radio_config.h.

Go to the source code of this file.

Typedefs

typedef void(* app_lib_radio_cfg_fem_set_power_cb_f) (uint8_t power_index)
 Callback function to set radio TX power. More...
 
typedef void(* app_lib_radio_cfg_fem_cmd_cb_f) (uint8_t femcmd)
 Callback function to control FEM state. More...
 
typedef app_res_e(* app_lib_radio_cfg_fem_setup_f) (const app_lib_radio_cfg_fem_t *fem_cfg)
 Setup FEM control. More...
 
typedef app_res_e(* app_lib_radio_cfg_power_setup_f) (const app_lib_radio_cfg_power_t *power_cfg)
 Setup radio configuration / power level settings. More...
 
typedef app_res_e(* app_lib_radio_cfg_pa_setup_f) (const void *pa_cfg)
 Setup radio PA configuration, relevant only for platforms that require PA configuration (e.g. SiLabs) More...
 

Data Structures

struct  app_lib_radio_cfg_fem_timings_t
 FEM state transition delays. More...
 
struct  app_lib_radio_cfg_fem_t
 Radio FEM configuration structure from application to firmware. More...
 
struct  app_lib_radio_cfg_tx_pwr_lvl_t
 Definition for single TX power level. More...
 
struct  app_lib_radio_cfg_power_t
 Radio FEM configuration structure from application to firmware. More...
 
struct  app_lib_radio_cfg_t
 List of library functions. More...
 

Enumerations

enum  app_lib_radio_cfg_femcmd_e {
  APP_LIB_RADIO_CFG_FEM_RX_ON, APP_LIB_RADIO_CFG_FEM_TX_ON, APP_LIB_RADIO_CFG_FEM_STANDBY, APP_LIB_RADIO_CFG_FEM_PWR_ON,
  APP_LIB_RADIO_CFG_FEM_PWR_OFF
}
 FEM control command from firmware to application. More...
 

Macros

#define APP_LIB_RADIO_CFG_NAME   0x6e080bb7
 Library symbolic name. More...
 
#define APP_LIB_RADIO_CFG_VERSION   0x200
 Maximum supported library version. More...
 
#define APP_LIB_RADIO_CFG_POWER_MAX_CNT   10
 Maximum amount of configurable power levels. More...
 
#define APP_LIB_RADIO_CFG_CURRENT_MIN   1
 Minimum configured radio current (10 x mA) More...
 
#define APP_LIB_RADIO_CFG_CURRENT_MAX   1000
 Maximum configured radio current (10 x mA) More...
 

Typedef Documentation

◆ app_lib_radio_cfg_fem_cmd_cb_f

typedef void(* app_lib_radio_cfg_fem_cmd_cb_f) (uint8_t femcmd)

Callback function to control FEM state.

This should be fast and not use other services. In some cases may be called from interrupt context. Customers are responsible for actual control strategy. Can be empty function if nothing to do. It is set via lib_radiocfg->femSetup() in femCmd argument

Parameters
femcmdCommand to set FEM state, app_lib_radio_cfg_femcmd_e For future compatibility, do nothing if command is not recognized.

Definition at line 150 of file wms_radio_config.h.

◆ app_lib_radio_cfg_fem_set_power_cb_f

typedef void(* app_lib_radio_cfg_fem_set_power_cb_f) (uint8_t power_index)

Callback function to set radio TX power.

This is called by firmware to tell the next TX power level. Never called when the TX is already active. Must not activate TX state. Sets power level of FEM PA (immediately or when TX actually starts). Can be empty function if nothing to do (no PA or fixed PA). It is set via lib_radiocfg->femSetup() in setPower argument

Note
Firmware sets the radio power level. Rationale: In some systems it would be impossible to access the internal radio from here.
Parameters
Powerlevel 0...APP_LIB_RADIO_CFG_POWER_MAX_CNT. Used as index for power configuration structures.

Definition at line 134 of file wms_radio_config.h.

◆ app_lib_radio_cfg_fem_setup_f

typedef app_res_e(* app_lib_radio_cfg_fem_setup_f) (const app_lib_radio_cfg_fem_t *fem_cfg)

Setup FEM control.

Parameters
fem_cfgPointer to configuration (defined in application)
Returns
Result code, APP_RES_OK if successful

Definition at line 221 of file wms_radio_config.h.

◆ app_lib_radio_cfg_pa_setup_f

typedef app_res_e(* app_lib_radio_cfg_pa_setup_f) (const void *pa_cfg)

Setup radio PA configuration, relevant only for platforms that require PA configuration (e.g. SiLabs)

Parameters
pa_cfgPointer to configuration defined by Vendor SDK. Refer to the Vendor SDK for type declarations. The stack assumes the format is what the silicon vendor uses to configure PA. As an example, for SiLabs the type is: RAIL_TxPowerConfig_t
Returns
Result code, APP_RES_OK if successful

Definition at line 242 of file wms_radio_config.h.

◆ app_lib_radio_cfg_power_setup_f

typedef app_res_e(* app_lib_radio_cfg_power_setup_f) (const app_lib_radio_cfg_power_t *power_cfg)

Setup radio configuration / power level settings.

Parameters
power_cfgPointer to configuration (defined in application)
Returns
Result code, APP_RES_OK if successful

Definition at line 230 of file wms_radio_config.h.


Data Structure Documentation

◆ app_lib_radio_cfg_fem_timings_t

struct app_lib_radio_cfg_fem_timings_t

FEM state transition delays.

Discrete delays between between different FEM states. The stack needs to know these values in order to command the FEM to correct state so it is ready and stabilized when a TX/RX operation begins.

Typically these values can all be set to 0, if the FEM stabilization can be assumed instantaneous (under a few microseconds).

However, if the FEM PA/LNA takes a significant amount of time to stabilize (in the order of tens of microseconds) then the application must provide the delay values here, otherwise the FEM PA/LNA will not be stable when TX/RX begins, and the RF performance will suffer.

Definition at line 92 of file wms_radio_config.h.

Data Fields
bool delay_values_set

Set this to true, if values are valid. If this is false, stack will assume FEM is fast enough to not care about state transition delays

uint32_t pd_to_sby

Delay when moving from APP_LIB_RADIO_CFG_FEM_PWR_OFF state to APP_LIB_RADIO_CFG_FEM_STANDBY state. The meaning of the value is to estimate how long it takes to move from the lowest power FEM state to a state where the FEM is ready to enter TX or RX state. The stack uses APP_LIB_RADIO_CFG_FEM_PWR_ON only as an intermediate state.

uint32_t sby_to_rx

Delay when moving from APP_LIB_RADIO_CFG_FEM_STANDBY to APP_LIB_RADIO_CFG_FEM_RX_ON, that is how much time the FEM LNA power output needs to stabilize. The stack will command the FEM to enter RX state at least this amount of time prior to commanding the radio to RX state

uint32_t sby_to_tx

Delay when moving from APP_LIB_RADIO_CFG_FEM_STANDBY to APP_LIB_RADIO_CFG_FEM_TX_ON, that is how much time the FEM PA power output needs to stabilize. The stack will command the FEM to enter TX state at least this amount of time prior to commanding the radio to TX state

◆ app_lib_radio_cfg_fem_t

struct app_lib_radio_cfg_fem_t

Radio FEM configuration structure from application to firmware.

Address given as a parameter to femSetup.

Definition at line 157 of file wms_radio_config.h.

Data Fields
app_lib_radio_cfg_fem_cmd_cb_f femCmd

Callback from firmware to application

app_lib_radio_cfg_fem_timings_t femTimings

FEM timings for stack, app_lib_radio_cfg_fem_timings_t

app_lib_radio_cfg_fem_set_power_cb_f setPower

Callback from firmware to application

◆ app_lib_radio_cfg_tx_pwr_lvl_t

struct app_lib_radio_cfg_tx_pwr_lvl_t

Definition for single TX power level.

Information needed by firmware to correctly configure TX a power level on the radio, and calculate e.g. relative energy usage from TX power level power consumption.

Used in app_lib_radio_cfg_power_t::powers[]-table.

Definition at line 176 of file wms_radio_config.h.

Data Fields
uint16_t tx_current

Transmit current, unit [mA x 10]

int8_t tx_output_dbm

Nominal output power , nearest integer dBm

uint32_t tx_power_raw

Raw power setting to radio register. Used by firmware.

uint8_t value_set

1: value set for index, 0: index empty

◆ app_lib_radio_cfg_power_t

struct app_lib_radio_cfg_power_t

Radio FEM configuration structure from application to firmware.

This is given as a parameter for lib_radiocfg->powerSetup() in power_cfg argument. All tables are indexed by power level. All fields must be filled realistically.

Definition at line 197 of file wms_radio_config.h.

Data Fields
uint8_t power_count

Amount of power levels configured

app_lib_radio_cfg_tx_pwr_lvl_t powers[10]

TX power level configuration / table. Requirements:

  • At least 1 power level must be set, recommendation is to use at least 8 power levels
  • Power levels MUST be in ascending order
uint16_t rx_current

RX state current, unit [mA x 10]

int8_t rx_gain_db

RX LNA gain or 0 [dB]

◆ app_lib_radio_cfg_t

struct app_lib_radio_cfg_t

List of library functions.

Definition at line 247 of file wms_radio_config.h.

Data Fields
app_lib_radio_cfg_fem_setup_f femSetup

Setup FEM control, works only when stack is in APP_LIB_STATE_STOPPED state

app_lib_radio_cfg_pa_setup_f paSetup

Setup radio PA configuration, works only when stack is in APP_LIB_STATE_STOPPED state. This is relevant only on platforms that require explicit radio PA configuration (e.g. SiLabs)

app_lib_radio_cfg_power_setup_f powerSetup

Setup custom radio power table, works only when stack is in APP_LIB_STATE_STOPPED state

Enumeration Type Documentation

◆ app_lib_radio_cfg_femcmd_e

FEM control command from firmware to application.

Used as parameter for app_lib_radio_cfg_fem_cmd_cb_f

Note
FEM driver may not need to to implement these literally. It is often possible to use lazy strategies.

Example: If power consumption is irrelevant, FEM may be kept in RX state by default, and in TX state only when APP_LIB_RADIO_CFG_FEM_TX_ON is asked.

Example: FEM may not have true power off / power on states but only some kind of low-current standby (non-active) state.

Enumerator
APP_LIB_RADIO_CFG_FEM_RX_ON 

FEM receiver on

APP_LIB_RADIO_CFG_FEM_TX_ON 

FEM transmitter on

APP_LIB_RADIO_CFG_FEM_STANDBY 

FEM low power sleep mode (STANDBY / SBY)

APP_LIB_RADIO_CFG_FEM_PWR_ON 

FEM power on, this state is mostly intermediate between OFF and SBY

APP_LIB_RADIO_CFG_FEM_PWR_OFF 

FEM power off

Definition at line 63 of file wms_radio_config.h.

Macro Definition Documentation

◆ APP_LIB_RADIO_CFG_CURRENT_MAX

#define APP_LIB_RADIO_CFG_CURRENT_MAX   1000

Maximum configured radio current (10 x mA)

FCC allow maximum power for 2.4GHz to be roughly 600mA, so to be sure that we don't block the users from doing what they want, but also have some reasonable limit to root out obviously invalid values, we set the upper limit for current to be 10A.

Definition at line 46 of file wms_radio_config.h.

◆ APP_LIB_RADIO_CFG_CURRENT_MIN

#define APP_LIB_RADIO_CFG_CURRENT_MIN   1

Minimum configured radio current (10 x mA)

Definition at line 36 of file wms_radio_config.h.

◆ APP_LIB_RADIO_CFG_NAME

#define APP_LIB_RADIO_CFG_NAME   0x6e080bb7

Library symbolic name.

"RADCFG"

Definition at line 27 of file wms_radio_config.h.

◆ APP_LIB_RADIO_CFG_POWER_MAX_CNT

#define APP_LIB_RADIO_CFG_POWER_MAX_CNT   10

Maximum amount of configurable power levels.

Definition at line 33 of file wms_radio_config.h.

◆ APP_LIB_RADIO_CFG_VERSION

#define APP_LIB_RADIO_CFG_VERSION   0x200

Maximum supported library version.

Definition at line 30 of file wms_radio_config.h.

APP_LIB_RADIO_CFG_FEM_PWR_OFF
@ APP_LIB_RADIO_CFG_FEM_PWR_OFF
Definition: wms_radio_config.h:74
APP_LIB_RADIO_CFG_FEM_STANDBY
@ APP_LIB_RADIO_CFG_FEM_STANDBY
Definition: wms_radio_config.h:70
APP_LIB_RADIO_CFG_FEM_PWR_ON
@ APP_LIB_RADIO_CFG_FEM_PWR_ON
Definition: wms_radio_config.h:72
APP_LIB_RADIO_CFG_FEM_RX_ON
@ APP_LIB_RADIO_CFG_FEM_RX_ON
Definition: wms_radio_config.h:66
APP_LIB_RADIO_CFG_FEM_TX_ON
@ APP_LIB_RADIO_CFG_FEM_TX_ON
Definition: wms_radio_config.h:68
app_lib_radio_cfg_femcmd_e
app_lib_radio_cfg_femcmd_e
FEM control command from firmware to application.
Definition: wms_radio_config.h:63