Skip to content

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.
Back to top