Merge branch 'feature/ieee802154_txpower_table_v5.1' into 'release/v5.1'

Feature/ieee802154 txpower table (v5.1)

See merge request espressif/esp-idf!36135

components/ieee802154/Kconfig

@@ -23,7 +23,7 @@ menu "IEEE 802.15.4"
         config IEEE802154_CCA_CARRIER
             bool "Carrier sense only"
             help
-                configure the CCA mode to Energy above threshold
+                configure the CCA mode to Carrier sense only
 
         config IEEE802154_CCA_ED
             bool "Energy above threshold"

components/ieee802154/driver/esp_ieee802154_pib.c

@@ -1,12 +1,13 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #include <stdint.h>
 #include <string.h>
 #include "hal/ieee802154_ll.h"
+#include "esp_check.h"
 #include "esp_ieee802154_pib.h"
 #include "esp_ieee802154_util.h"
 
@@ -40,7 +41,7 @@ void ieee802154_pib_init(void)
     s_ieee802154_pib.channel = 11;
     s_ieee802154_pib.cca_threshold = CONFIG_IEEE802154_CCA_THRESHOLD;
     s_ieee802154_pib.cca_mode = CONFIG_IEEE802154_CCA_MODE;
-    s_ieee802154_pib.txpower = IEEE802154_TXPOWER_VALUE_MAX;
+    memset(&s_ieee802154_pib.power_table, IEEE802154_TXPOWER_VALUE_MAX, sizeof(s_ieee802154_pib.power_table));
 
     set_pending();
 }
