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

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

femcmd

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

Definition at line 137 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

Power

level 0...APP_LIB_RADIO_CFG_POWER_MAX_CNT. Used as index for power configuration structures.

Definition at line 121 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_cfg

Pointer to configuration (defined in application)

Returns

Result code, APP_RES_OK if successful

Definition at line 208 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_cfg

Pointer 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 229 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_cfg

Pointer to configuration (defined in application)

Returns

Result code, APP_RES_OK if successful

Definition at line 217 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 79 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 144 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_femtimings_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 163 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 184 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_dbm	RX LNA gain or 0 [dB]

app_lib_radio_cfg_t

struct app_lib_radio_cfg_t

List of library functions.

Definition at line 234 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

enum 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_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 50 of file wms_radio_config.h.

{
    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,
} app_lib_radio_cfg_femcmd_e;

Macro Definition Documentation

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.