RF 校准

[English]

ESP32-C2 的 RF 校准行为由以下两个配置项共同决定：

1. CONFIG_ESP_PHY_CALIBRATION_MODE：选择部分校准、全面校准或不校准。

2. CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE：控制是否在 RF 初始化过程中自动加载和保存 NVS 中的 PHY 校准数据。

RF 校准配置

CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE 控制是否在 RF 初始化过程中自动使用 NVS 中的 PHY 校准数据：

• 启用该选项时，系统会从 NVS 加载校准数据，普通启动时的校准方式由 CONFIG_ESP_PHY_CALIBRATION_MODE 决定。从 Deep-sleep 模式唤醒时，无论配置了哪种校准方式，系统都会优先选择不校准。如果 NVS 校准数据不存在或无效，系统会改为执行全面校准，并尝试将新数据存入 NVS。

• 禁用该选项时，CONFIG_ESP_PHY_CALIBRATION_MODE 不可配置，系统不自动加载或保存 NVS 校准数据，并始终执行全面校准。

启用 NVS 校准数据存储时，应在初始化 Wi-Fi 或 Bluetooth®/Bluetooth Low Energy 前调用 nvs_flash_init()。否则系统无法加载或保存校准数据，并会回退到全面校准。

部分校准

当前版本中，部分校准和全面校准在功能上等效，默认使用全面校准。

全面校准

全面校准是 CONFIG_ESP_PHY_CALIBRATION_MODE 的默认选项。此外，在以下情况下，系统也会强制执行全面校准：

1. CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE 被禁用。

2. NVS 未初始化，或者存储校准数据的 NVS 分区或 phy 命名空间不存在。

3. 存储校准数据的 NVS 分区已擦除。

4. 硬件 MAC 地址变更。

5. PHY 库使用的校准数据格式版本变更。

6. 从 NVS 加载的 RF 校准数据长度不正确、校验失败或已经过期。

启用 CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE 时，如果 NVS 数据加载失败，系统会执行全面校准并尝试保存新数据；如果 NVS 数据加载成功，则只有在 PHY 库报告校准数据校验失败或已经过期时，才会更新 NVS 中的数据。

如需强制触发全面校准，可以使用以下方法：

1. 如果不介意擦除 NVS 分区中的所有数据，那么擦除 NVS 分区是最简单的方法。

2. 在初始化 Wi-Fi 和 Bluetooth®/Bluetooth Low Energy 前，根据某些条件（例如，在某些诊断模式下提供的选项）调用 API esp_phy_erase_cal_data_in_nvs()，此时仅会擦除 NVS 分区的 PHY 命名空间。

不校准

不校准仅适用于设备从 Deep-sleep 模式唤醒的场景。启用 CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE 后，从 Deep-sleep 模式唤醒时，系统会自动将校准方式设置为不校准，无需手动修改 CONFIG_ESP_PHY_CALIBRATION_MODE。如果此时无法从 NVS 加载有效的校准数据，系统仍会回退到全面校准。

不建议将 CONFIG_ESP_PHY_CALIBRATION_MODE 配置为不校准。这样配置后，只要 NVS 校准数据有效，普通冷启动也会跳过 RF 校准，可能导致 RF 性能出现问题。

配置组合总结

当前版本中，部分校准和全面校准在功能上等效。以下总结中的 PARTIAL、FULL 和 NONE 表示传递给 PHY 库的校准模式：

• 启用 CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE 并选择 FULL：

  • 普通启动且 NVS 校准数据有效：使用 FULL。

  • 从 Deep-sleep 模式唤醒且 NVS 校准数据有效：使用 NONE。

  • NVS 校准数据无效或加载失败：使用 FULL，并尝试保存新校准数据。

• 启用 CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE 并选择 PARTIAL：当前版本中的行为与选择 FULL 相同。

• 启用 CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE 并选择 NONE：

  • 普通启动且 NVS 校准数据有效：使用 NONE。

  • 从 Deep-sleep 模式唤醒且 NVS 校准数据有效：使用 NONE。

  • NVS 校准数据无效或加载失败：使用 FULL，并尝试保存新校准数据。