@@ -62,7 +63,7 @@ void ieee802154_pib_update(void)
 {
     if (ieee802154_pib_is_pending()) {
         ieee802154_ll_set_freq(ieee802154_channel_to_freq(s_ieee802154_pib.channel));
-        ieee802154_ll_set_power(ieee802154_txpower_convert(s_ieee802154_pib.txpower));
+        ieee802154_ll_set_power(ieee802154_txpower_convert(ieee802154_pib_get_power()));
 
         ieee802154_ll_set_cca_mode(s_ieee802154_pib.cca_mode);
         ieee802154_ll_set_cca_threshold(s_ieee802154_pib.cca_threshold);
@@ -86,6 +87,7 @@ uint8_t ieee802154_pib_get_channel(void)
 
 void ieee802154_pib_set_channel(uint8_t channel)
 {
+    ESP_RETURN_ON_FALSE(ieee802154_is_valid_channel(channel), , IEEE802154_TAG, "Failed to set channel, reason: Invalid channel: %d", channel);
     if (s_ieee802154_pib.channel != channel) {
         s_ieee802154_pib.channel = channel;
         set_pending();
@@ -94,15 +96,48 @@ void ieee802154_pib_set_channel(uint8_t channel)
 
 int8_t ieee802154_pib_get_power(void)
 {
-    return s_ieee802154_pib.txpower;
+    int8_t ret_power = 0;
+    ieee802154_pib_get_power_with_channel(s_ieee802154_pib.channel, &ret_power);
+    return ret_power;
 }
 
 void ieee802154_pib_set_power(int8_t power)
 {
-    if (s_ieee802154_pib.txpower != power) {
-        s_ieee802154_pib.txpower = power;
+    ieee802154_pib_set_power_with_channel(s_ieee802154_pib.channel, power);
+}
+
+esp_err_t ieee802154_pib_set_power_table(esp_ieee802154_txpower_table_t power_table)
+{
+    if (memcmp(&s_ieee802154_pib.power_table, &power_table, sizeof(esp_ieee802154_txpower_table_t)) != 0) {
+        memcpy((void *)&s_ieee802154_pib.power_table, (void *)&power_table, sizeof(esp_ieee802154_txpower_table_t));
+        set_pending();
+    }
+    return ESP_OK;
+}
+
+esp_err_t ieee802154_pib_get_power_table(esp_ieee802154_txpower_table_t *out_power_table)
+{
+    ESP_RETURN_ON_FALSE(out_power_table != NULL, ESP_ERR_INVALID_ARG, IEEE802154_TAG, "Invalid power table");
+    memcpy((void *)out_power_table, (void *)&s_ieee802154_pib.power_table, sizeof(esp_ieee802154_txpower_table_t));
+    return ESP_OK;
+}
+
+esp_err_t ieee802154_pib_set_power_with_channel(uint8_t channel, int8_t power)
+{
+    ESP_RETURN_ON_FALSE(ieee802154_is_valid_channel(channel), ESP_ERR_INVALID_ARG, IEEE802154_TAG, "Invalid channel: %d", channel);
+    if (s_ieee802154_pib.power_table.channel[channel - IEEE802154_OQPSK_2P4G_CHANNEL_MIN] != power) {
+        s_ieee802154_pib.power_table.channel[channel - IEEE802154_OQPSK_2P4G_CHANNEL_MIN] = power;
         set_pending();
     }
+    return ESP_OK;
+}
+
+esp_err_t ieee802154_pib_get_power_with_channel(uint8_t channel, int8_t *out_power)
+{
+    ESP_RETURN_ON_FALSE(ieee802154_is_valid_channel(channel), ESP_ERR_INVALID_ARG, IEEE802154_TAG, "Invalid channel: %d", channel);
+    ESP_RETURN_ON_FALSE(out_power != NULL, ESP_ERR_INVALID_ARG, IEEE802154_TAG, "The pointer of out_power should not be NULL");
+    *out_power = s_ieee802154_pib.power_table.channel[channel - IEEE802154_OQPSK_2P4G_CHANNEL_MIN];
+    return ESP_OK;
 }
 
 bool ieee802154_pib_get_promiscuous(void)

components/ieee802154/driver/esp_ieee802154_util.c

@@ -13,12 +13,12 @@
 
 uint8_t ieee802154_freq_to_channel(uint8_t freq)
 {
-    return (freq - 3) / 5 + 11;
+    return (freq - 3) / 5 + IEEE802154_OQPSK_2P4G_CHANNEL_MIN;
 }
 
 uint8_t ieee802154_channel_to_freq(uint8_t channel)
 {
-    return (channel - 11) * 5 + 3;
+    return (channel - IEEE802154_OQPSK_2P4G_CHANNEL_MIN) * 5 + 3;
 }
 
 #if !CONFIG_IEEE802154_TEST && (CONFIG_ESP_COEX_SW_COEXIST_ENABLE || CONFIG_EXTERNAL_COEX_ENABLE)

components/ieee802154/esp_ieee802154.c

@@ -59,6 +59,26 @@ esp_err_t esp_ieee802154_set_txpower(int8_t power)
     return ESP_OK;
 }
 
+esp_err_t esp_ieee802154_set_power_table(esp_ieee802154_txpower_table_t power_table)
+{
+    return ieee802154_pib_set_power_table(power_table);
+}
+
+esp_err_t esp_ieee802154_get_power_table(esp_ieee802154_txpower_table_t *out_power_table)
+{
+    return ieee802154_pib_get_power_table(out_power_table);
+}
+
+esp_err_t esp_ieee802154_set_power_with_channel(uint8_t channel, int8_t power)
+{
+    return ieee802154_pib_set_power_with_channel(channel, power);
+}
+
+esp_err_t esp_ieee802154_get_power_with_channel(uint8_t channel, int8_t *out_power)
+{
+    return ieee802154_pib_get_power_with_channel(channel, out_power);
+}
+
 bool esp_ieee802154_get_promiscuous(void)
 {
     return ieee802154_pib_get_promiscuous();

components/ieee802154/include/esp_ieee802154.h

@@ -73,6 +73,52 @@ int8_t esp_ieee802154_get_txpower(void);
  */
 esp_err_t esp_ieee802154_set_txpower(int8_t power);
 
+/**
+ * @brief  Set the transmission power table.
+ *
+ * @param[in]  power_table  The power table.
+ *
+ * @return
+ *        - ESP_OK   Set the transmission power table to successfully.
+ */
+esp_err_t esp_ieee802154_set_power_table(esp_ieee802154_txpower_table_t power_table);
+
+/**
+ * @brief  Get the transmission power table.
+ *
+ * @param[out]  out_power_table  The power table.
+ *
+ * @return
+ *        - ESP_OK                  Get the transmission power table successfully.
+ *        - ESP_ERR_INVALID_ARG     Invalid arguments.
+ *
+ */
+esp_err_t esp_ieee802154_get_power_table(esp_ieee802154_txpower_table_t *out_power_table);
+
+/**
+ * @brief  Set the transmission power for a specific channel.
+ *
+ * @param[in]  channel  The channel.
+ * @param[in]  power    The power.
+ *
+ * @return
+ *        - ESP_OK                  Set the transmission power for a specific channel successfully.
+ *        - ESP_ERR_INVALID_ARG     Invalid arguments.
+ */
+esp_err_t esp_ieee802154_set_power_with_channel(uint8_t channel, int8_t power);
+
+/**
+ * @brief  Get the transmission power for a specific channel.
+ *
+ * @param[in]  channel    The channel.
+ * @param[out] out_power  The power.
+ *
+ * @return
+ *        - ESP_OK                  Get the transmission power for a specific channel successfully.
+ *        - ESP_ERR_INVALID_ARG     Invalid arguments.
+ */
+esp_err_t esp_ieee802154_get_power_with_channel(uint8_t channel, int8_t *out_power);
+
 /**
  * @brief  Get the promiscuous mode.
  *

components/ieee802154/include/esp_ieee802154_types.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -83,6 +83,14 @@ typedef struct {
     uint64_t timestamp;          /*!< The timestamp when the frame's SFD field was received */
 } esp_ieee802154_frame_info_t;
 
+/**
+ * @brief The O-QPSK PHY transmission power table for 2.4 GHz channels as defined by the IEEE 802.15.4 specification.
+ *
+ */
+typedef struct {
+    int8_t channel[16];         /*!< Index 0 -> Channel 11, Index 1 -> Channel 12 ... Index 15 -> Channel 26 */
+} esp_ieee802154_txpower_table_t;
+
 #ifdef __cplusplus
 }
 #endif

components/ieee802154/private_include/esp_ieee802154_pib.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -10,6 +10,7 @@
 #include <stdint.h>
 #include "hal/ieee802154_ll.h"
 #include "esp_ieee802154_frame.h"
+#include "esp_ieee802154_types.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -25,11 +26,11 @@ typedef struct {
     bool promiscuous;                                                               /*!< A flag indicates promiscuous mode is enabled or not */
     bool coordinator;                                                               /*!< A flag indicates the device is coordinator or not*/
     bool rx_when_idle;                                                              /*!< A flag indicates the device is rx on when idle or not */
-    int8_t txpower;                                                                 /*!< Tx power configuration */
+    esp_ieee802154_txpower_table_t power_table;                                     /*!< The power table configuration */
     uint8_t channel;                                                                /*!< Channel configuration  */
-    ieee802154_ll_pending_mode_t pending_mode;                                         /*!< Pending mode configuration  */
+    ieee802154_ll_pending_mode_t pending_mode;                                      /*!< Pending mode configuration  */
     int8_t cca_threshold;                                                           /*!< CCA threshold */
-    ieee802154_ll_cca_mode_t cca_mode;                                                 /*!< CCA mode */
+    ieee802154_ll_cca_mode_t cca_mode;                                              /*!< CCA mode */
 } ieee802154_pib_t;
 
 /**
@@ -69,21 +70,66 @@ void ieee802154_pib_set_channel(uint8_t channel);
 uint8_t ieee802154_pib_get_channel(void);
 
 /**
- * @brief  Set a specific transmission power to the PIB.
+ * @brief  Set a specific transmission power for current channel to the PIB.
  *
  * @param[in]  power  The power.
  *
  */
 void ieee802154_pib_set_power(int8_t power);
 
 /**
- * @brief  Get the transmission power from the PIB.
+ * @brief  Get the transmission power of current channel from the PIB.
  *
  * @return
  *        - The transmission power has been set in the PIB.
  */
 int8_t ieee802154_pib_get_power(void);
 
+/**
+ * @brief  Set a specific transmission power table to the PIB.
+ *
+ * @param[in]  power_table  The power table.
+ *
+ * @return
+ *        - ESP_OK   Set the transmission power table to the PIB successfully.
+ */
+esp_err_t ieee802154_pib_set_power_table(esp_ieee802154_txpower_table_t power_table);
+
+/**
+ * @brief  Get the transmission power table from the PIB.
+ *
+ * @param[out]  out_power_table  The power table.
+ *
+ * @return
+ *        - ESP_OK   Get the transmission power table from the PIB successfully.
+ *
+ */
+esp_err_t ieee802154_pib_get_power_table(esp_ieee802154_txpower_table_t *out_power_table);
+
+/**
+ * @brief  Set a specific transmission power for a specific channel to the PIB.
+ *
+ * @param[in]  channel  The channel.
+ * @param[in]  power    The power.
+ *
+ * @return
+ *        - ESP_OK                  Set the transmission power of a specific channel from the PIB successfully.
+ *        - ESP_ERR_INVALID_ARG     Invalid channel.
+ */
+esp_err_t ieee802154_pib_set_power_with_channel(uint8_t channel, int8_t power);
+
+/**
+ * @brief  Get the transmission power of a specific channel from the PIB.
+ *
+ * @param[in]  channel    The channel.
+ * @param[out] out_power  The power.
+ *
+ * @return
+ *        - ESP_OK                  Get the transmission power of a specific channel from the PIB successfully.
+ *        - ESP_ERR_INVALID_ARG     Invalid channel.
+ */
+esp_err_t ieee802154_pib_get_power_with_channel(uint8_t channel, int8_t *out_power);
+
 /**
  * @brief  Set the promiscuous mode to the PIB.
  *

components/ieee802154/private_include/esp_ieee802154_util.h

@@ -19,6 +19,14 @@ extern "C" {
 
 #define IEEE802154_TAG "ieee802154"
 
+#define IEEE802154_OQPSK_2P4G_CHANNEL_MIN 11
+#define IEEE802154_OQPSK_2P4G_CHANNEL_MAX 26
+
+static inline bool ieee802154_is_valid_channel(uint8_t channel)
+{
+    return ((channel <= IEEE802154_OQPSK_2P4G_CHANNEL_MAX) && (channel >= IEEE802154_OQPSK_2P4G_CHANNEL_MIN));
+}
+
 #if SOC_PM_MODEM_RETENTION_BY_REGDMA && CONFIG_FREERTOS_USE_TICKLESS_IDLE
 #define IEEE802154_RF_ENABLE() ieee802154_rf_enable()
 #define IEEE802154_RF_DISABLE() ieee802154_rf_disable()

components/openthread/Kconfig

@@ -360,6 +360,14 @@ menu "OpenThread"
                     default 120
             endmenu
 
+            config OPENTHREAD_PREFERRED_CHANNEL_MASK
+                hex "Preferred channel mask"
+                default 0x7fff800
+
+            config OPENTHREAD_SUPPORTED_CHANNEL_MASK
+                hex "Supported channel mask"
+                default 0x7fff800
+
             config OPENTHREAD_NUM_MESSAGE_BUFFERS
                 int "The number of openthread message buffers"
                 default 65

components/openthread/src/port/esp_openthread_radio.c

@@ -798,3 +798,15 @@ void otPlatRadioSetRxOnWhenIdle(otInstance *aInstance, bool aEnable)
     esp_ieee802154_set_rx_when_idle(aEnable);
 }
 #endif
+
+uint32_t otPlatRadioGetPreferredChannelMask(otInstance *aInstance)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    return CONFIG_OPENTHREAD_PREFERRED_CHANNEL_MASK;
+}
+
+uint32_t otPlatRadioGetSupportedChannelMask(otInstance *aInstance)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    return CONFIG_OPENTHREAD_SUPPORTED_CHANNEL_MASK;
+}

components/openthread/src/port/esp_openthread_radio_spinel.cpp

@@ -467,3 +467,17 @@ uint16_t otPlatTimeGetXtalAccuracy(void)
 {
     return CONFIG_OPENTHREAD_XTAL_ACCURACY;
 }
+
+uint32_t otPlatRadioGetPreferredChannelMask(otInstance *aInstance)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    // Refer to `GetRadioChannelMask(bool aPreferred)`: TRUE to get preferred channel mask
+    return s_radio.GetRadioChannelMask(true);
+}
+
+uint32_t otPlatRadioGetSupportedChannelMask(otInstance *aInstance)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    // Refer to `GetRadioChannelMask(bool aPreferred)`: FALSE to get supported channel mask
+    return s_radio.GetRadioChannelMask(false);
+}