espressif/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-04-27 19:13:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feat/add_phy_cli_debug_v6.0' into 'release/v6.0'

Browse Source 
feat(openthread): support 154 debug features on RCP (v6.0)

See merge request espressif/esp-idf!45730
This commit is contained in:
Zhang Wen Xu
2026-03-19 13:52:48 +00:00
parent 818c06b158 cc4f020278
commit a37a16057d
9 changed files with 304 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/ieee802154/Kconfig
+154 -110
View File
@@ -11,34 +11,42 @@ menu "IEEE 802.15.4"
default 20
range 2 100
help
The number of 802.15.4 receive buffers
Number of receive buffers allocated for IEEE 802.15.4 frames.
Increasing this value allows more frames to be buffered before processing,
but consumes more memory.
choice IEEE802154_CCA_MODE
depends on IEEE802154_ENABLED
prompt "Clear Channel Assessment (CCA) mode"
default IEEE802154_CCA_ED
help
configure the CCA mode
Select the Clear Channel Assessment (CCA) mode used to determine if the
channel is clear before transmission. CCA is required by the IEEE 802.15.4
standard to avoid collisions.
config IEEE802154_CCA_CARRIER
bool "Carrier sense only"
help
configure the CCA mode to Carrier sense only
CCA reports channel busy only if a valid IEEE 802.15.4 signal is detected.
This mode is less sensitive to non-802.15.4 interference.
config IEEE802154_CCA_ED
bool "Energy above threshold"
help
configure the CCA mode to Energy above threshold
CCA reports channel busy if the energy level exceeds the configured threshold.
This is the default mode and provides good balance between sensitivity and reliability.
config IEEE802154_CCA_CARRIER_OR_ED
bool "Carrier sense OR energy above threshold"
help
configure the CCA mode to Carrier sense OR energy above threshold
CCA reports channel busy if either a valid IEEE 802.15.4 signal is detected OR
the energy level exceeds the threshold. This is the most sensitive mode.
config IEEE802154_CCA_CARRIER_AND_ED
bool "Carrier sense AND energy above threshold"
help
configure the CCA mode to Carrier sense AND energy above threshold
CCA reports channel busy only if both a valid IEEE 802.15.4 signal is detected
AND the energy level exceeds the threshold. This is the least sensitive mode.
endchoice
config IEEE802154_CCA_MODE
@@ -55,7 +63,9 @@ menu "IEEE 802.15.4"
range -120 0
default -75
help
set the CCA threshold, in dBm
Energy detection threshold for CCA, in dBm. The channel is considered busy
if the detected energy exceeds this threshold. Lower values make the radio
more sensitive to interference but may cause false positives.
config IEEE802154_PENDING_TABLE_SIZE
int "Pending table size"
@@ -63,14 +73,18 @@ menu "IEEE 802.15.4"
range 1 100
default 20
help
set the pending table size
Size of the pending data table used to track frames waiting to be sent to
sleeping devices. Each entry consumes memory, so adjust based on the number
of sleeping child devices in your network.
config IEEE802154_MULTI_PAN_ENABLE
bool "Enable multi-pan feature for frame filter"
depends on IEEE802154_ENABLED
default n
help
Enable IEEE802154 multi-pan
Enable IEEE 802.15.4 multi-PAN (Personal Area Network) support. This allows
the device to participate in multiple PANs simultaneously by filtering frames
based on PAN ID.
config IEEE802154_INTERFACE_NUM
int "Number of IEEE802154 interfaces"
@@ -99,7 +113,7 @@ menu "IEEE 802.15.4"
Enabling this option allows the IEEE802.15.4 module to be powered down during automatic light sleep,
which reduces current consumption.
menuconfig IEEE802154_DEBUG
config IEEE802154_DEBUG
bool "Enable IEEE802154 Debug"
depends on IEEE802154_ENABLED
default n
@@ -107,119 +121,149 @@ menu "IEEE 802.15.4"
Enabling this option allows different kinds of IEEE802154 debug output.
All IEEE802154 debug features increase the size of the final binary.
config IEEE802154_DEBUG_ASSERT_MONITOR
bool "Enable IEEE802154 assert monitor"
depends on IEEE802154_ENABLED
default n
help
Enabling this option to monitor and detect certain abnormal or unexpected
states during the operation of the IEEE 802.15.4. When this option is enabled,
it will perform additional runtime checks and assertions.
config IEEE802154_RX_BUFFER_STATISTIC
bool "Rx buffer statistic"
menu "IEEE 802.15.4 Debug Parameters"
depends on IEEE802154_DEBUG
default n
help
Enabling this option to count IEEE802154 rx buffer when allocating or freeing.
config IEEE802154_ASSERT
bool "Enrich the assert information"
depends on IEEE802154_DEBUG
select IEEE802154_RECORD
default n
help
Enabling this option to print more information when assert.
config IEEE802154_DEBUG_ASSERT_MONITOR
bool "Enable IEEE802154 assert monitor"
default n
help
Enable monitoring and detection of abnormal or unexpected states during
IEEE 802.15.4 operation. When enabled, performs additional runtime checks
and assertions to catch potential driver issues early.
config IEEE802154_RECORD
bool "Record the information with IEEE802154 state and event"
depends on IEEE802154_DEBUG
default n
help
Enabling this option to add some probe codes in the driver, and record these information.
config IEEE802154_RX_BUFFER_STATISTIC
bool "Rx buffer statistic"
default n
help
Enable tracking of receive buffer allocation and deallocation. This provides
statistics on buffer usage patterns, which can help optimize buffer sizing
for your application.
config IEEE802154_RECORD_EVENT
bool "Enable record event information for debugging"
depends on IEEE802154_RECORD
default n
help
Enabling this option to record event, when assert, the recorded event will be printed.
config IEEE802154_ASSERT
bool "Enrich the assert information"
select IEEE802154_RECORD
default n
help
Enable enhanced assert information. When an assertion fails, additional
context including state, events, and commands will be printed to help
diagnose the issue. Automatically enables IEEE802154_RECORD.
config IEEE802154_RECORD_EVENT_SIZE
int "Record event table size"
depends on IEEE802154_RECORD_EVENT
range 1 50
default 30
help
set the record event table size
config IEEE802154_RECORD
bool "Record the information with IEEE802154 state and event"
default n
help
Enable recording of IEEE 802.15.4 driver state, events, and commands.
Probe code is added throughout the driver to capture runtime information
for debugging purposes. This is a prerequisite for other RECORD_* options.
config IEEE802154_RECORD_STATE
bool "Enable record state information for debugging"
depends on IEEE802154_RECORD
default n
help
Enabling this option to record state, when assert, the recorded state will be printed.
config IEEE802154_RECORD_EVENT
bool "Enable record event information for debugging"
depends on IEEE802154_RECORD
default n
help
Record IEEE 802.15.4 driver events in a circular buffer. When an assertion
occurs, the recorded event history will be printed to help trace the sequence
of events leading to the failure.
config IEEE802154_RECORD_STATE_SIZE
int "Record state table size"
depends on IEEE802154_RECORD_STATE
range 1 50
default 10
help
set the record state table size
config IEEE802154_RECORD_EVENT_SIZE
int "Record event table size"
depends on IEEE802154_RECORD_EVENT
range 1 50
default 30
help
Size of the circular buffer for recording events. Larger values provide
more history but consume more memory.
config IEEE802154_RECORD_CMD
bool "Enable record command information for debugging"
depends on IEEE802154_RECORD
default n
help
Enabling this option to record the command, when assert, the recorded
command will be printed.
config IEEE802154_RECORD_STATE
bool "Enable record state information for debugging"
depends on IEEE802154_RECORD
default n
help
Record IEEE 802.15.4 driver state transitions in a circular buffer.
When an assertion occurs, the recorded state history will be printed
to show the sequence of state changes.
config IEEE802154_RECORD_CMD_SIZE
int "Record command table size"
depends on IEEE802154_RECORD_CMD
range 1 50
default 10
help
set the record command table size
config IEEE802154_RECORD_STATE_SIZE
int "Record state table size"
depends on IEEE802154_RECORD_STATE
range 1 50
default 10
help
Size of the circular buffer for recording state transitions. Larger values
provide more history but consume more memory.
config IEEE802154_RECORD_ABORT
bool "Enable record abort information for debugging"
depends on IEEE802154_RECORD
default n
help
Enabling this option to record the abort, when assert, the recorded
abort will be printed.
config IEEE802154_RECORD_CMD
bool "Enable record command information for debugging"
depends on IEEE802154_RECORD
default n
help
Record IEEE 802.15.4 driver commands in a circular buffer. When an assertion
occurs, the recorded command history will be printed to show what commands
were issued before the failure.
config IEEE802154_RECORD_ABORT_SIZE
int "Record abort table size"
depends on IEEE802154_RECORD_ABORT
range 1 50
default 10
help
set the record abort table size
config IEEE802154_RECORD_CMD_SIZE
int "Record command table size"
depends on IEEE802154_RECORD_CMD
range 1 50
default 10
help
Size of the circular buffer for recording commands. Larger values provide
more history but consume more memory.
config IEEE802154_RECORD_TXRX_FRAME
bool "Enable record txrx packets for debugging"
depends on IEEE802154_DEBUG
default n
help
Enabling this option to record the tx and rx packets
config IEEE802154_RECORD_ABORT
bool "Enable record abort information for debugging"
depends on IEEE802154_RECORD
default n
help
Record IEEE 802.15.4 operation aborts in a circular buffer. When an assertion
occurs, the recorded abort history will be printed to show what operations
were aborted before the failure.
config IEEE802154_RECORD_TXRX_FRAME_SIZE
int "Record frame table size"
depends on IEEE802154_RECORD_TXRX_FRAME
range 1 50
default 15
help
set the record frame table size
config IEEE802154_RECORD_ABORT_SIZE
int "Record abort table size"
depends on IEEE802154_RECORD_ABORT
range 1 50
default 10
help
Size of the circular buffer for recording aborts. Larger values provide
more history but consume more memory.
config IEEE802154_TXRX_STATISTIC
bool "Enable record tx/rx packets information for debugging"
depends on IEEE802154_DEBUG
default n
help
Enabling this option to record the tx and rx
config IEEE802154_RECORD_TXRX_FRAME
bool "Enable record txrx packets for debugging"
default n
help
Record transmitted and received IEEE 802.15.4 frames in a circular buffer.
When an assertion occurs, the recorded frame history will be printed to
help diagnose frame-level issues. Note: This can consume significant memory
depending on frame size and buffer size.
config IEEE802154_RECORD_TXRX_FRAME_SIZE
int "Record frame table size"
depends on IEEE802154_RECORD_TXRX_FRAME
range 1 50
default 15
help
Size of the circular buffer for recording frames. Larger values provide
more frame history but consume significantly more memory (each frame can
be up to 127 bytes plus metadata).
config IEEE802154_TXRX_STATISTIC
bool "Enable record tx/rx packets information for debugging"
default n
help
Enable collection of transmit and receive packet statistics. This tracks
counts, errors, and other metrics for transmitted and received frames.
Statistics can be accessed via debug APIs for performance analysis.
config IEEE802154_PRINT_PHY_REG
bool "Enable print IEEE802154 PHY register command"
default n
help
Enable the 'phyreg' console command to print IEEE 802.15.4 PHY register
information for debugging purposes. This command displays register values
and configuration settings of the IEEE 802.15.4 hardware.
endmenu # IEEE 802.15.4 Debug Parameters
endmenu # IEEE 802.15.4
examples/ieee802154/components/cmd_ieee802154_debug/ieee802154_debug.c
+80 -1
View File
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Unlicense OR CC0-1.0
*/
@@ -26,6 +26,10 @@ static void register_txrx_statistic(void);
static void register_record(void);
#endif
#if CONFIG_IEEE802154_PRINT_PHY_REG
static void register_phyreg(void);
#endif
void register_ieee802154_debug_cmd(void)
{
#if CONFIG_IEEE802154_RX_BUFFER_STATISTIC
@@ -37,6 +41,9 @@ void register_ieee802154_debug_cmd(void)
#if CONFIG_IEEE802154_RECORD
register_record();
#endif
#if CONFIG_IEEE802154_PRINT_PHY_REG
register_phyreg();
#endif
}
#endif
@@ -173,4 +180,76 @@ static void register_record(void)
ESP_ERROR_CHECK(esp_console_cmd_register(&cmd));
}
#endif // CONFIG_IEEE802154_RECORD
#if CONFIG_IEEE802154_PRINT_PHY_REG
__attribute__((weak)) void pbus_print(void)
{
ESP_LOGE("", "pbus_print not in phylib");
}
__attribute__((weak)) void phy_cal_print(void)
{
ESP_LOGE("", "phy_cal_print not in phylib");
}
__attribute__((weak)) void phy_i2c_check(void)
{
ESP_LOGE("", "phy_i2c_check not in phylib");
}
__attribute__((weak)) void phy_reg_check(void)
{
ESP_LOGE("", "phy_reg_check not in phylib");
}
extern void pbus_print(void);
extern void phy_cal_print(void);
extern void phy_i2c_check(void);
extern void phy_reg_check(void);
static void ieee802154_phy_reg_print(void)
{
pbus_print();
phy_cal_print();
phy_i2c_check();
phy_reg_check();
}
static struct {
struct arg_lit *get_phyreg;
struct arg_end *end;
} phyreg_args;
static int process_phyreg(int argc, char **argv)
{
int nerrors = arg_parse(argc, argv, (void **) &phyreg_args);
if (nerrors != 0) {
arg_print_errors(stderr, phyreg_args.end, argv[0]);
return 1;
}
if (phyreg_args.get_phyreg->count) {
ieee802154_phy_reg_print();
} else {
ESP_LOGE(TAG, "no valid arguments");
return 1;
}
return 0;
}
static void register_phyreg(void)
{
phyreg_args.get_phyreg =
arg_lit0("g", "get", "get IEEE802154 PHY register debug info");
phyreg_args.end = arg_end(1);
const esp_console_cmd_t cmd = {
.command = "phyreg",
.help = "get IEEE802154 PHY register debug info",
.hint = NULL,
.func = &process_phyreg,
.argtable = &phyreg_args
};
ESP_ERROR_CHECK(esp_console_cmd_register(&cmd));
}
#endif // CONFIG_IEEE802154_PRINT_PHY_REG
#endif // CONFIG_IEEE802154_DEBUG
examples/openthread/ot_common_components/ot_examples_common/include/ot_examples_common.h
+6
View File
@@ -56,6 +56,12 @@ void ot_external_coexist_init(void);
*/
void ot_console_start(void);
/**
* @brief De-initializes the console.
*
*/
void ot_console_stop(void);
/**
* @brief Form or join the Thread network automatically.
*
examples/openthread/ot_common_components/ot_examples_common/ot_console.c
+7 -2
View File
@@ -22,9 +22,10 @@
#include "iperf_cmd.h"
#endif
static esp_console_repl_t *repl = NULL;
void ot_console_start(void)
{
esp_console_repl_t *repl = NULL;
esp_console_repl_config_t repl_config = ESP_CONSOLE_REPL_CONFIG_DEFAULT();
/* Prompt to be printed before each line.
* This can be customized, made dynamic, etc.
@@ -39,7 +40,6 @@ void ot_console_start(void)
#elif defined(CONFIG_ESP_CONSOLE_USB_CDC)
esp_console_dev_usb_cdc_config_t hw_config = ESP_CONSOLE_DEV_CDC_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_console_new_repl_usb_cdc(&hw_config, &repl_config, &repl));
#elif defined(CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG)
esp_console_dev_usb_serial_jtag_config_t hw_config = ESP_CONSOLE_DEV_USB_SERIAL_JTAG_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_console_new_repl_usb_serial_jtag(&hw_config, &repl_config, &repl));
@@ -49,6 +49,11 @@ void ot_console_start(void)
ESP_ERROR_CHECK(esp_console_start_repl(repl));
}
void ot_console_stop(void)
{
ESP_ERROR_CHECK(esp_console_stop_repl(repl)); // this does esp_console_repl_usb_serial_xxxx_delete
}
void ot_register_external_commands(void)
{
register_system();
examples/openthread/ot_rcp/README.md
+40
View File
@@ -64,3 +64,43 @@ Please refer to [ot_br](../ot_br) example for the setup steps.
#### Thread Sniffer
Please refer to [Thread Sniffer](https://openthread.io/guides/pyspinel/sniffer) for the detailed instructions.
### Debug Feature: Turn on RCP console
The RCP console feature allows you to send console commands to the RCP firmware via the Spinel protocol. This is useful for debugging IEEE 802.15.4 PHY register issues and accessing debug statistics.
To enable the RCP console, you can either:
**Option 1: Use the debug configuration file**
Use the debug configuration file and rebuild:
```
idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.debug" set-target esp32h2
idf.py -p <PORT> build flash
```
This enables the following commands:
- `phyreg -g` - Get IEEE 802.15.4 PHY register debug information, including PBUS registers, PHY calibration data, I2C checks, and register validation
- `help` - List all available console commands
**Option 2: Configure manually via menuconfig**
To enable other IEEE 802.15.4 debug commands (detailed in `examples/ieee802154/components/cmd_ieee802154_debug/README.md`), run `idf.py menuconfig` and enable the following options:
```
Component config → OpenThread → Thread Core Features → Thread Radio Co-Processor Feature → Enable RCP console via Spinel
Component config → IEEE 802.15.4 → Enable IEEE802154 Debug
Component config → IEEE 802.15.4 → IEEE 802.15.4 Debug Parameters → **Select relevant debug features as required**
Component config → Log → Log Level → Default log verbosity → Info
Component config → ESP System Settings → Task watchdog timeout period (seconds) → 10
```
**Note:** It's recommended to increase the watchdog timer timeout to 10 seconds when enabling debug features, as large debug prints may take longer to complete.
Then rebuild and flash:
```
idf.py -p <PORT> build flash
```
examples/openthread/ot_rcp/main/esp_ot_rcp.c
+6
View File
@@ -31,6 +31,9 @@
#if CONFIG_OPENTHREAD_RCP_SPINEL_CONSOLE
#include "esp_console.h"
#if CONFIG_IEEE802154_DEBUG
#include "ieee802154_debug.h"
#endif
#endif
#define TAG "ot_esp_rcp"
@@ -67,6 +70,9 @@ void app_main(void)
esp_console_config_t console_config = ESP_CONSOLE_CONFIG_DEFAULT();
esp_console_init(&console_config);
esp_console_register_help_command();
#if CONFIG_IEEE802154_DEBUG
register_ieee802154_debug_cmd();
#endif
#endif
ESP_ERROR_CHECK(esp_openthread_start(&config));
examples/openthread/ot_rcp/main/idf_component.yml
+2
View File
@@ -2,3 +2,5 @@
dependencies:
ot_examples_common:
path: ${IDF_PATH}/examples/openthread/ot_common_components/ot_examples_common
cmd_ieee802154_debug:
path: ${IDF_PATH}/examples/ieee802154/components/cmd_ieee802154_debug
examples/openthread/ot_rcp/sdkconfig.defaults
-6
View File
@@ -52,9 +52,3 @@ CONFIG_OPENTHREAD_LOG_LEVEL_DYNAMIC=n
CONFIG_OPENTHREAD_LOG_LEVEL_NONE=y
CONFIG_OPENTHREAD_TIMING_OPTIMIZATION=y
CONFIG_FREERTOS_HZ=1000
#
# Turn on RCP console by default, overriding default log level from above
#
CONFIG_OPENTHREAD_RCP_SPINEL_CONSOLE=y
CONFIG_LOG_DEFAULT_LEVEL_INFO=y
examples/openthread/ot_rcp/sdkconfig.defaults.debug
+9
View File
@@ -0,0 +1,9 @@
#
# Turn on RCP console, overriding default log level from sdkconfig.defaults
# We also increase the timeout for watchdog timer to account for large prints.
#
CONFIG_OPENTHREAD_RCP_SPINEL_CONSOLE=y
CONFIG_LOG_DEFAULT_LEVEL_INFO=y
CONFIG_ESP_TASK_WDT_TIMEOUT_S=10
CONFIG_IEEE802154_DEBUG=y
CONFIG_IEEE802154_PRINT_PHY_REG=y