• 禁用 CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE：

  • CONFIG_ESP_PHY_CALIBRATION_MODE 不可配置，其值会被忽略。

  • 所有场景均使用 FULL。

  • 不自动加载或保存 NVS 校准数据。

  • 从 Deep-sleep 模式唤醒时也使用 FULL。

PHY 初始化数据

PHY 初始化数据用于 RF 校准，通过以下两种方法，可以获取 PHY 初始化数据。

一是使用默认初始化数据，该数据位于头文件 components/esp_phy/esp32c2/include/phy_init_data.h 中。默认初始化数据会在编译后嵌入到应用程序的二进制文件，然后存储在只读存储器 (DROM) 中。要使用默认的初始化数据，请前往 menuconfig 并禁用 CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION。

二是将初始化数据存储在 PHY 数据分区中。默认的分区表中已经包含了 PHY 数据分区，但是使用自定义分区表时，请确保在自定义分区表中包含一个 PHY 数据分区（类型：data，子类型：phy）。无论使用自定义分区表还是默认分区表，只要初始化数据存储在分区中，就需要将其烧录到相应的分区中，否则运行时可能会出现错误。如果想要使用存储在分区中的初始化数据，请前往 menuconfig 并启用选项 CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION。

API 参考

Header File

• components/esp_phy/include/esp_phy_init.h

• This header file can be included with:

  #include "esp_phy_init.h"
  

• This header file is a part of the API provided by the esp_phy component. To declare that your component depends on esp_phy, add the following to your CMakeLists.txt:

  REQUIRES esp_phy
  

  or

  PRIV_REQUIRES esp_phy
  

Functions

const esp_phy_init_data_t *esp_phy_get_init_data(void)

Get PHY init data.

If "Use a partition to store PHY init data" option is set in menuconfig, This function will load PHY init data from a partition. Otherwise, PHY init data will be compiled into the application itself, and this function will return a pointer to PHY init data located in read-only memory (DROM).

If "Use a partition to store PHY init data" option is enabled, this function may return NULL if the data loaded from flash is not valid.

备注

Call esp_phy_release_init_data to release the pointer obtained using this function after the call to esp_wifi_init.

返回:

pointer to PHY init data structure

void esp_phy_release_init_data(const esp_phy_init_data_t *data)

Release PHY init data.

参数:

data -- pointer to PHY init data structure obtained from esp_phy_get_init_data function

esp_err_t esp_phy_load_cal_data_from_nvs(esp_phy_calibration_data_t *out_cal_data)

Function called by esp_phy_load_cal_and_init to load PHY calibration data.

This is a convenience function which can be used to load PHY calibration data from NVS. Data can be stored to NVS using esp_phy_store_cal_data_to_nvs function.

If calibration data is not present in the NVS, or data is not valid (was obtained for a chip with a different MAC address, or obtained for a different version of software), this function will return an error.

参数:

out_cal_data -- pointer to calibration data structure to be filled with loaded data.

返回:

ESP_OK on success

esp_err_t esp_phy_store_cal_data_to_nvs(const esp_phy_calibration_data_t *cal_data)

Function called by esp_phy_load_cal_and_init to store PHY calibration data.

This is a convenience function which can be used to store PHY calibration data to the NVS. Calibration data is returned by esp_phy_load_cal_and_init function. Data saved using this function to the NVS can later be loaded using esp_phy_store_cal_data_to_nvs function.

参数:

cal_data -- pointer to calibration data which has to be saved.

返回:

ESP_OK on success

esp_err_t esp_phy_erase_cal_data_in_nvs(void)

Erase PHY calibration data which is stored in the NVS.

This is a function which can be used to trigger full calibration as a last-resort remedy if partial calibration is used. It can be called in the application based on some conditions (e.g. an option provided in some diagnostic mode).

返回:

ESP_OK on success

返回:

others on fail. Please refer to NVS API return value error number.

void esp_phy_enable(esp_phy_modem_t modem)

Enable PHY and RF module.

PHY and RF module should be enabled in order to use WiFi or BT. Now PHY and RF enabling job is done automatically when start WiFi or BT. Users should not call this API in their application.

参数:

modem -- the modem to call the phy enable.

void esp_phy_disable(esp_phy_modem_t modem)

Disable PHY and RF module.

PHY module should be disabled in order to shutdown WiFi or BT. Now PHY and RF disabling job is done automatically when stop WiFi or BT. Users should not call this API in their application.

参数:

modem -- the modem to call the phy disable.

void esp_btbb_enable(void)

Enable BTBB module.

BTBB module should be enabled in order to use IEEE802154 or BT. Now BTBB enabling job is done automatically when start IEEE802154 or BT. Users should not call this API in their application.

void esp_btbb_disable(void)

Disable BTBB module.

Disable BTBB module, used by IEEE802154 or Bluetooth. Users should not call this API in their application.

void esp_phy_load_cal_and_init(void)

Load calibration data from NVS and initialize PHY and RF module.

void esp_phy_modem_init(uint8_t modem)

Initialize backup memory for Phy power up/down.

参数:

modem -- Modem calling phy retention

void esp_phy_modem_deinit(uint8_t modem)

Deinitialize backup memory for Phy power up/down Set phy_init_flag if all modems deinit on ESP32C3.

参数:

modem -- Modem calling phy retention

void esp_phy_common_clock_enable(void)

Enable WiFi/BT common clock.

void esp_phy_common_clock_disable(void)

Disable WiFi/BT common clock.

int64_t esp_phy_rf_get_on_ts(void)

Get the time stamp when PHY/RF was switched on.

返回:

return 0 if PHY/RF is never switched on. Otherwise return time in microsecond since boot when phy/rf was last switched on

esp_err_t esp_phy_update_country_info(const char *country)

Update the corresponding PHY init type according to the country code of Wi-Fi.

参数:

country -- country code

返回:

ESP_OK on success.

返回:

esp_err_t code describing the error on fail

char *get_phy_version_str(void)

Get PHY lib version.

返回:

PHY lib version.

void phy_init_param_set(uint8_t param)

Set PHY init parameters.

参数:

param -- is 1 means combo module

void phy_wifi_enable_set(uint8_t enable)

Wi-Fi RX enable.

参数:

enable -- True for enable wifi receiving mode as default, false for closing wifi receiving mode as default.

void esp_wifi_bt_power_domain_on(void)

Power on Bluetooth Wi-Fi power domain.

void esp_wifi_bt_power_domain_off(void)

Power off Bluetooth Wi-Fi power domain.

Structures

struct esp_phy_init_data_t

Structure holding PHY init parameters.

Public Members

uint8_t params[128]

opaque PHY initialization parameters

struct esp_phy_calibration_data_t

Opaque PHY calibration data.

Public Members

uint8_t version[4]

PHY version

uint8_t mac[6]

The MAC address of the station

uint8_t opaque[1894]

calibration data

Enumerations

enum esp_phy_modem_t

PHY enable or disable modem.

Values:

enumerator PHY_MODEM_WIFI

PHY modem WIFI

enumerator PHY_MODEM_BT

PHY modem BT

enumerator PHY_MODEM_IEEE802154

PHY modem IEEE802154

enumerator PHY_MODEM_MAX

Don't use it. Used by ESP_PHY_MODEM_COUNT_MAX

enum esp_phy_calibration_mode_t

PHY calibration mode.

Values:

enumerator PHY_RF_CAL_PARTIAL

Do part of RF calibration. This should be used after power-on reset.

enumerator PHY_RF_CAL_NONE

Don't do any RF calibration. This mode is only suggested to be used after deep sleep reset.

enumerator PHY_RF_CAL_FULL

Do full RF calibration. Produces best results, but also consumes a lot of time and current. Suggested to be used once.

Header File

