Radio Frontend Control¶

Structs¶

mira_net_frontend_config_t¶

Control structure for PA/front-end.

Front-end configuration:

gain_cb_*: gain values in cB for different FEM modes. Used to estimate the output power for fulfilling regulatory and power requirements.
gpio_*: the pins to control front-end modes and antenna selection. Set unused GPIO to MIRA_GPIO_PIN_UNDEFINED.
pin_values_*: the pin levels required to select a mode. Each bit of such a member variable corresponds to an element of gpio_mode_control[]. For example: pin_values_bypass_tx bit 0 specifies the required level of pin gpio_mode_control[0] for mode bypass_tx. 1 means high, 0 means low.
pin_values_antsel: pin levels required to select an antenna. Only bit 0 is used. pin_values_antsel[0] bit 0 is the pin level of gpio_antsel for selecting antenna 0. pin_values_antsel[1] bit 0 is the pin level of gpio_antsel for selecting antenna 1.
pin_values_antsel_idle: bit 0 is the pin level required for gpio_antsel in idle mode.

Name	Type	Description
`gain_cb_bypass_tx`	`int16_t`	gain in bypass TX [cB].
`gain_cb_bypass_rx`	`int16_t`	gain in bypass RX [cB].
`gain_cb_active_tx`	`int16_t`	gain in PA active TX [cB].
`gain_cb_active_rx`	`int16_t`	gain in PA active RX [cB].
`gpio_mode_control`	`mira_gpio_pin_t[4]`	Set unused GPIO pins to MIRA_GPIO_PIN_UNDEFINED GPIO for PA mode control.
`gpio_antsel`	`mira_gpio_pin_t`	GPIO for antenna selection.
`pin_values_bypass_tx`	`uint8_t`	GPIO levels to select bypass TX mode.
`pin_values_bypass_rx`	`uint8_t`	GPIO levels to select bypass RX mode.
`pin_values_active_tx`	`uint8_t`	GPIO levels to select PA active TX mode.
`pin_values_active_rx`	`uint8_t`	GPIO levels to select PA active RX mode.
`pin_values_idle`	`uint8_t`	GPIO levels to set the PA in idle mode.
`pin_values_antsel`	`uint8_t[2]`	GPIO levels required for gpio_antsel to select antenna. Only bit 0 is used.
`pin_values_antsel_idle`	`uint8_t`	GPIO levels required for gpio_antsel to enter idle mode.

Functions¶

mira_net_set_low_power¶

mira_status_t mira_net_set_low_power(void);

Set low power mode.

Disable the radio front-end if present, lowering output power and power consumption.

Return value¶

Name	Description
MIRA_SUCCESS	Low power mode set successfully.
MIRA_ERROR_UNKNOWN	An unknown error occurred.
MIRA_RADIO_ERROR	Radio driver reported an error.
MIRA_ERROR_INVALID_VALUE	Value invalid.
MIRA_ERROR_NOT_SUPPORTED	Function not supported.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_net_set_high_power¶

mira_status_t mira_net_set_high_power(void);

Set high power mode.

Enable the radio front-end if present, increasing output power and power consumption.

Return value¶

Name	Description
MIRA_SUCCESS	High power mode set successfully.
MIRA_ERROR_UNKNOWN	An unknown error occurred.
MIRA_RADIO_ERROR	Radio driver reported an error.
MIRA_ERROR_INVALID_VALUE	Value invalid.
MIRA_ERROR_NOT_SUPPORTED	Function not supported.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_net_set_txpower¶

mira_status_t mira_net_set_txpower(int16_t power_cbm);

Set radio output power.

Set the output power of the chip, without accounting for antenna gain. If in high power mode, and the TX power passed as parameter requires it, dynamically enable the radio front-end if any.

Power levels are quantized and therefore rounded down to the nearest available power level. The available power level that was set can be obtained through mira_net_get_actual_txpower().

All power values are in cBm, or centi-bel-mW, which is tenth of dBm. For example, 100 mW is 20.0 dBm, which is 200 cBm. The proper value to pass to the function is therefore 200.

Note

Also applies for BLE beacons, which are limited to 100 cBm by the BLE 4 standard. If a value above 100 cBm is requested, that value will be valid for Mira network messages, while BLE beacons will be sent at 100 cBm. If a value below 100 cBm is set, that value will be valid for both Mira network messages and BLE beacons.

Parameters¶

Name	Description
power_cbm	Desired output power in cBm.

Return value¶

Name	Description
MIRA_SUCCESS	Output power set successfully.
MIRA_ERROR_UNKNOWN	An unknown error occurred.
MIRA_RADIO_ERROR	Radio driver reported an error.
MIRA_ERROR_INVALID_VALUE	Invalid output power.
MIRA_ERROR_NOT_SUPPORTED	Function not supported.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_net_get_actual_txpower¶

mira_status_t mira_net_get_actual_txpower(int16_t *power_cbm);

Get actual radio output power.

Get the output power for the current configuration.

Since output power may be quantized, and front-end might be active or inactive, the actual output power may differ from the requested.

Parameters¶

Name	Description
power_cbm	pointer to an int16_t of where to store the output power value.

Return value¶

Name	Description
MIRA_SUCCESS	Output power gotten successfully.
MIRA_ERROR_UNKNOWN	An unknown error occurred.
MIRA_RADIO_ERROR	Radio driver reported an error.
MIRA_ERROR_INVALID_VALUE	Invalid output power.
MIRA_ERROR_NOT_SUPPORTED	Function not supported.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_net_set_antenna¶

mira_status_t mira_net_set_antenna(mira_net_antenna_t antenna);

Set active antenna.

The antenna defaults to the onboard antenna. If setting an antenna the hardware doesn't support, it will default back to the onboard antenna.

Parameters¶

Name	Description
antenna	Index of preferred antenna. Controls the pin defined in the front-end control structure. mira_net_frontend_config_t::gpio_antsel.

Return value¶

Name	Description
MIRA_SUCCESS	Antenna selected successfully.
MIRA_ERROR_UNKNOWN	An unknown error occurred.
MIRA_RADIO_ERROR	Radio driver reported an error.
MIRA_ERROR_INVALID_VALUE	Invalid antenna.
MIRA_ERROR_NOT_SUPPORTED	Function not supported.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_net_set_active_frontend_cfg¶

mira_status_t mira_net_set_active_frontend_cfg(const mira_net_frontend_config_t *fe_config);

Set frontend config. Overwrites configuration set by sysconfig, factory config or earlier invocations of this function.

Note

Must be called before mira_net_init

Parameters¶

Name	Description
fe_config	Pointer to a complete frontend config.

Return value¶

Name	Description
MIRA_SUCCESS	Successfully set frontend config.
MIRA_INVALID_VALUE	Incomplete frontend config provided.
MIRA_ERROR_ALREADY_INITIALIZED	mira_net_init has already been called.

mira_net_get_active_frontend_cfg¶

mira_status_t mira_net_get_active_frontend_cfg(mira_net_frontend_config_t *fe_dst);

Get the currently active frontend config.

Note

Values returned from this function shall only be used for diagnostics or debugging!

Parameters¶

Name	Description
fe_dst	Pointer to storage for retrieved active frontend config.

Return value¶

Name	Description
MIRA_SUCCESS	Successfully retrieved active frontend config.
MIRA_ERROR_INVALID_VALUE	No storage provided for frontend config.