# RF Coexistence

[中文]

## Overview

ESP boards now support three modules: Bluetooth (BT & BLE), IEEE 802.15.4 (Thread / Zigbee), and Wi-Fi. Each type of board has only one 2.4 GHz ISM band RF module, shared by two or three modules. Consequently, a module cannot receive or transmit data while another module is engaged in data transmission or reception. In such scenarios, ESP32-H2 employs the time-division multiplexing method to manage the reception and transmission of packets.

## Supported Coexistence Scenario for ESP32-H2

Supported Features of IEEE 802.15.4 (Thread / Zigbee) and BLE Coexistence
| BLE
Scan | Advertising | Connected
Thread / Zigbee | Scan | X | Y | Y
Router | X | Y | Y
End Device | C1 | Y | Y

Note

- Y: supported and the performance is stable

- C1: supported but the performance is unstable

- X: not supported

Note

Routers in Thread and Zigbee networks maintain unsynchronized links with their neighbors, requiring continuous signal reception. With only a single RF path, increased Wi-Fi or BLE traffic may lead to higher packet loss rates for Thread and Zigbee communications.

To build a Wi-Fi based Thread Border Router or Zigbee Gateway product, we recommend using a dual-SoC solution (e.g., ESP32-S3 + ESP32-H2) with separate antennas. This setup enables simultaneous reception of Wi-Fi and 802.15.4 signals, ensuring optimal performance.

## Coexistence Mechanism and Policy

### Coexistence Mechanism

The RF resource allocation mechanism is based on priority. As shown below, Wi-Fi, Bluetooth and 802.15.4 modules request RF resources from the coexistence module, and the coexistence module decides who will use the RF resource based on their priority.

Coexistence Mechanism

### Coexistence Policy

The IEEE 802.15.4 module requests RF resources based on pre-assigned priorities. Normal receive operations are assigned the lowest priority, meaning Wi-Fi and BLE will take over the RF whenever needed, while 802.15.4 can only receive during the remaining time. Other 802.15.4 operations, such as transmitting or receiving ACKs and transmitting or receiving at given time, are assigned higher priorities. However, their access to RF ultimately depends on the priorities of Wi-Fi and BLE operations at that moment.

## How to Use the Coexistence Feature

### Coexistence API

For most coexistence cases, ESP32-H2 will switch the coexistence status automatically without calling API. However, ESP32-H2 provides two APIs for the coexistence of BLE MESH and Wi-Fi. When the status of BLE MESH changes, call `esp_coex_status_bit_clear` to clear the previous status first and then call `esp_coex_status_bit_set` to set the current status.

#### BLE MESH Coexistence Status

As the firmware of Wi-Fi and Bluetooth are not aware of the current scenario of the upper layer application, some coexistence schemes require application code to call the coexistence API to take effect. The application layer needs to pass the working status of BLE MESH to the coexistence module for selecting the coexistence scheme.

> - ESP_COEX_BLE_ST_MESH_CONFIG: network is provisioning

> - ESP_COEX_BLE_ST_MESH_TRAFFIC: data is transmitting

> - ESP_COEX_BLE_ST_MESH_STANDBY: in idle status with no significant data interaction

### Coexistence API Error Codes

All coexistence APIs have custom return values, i.e., error codes. These error codes can be categorized as:

> - No error. For example, the return value ESP_OK siginifies the API returned successfully.

> - Recoverable errors. For example, the return value ESP_ERR_INVALID_ARG signifies API parameter errors.

### Setting Coexistence Compile-time Options

- After writing the coexistence program, you must check CONFIG_ESP_COEX_SW_COEXIST_ENABLE option through menuconfig to open coexistence configuration on software, otherwise the coexistence function mentioned above cannot be used.

- You can reduce the memory consumption by configuring the following options on menuconfig.

  - CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY: enable the configuration of dynamic memory for Bluetooth protocol stack.

Note

As the coexistence configuration option relies on the presence of any two enabled modules, please ensure that both modules are activated before configuring any coexistence features.

Provide feedback about this document