• components/esp_phy/include/esp_phy_cert_test.h

• This header file can be included with:

  #include "esp_phy_cert_test.h"
  

• This header file is a part of the API provided by the esp_phy component. To declare that your component depends on esp_phy, add the following to your CMakeLists.txt:

  REQUIRES esp_phy
  

  or

  PRIV_REQUIRES esp_phy
  

Functions

void esp_wifi_power_domain_on(void)

Wifi power domain power on.

void esp_wifi_power_domain_off(void)

Wifi power domain power off.

void esp_phy_rftest_config(uint8_t conf)

Environment variable configuration.

参数:

conf -- Set to 1 to enter RF test mode.

void esp_phy_rftest_init(void)

RF initialization configuration.

void esp_phy_tx_contin_en(bool contin_en)

TX Continuous mode.

参数:

contin_en -- Set to true for continuous packet sending, which can be used for certification testing; Set to false to cancel continuous mode, which is the default mode and can be used for WLAN tester.

void esp_phy_cbw40m_en(bool en)

HT40/HT20 mode selection.

参数:

en -- Set to false to enter 11n HT20 mode; Set to true to enter 11n HT40 mode;

void esp_phy_wifi_tx(uint32_t chan, esp_phy_wifi_rate_t rate, int8_t backoff, uint32_t length_byte, uint32_t packet_delay, uint32_t packet_num)

Wi-Fi TX command.

参数:

• chan -- channel setting, 1~14;

• rate -- rate setting;

• backoff -- Transmit power attenuation, unit is 0.25dB. For example, 4 means that the power is attenuated by 1dB;

• length_byte -- TX packet length configuration, indicating PSDU Length, unit is byte;

• packet_delay -- TX packet interval configuration, unit is us;

• packet_num -- The number of packets sent, 0 means sending packets continuously, other values represent the number of packets to send.

void esp_phy_test_start_stop(uint8_t value)

Test start/stop command, used to stop transmitting or receiving state.

参数:

value -- Value should be set to 3 before TX/RX. Set value to 0 to end TX/RX state.

void esp_phy_wifi_rx(uint32_t chan, esp_phy_wifi_rate_t rate)

Wi-Fi RX command.

参数:

• chan -- channel setting, 1~14;

• rate -- rate setting;

void esp_phy_wifi_tx_tone(uint32_t start, uint32_t chan, uint32_t backoff)

Wi-Fi Carrier Wave(CW) TX command.

参数:

• start -- enable CW, 1 means transmit, 0 means stop transmitting;

• chan -- CW channel setting, 1~14;

• backoff -- CW power attenuation parameter, unit is 0.25dB. 4 indicates the power is attenuated by 1dB.

void esp_phy_ble_tx(uint32_t txpwr, uint32_t chan, uint32_t len, esp_phy_ble_type_t data_type, uint32_t syncw, esp_phy_ble_rate_t rate, uint32_t tx_num_in)

BLE TX command.

参数:

• txpwr -- Transmit power level. Tx power is about (level-8)*3 dBm, step is 3dB. Level 8 is around 0 dBm;

• chan -- channel setting, range is 0~39, corresponding frequency = 2402+chan*2;

• len -- Payload length setting, range is 0-255, unit is byte, 37 bytes is employed generally;

• data_type -- Data type setting;

• syncw -- Packet identification (need to be provided by the packet generator or instrument manufacturer), 0x71764129 is employed generally;

• rate -- rate setting;

• tx_num_in -- The number of packets sent, 0 means sending packets continuously, other values represent the number of packets to send.

void esp_phy_ble_rx(uint32_t chan, uint32_t syncw, esp_phy_ble_rate_t rate)

BLE RX command.

参数:

• chan -- channel selection, range is 0-39; Channels 0, 1, 2~10 correspond to 2404MHz, 2406MHz, 2408MHz~2424MHz respectively; Channels 11, 12, 13~36 correspond to 2428MHz, 2430MHz, 2432MHz~2478MHz respectively; Channel 37: 2402MHz, Channel 38: 2426MHz, Channel 39: 2480MHz;

• syncw -- Packet identification (need to be provided by the packet generator or instrument manufacturer), 0x71764129 is employed generally;

• rate -- rate setting;

void esp_phy_bt_tx_tone(uint32_t start, uint32_t chan, uint32_t power)

BLE Carrier Wave(CW) TX command.

参数:

• start -- enable CW, 1 means transmit, 0 means stop transmitting;

• chan -- Single carrier transmission channel selection, range is 0~39, corresponding frequency freq = 2402+chan*2;

• power -- CW power attenuation parameter, unit is 0.25dB. 4 indicates the power is attenuated by 1dB.

void esp_phy_get_rx_result(esp_phy_rx_result_t *rx_result)

Get some RX information.

参数:

rx_result -- This struct for storing RX information;

Structures

struct esp_phy_rx_result_t

Structure holding PHY RX result.

Public Members

uint32_t phy_rx_correct_count

The number of desired packets received

int phy_rx_rssi

Average RSSI of desired packets

uint32_t phy_rx_total_count

The number of total packets received

uint32_t phy_rx_result_flag

0 means no RX info; 1 means the latest Wi-Fi RX info; 2 means the latest BLE RX info.

Enumerations

enum esp_phy_wifi_rate_t

Values:

enumerator PHY_RATE_1M

enumerator PHY_RATE_2M

enumerator PHY_RATE_5M5

enumerator PHY_RATE_11M

enumerator PHY_RATE_6M

enumerator PHY_RATE_9M

enumerator PHY_RATE_12M

enumerator PHY_RATE_18M

enumerator PHY_RATE_24M

enumerator PHY_RATE_36M

enumerator PHY_RATE_48M

enumerator PHY_RATE_54M

enumerator PHY_RATE_MCS0

enumerator PHY_RATE_MCS1

enumerator PHY_RATE_MCS2

enumerator PHY_RATE_MCS3

enumerator PHY_RATE_MCS4

enumerator PHY_RATE_MCS5

enumerator PHY_RATE_MCS6

enumerator PHY_RATE_MCS7

enumerator PHY_RATE_11AX_MCS0

enumerator PHY_RATE_11AX_MCS1

enumerator PHY_RATE_11AX_MCS2

enumerator PHY_RATE_11AX_MCS3

enumerator PHY_RATE_11AX_MCS4

enumerator PHY_RATE_11AX_MCS5

enumerator PHY_RATE_11AX_MCS6

enumerator PHY_RATE_11AX_MCS7

enumerator PHY_RATE_11AX_MCS8

enumerator PHY_RATE_11AX_MCS9

enumerator PHY_RATE_VHT_MCS0

enumerator PHY_RATE_VHT_MCS1

enumerator PHY_RATE_VHT_MCS2

enumerator PHY_RATE_VHT_MCS3

enumerator PHY_RATE_VHT_MCS4

enumerator PHY_RATE_VHT_MCS5

enumerator PHY_RATE_VHT_MCS6

enumerator PHY_RATE_VHT_MCS7

enumerator PHY_RATE_VHT_MCS8

enumerator PHY_WIFI_RATE_MAX

enum esp_phy_ble_rate_t

Values:

enumerator PHY_BLE_RATE_1M

enumerator PHY_BLE_RATE_2M

enumerator PHY_BLE_RATE_125K

enumerator PHY_BLE_RATE_500k

enumerator PHY_BLE_RATE_MAX

enum esp_phy_ble_type_t

Values:

enumerator PHY_BLE_TYPE_1010

enumerator PHY_BLE_TYPE_00001111

enumerator PHY_BLE_TYPE_prbs9

enumerator PHY_BLE_TYPE_00111100

enumerator PHY_BLE_TYPE_MAX

---

此文档对您有帮助吗？

• 反馈已收到，谢谢！
• 如果您有其他意见，欢迎填写乐鑫文档反馈表。

• 我们重视您的反馈。
• 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。