From e770817dc7f18fa02fa1d14937335096af5f5fe3 Mon Sep 17 00:00:00 2001 From: Shu Chen Date: Wed, 25 Aug 2021 18:05:04 +0800 Subject: [PATCH] openthread: refine ot_rcp example documentation and APIs --- components/openthread/ftd.cmake | 1 + .../openthread-core-esp32x-ftd-config.h | 0 .../openthread-core-esp32x-radio-config.h | 38 +++++++++-- components/openthread/radio.cmake | 1 + docs/doxygen/Doxyfile | 2 - .../api-reference/network/esp_openthread.rst | 2 - examples/openthread/ot_rcp/README.md | 67 +++++-------------- .../openthread/ot_rcp/main/esp_ot_config.h | 2 +- 8 files changed, 53 insertions(+), 60 deletions(-) rename components/openthread/{include => private_include}/openthread-core-esp32x-ftd-config.h (100%) rename components/openthread/{include => private_include}/openthread-core-esp32x-radio-config.h (93%) diff --git a/components/openthread/ftd.cmake b/components/openthread/ftd.cmake index 89ef3e1735..d87bd93159 100644 --- a/components/openthread/ftd.cmake +++ b/components/openthread/ftd.cmake @@ -10,6 +10,7 @@ set(private_include_dirs "openthread/src/lib/hdlc" "openthread/src/lib/spinel" "openthread/src/ncp" + "private_include" ) set(src_dirs diff --git a/components/openthread/include/openthread-core-esp32x-ftd-config.h b/components/openthread/private_include/openthread-core-esp32x-ftd-config.h similarity index 100% rename from components/openthread/include/openthread-core-esp32x-ftd-config.h rename to components/openthread/private_include/openthread-core-esp32x-ftd-config.h diff --git a/components/openthread/include/openthread-core-esp32x-radio-config.h b/components/openthread/private_include/openthread-core-esp32x-radio-config.h similarity index 93% rename from components/openthread/include/openthread-core-esp32x-radio-config.h rename to components/openthread/private_include/openthread-core-esp32x-radio-config.h index ace9c05e74..4e5e667dd1 100644 --- a/components/openthread/include/openthread-core-esp32x-radio-config.h +++ b/components/openthread/private_include/openthread-core-esp32x-radio-config.h @@ -262,6 +262,38 @@ */ #define OPENTHREAD_CONFIG_PLATFORM_USEC_TIMER_ENABLE 1 +/** + * @def OPENTHREAD_CONFIG_MAC_SOFTWARE_CSMA_BACKOFF_ENABLE + * + * Define to 1 to enable software CSMA-CA backoff logic. + * + */ +#define OPENTHREAD_CONFIG_MAC_SOFTWARE_CSMA_BACKOFF_ENABLE 1 + +/** + * @def OPENTHREAD_CONFIG_MAC_SOFTWARE_RETRANSMIT_ENABLE + * + * Define to 1 to enable software retransmission logic. + * + */ +#define OPENTHREAD_CONFIG_MAC_SOFTWARE_RETRANSMIT_ENABLE 1 + +/** + * @def OPENTHREAD_CONFIG_MAC_SOFTWARE_TX_SECURITY_ENABLE + * + * Define to 1 to enable software transmission security logic. + * + */ +#define OPENTHREAD_CONFIG_MAC_SOFTWARE_TX_SECURITY_ENABLE 1 + +/** + * @def OPENTHREAD_CONFIG_MAC_SOFTWARE_TX_TIMING_ENABLE + * + * Define to 1 to enable software transmission target time logic. + * + */ +#define OPENTHREAD_CONFIG_MAC_SOFTWARE_TX_TIMING_ENABLE 1 + /** * The configurable definitions via Kconfig */ @@ -284,9 +316,3 @@ #elif CONFIG_OPENTHREAD_RADIO #define OPENTHREAD_RADIO 1 #endif - - -#define OPENTHREAD_CONFIG_MAC_SOFTWARE_CSMA_BACKOFF_ENABLE 1 -#define OPENTHREAD_CONFIG_MAC_SOFTWARE_RETRANSMIT_ENABLE 1 -#define OPENTHREAD_CONFIG_MAC_SOFTWARE_TX_SECURITY_ENABLE 1 -#define OPENTHREAD_CONFIG_MAC_SOFTWARE_TX_TIMING_ENABLE 1 diff --git a/components/openthread/radio.cmake b/components/openthread/radio.cmake index 3c5510c497..93b6f1166f 100644 --- a/components/openthread/radio.cmake +++ b/components/openthread/radio.cmake @@ -10,6 +10,7 @@ set(private_include_dirs "openthread/src/lib/hdlc" "openthread/src/lib/spinel" "openthread/src/ncp" + "private_include" ) set(src_dirs diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 7424a473b3..42781bcdf9 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -158,8 +158,6 @@ INPUT = \ $(PROJECT_PATH)/components/openthread/include/esp_openthread_lock.h \ $(PROJECT_PATH)/components/openthread/include/esp_openthread_netif_glue.h \ $(PROJECT_PATH)/components/openthread/include/esp_openthread_types.h \ - $(PROJECT_PATH)/components/openthread/include/openthread-core-esp32x-ftd-config.h \ - $(PROJECT_PATH)/components/openthread/include/openthread-core-esp32x-radio-config.h \ $(PROJECT_PATH)/components/vfs/include/esp_vfs.h \ $(PROJECT_PATH)/components/vfs/include/esp_vfs_dev.h \ $(PROJECT_PATH)/components/vfs/include/esp_vfs_eventfd.h \ diff --git a/docs/en/api-reference/network/esp_openthread.rst b/docs/en/api-reference/network/esp_openthread.rst index 21f3933191..0843047962 100644 --- a/docs/en/api-reference/network/esp_openthread.rst +++ b/docs/en/api-reference/network/esp_openthread.rst @@ -29,5 +29,3 @@ ESP-IDF provides extra apis for launching and managing the OpenThread stack, bin .. include-build-file:: inc/esp_openthread_lock.inc .. include-build-file:: inc/esp_openthread_netif_glue.inc .. include-build-file:: inc/esp_openthread_border_router.inc -.. include-build-file:: inc/openthread-core-esp32x-ftd-config.inc - diff --git a/examples/openthread/ot_rcp/README.md b/examples/openthread/ot_rcp/README.md index ac3c8ae58a..e3f3cc6fc2 100644 --- a/examples/openthread/ot_rcp/README.md +++ b/examples/openthread/ot_rcp/README.md @@ -1,69 +1,38 @@ | Supported Targets | ESP32-H2 | | ----------------- | -------- | -# OpenThread radio co-processor (RCP) example +# OpenThread Radio Co-Processor (RCP) Example -## Overview +This example demonstrates an [OpenThread Radio Co-Processor](https://openthread.io/platforms/co-processor). -This example demonstrates an openthread radio co-processor. -The RCP can receive/transmit 15.4-type packets, encode and send the packet to the host device. -You can use the RCP to implement an Openthread sniffer. You cani also connect the RCP to the host device which do not have a 15.4-radio to join in an Openthread network. +OpenThread RCP doesn't function alone, it needs to work together with a Host and this example covers two common user scenarios: +- Work with a Host Processor to perform a [Thread Border Router](https://openthread.io/guides/border-router). +- Work as a [Thread Sniffer](https://openthread.io/guides/pyspinel/sniffer). + +## How to use example + +### Hardware Required To run this example, an ESP32-H2 board is required. -### Config ESP32-H2 uart +### Configure the project -Modify the file `esp_ot_config.h`. +The default communication interface is port 0 of ESP32-H2 UART running at 115200 baud, change the configuration in [esp_ot_config.h](main/esp_ot_config.h) if you want to use another interface or need different communication parameters. -In the file `esp_ot_config.h`, there are three parameters. -As for `ESP_OPENTHREAD_DEFAULT_RADIO_CONFIG` and `ESP_OPENTHREAD_DEFAULT_PORT_CONFIG`, modification is not recommended. -As for the parameters in `ESP_OPENTHREAD_DEFAULT_HOST_CONFIG`, you can refer to ESP uart example `example/peripherals/uart/uart_echo/README.md` +### Build and Flash -### Build, Flash, and Run - -Build the project and flash it to the board +Build the project and flash it to the board: ``` idf.py -p build flash ``` -Now you'll get an ot-rcp (for this example, there is no output in console). +Now you'll get an OpenThread RCP, you can try the following use cases: -# OpenThread sniffer example (Linux or macOS based) +#### Thread Border Router -## Overview +Please refer to [ot_br](../ot_br) example for the setup steps. -This example is about how to run a sniffer to capture Thread packet, which refers to [openthread.io](https://openthread.io/guides/pyspinel/sniffer). -Openthread group just supports Linux and macOS. - -## How to use example - -### Hardware connection - -To run this example, you need an ESP32-H2 borad flashed with ot-rcp application. - -### Set up the sniffer environment - -The sniffer tool connects to an openthread RCP device and converts it into a promiscuous packet sniffer. RCP -will encode and send the packet to host after capturing a 15.4-type packet. On the host, Pyspinel should be run for -decoding the packet and generating a pcap (packet capture) stream to be saved or piped directly into Wireshark. - -Clone and install Pyspinel and dependencies, refer to [openthread.io](https://openthread.io/guides/pyspinel/sniffer#installation). - -### Install and config Wireshark - -For installing the Wireshark, refer to [Espressif Wireshark User Guide]( -https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/wireshark-user-guide.html). - -You need to config Wireshark with some properties for the Thread network. -For Wireshark configuration, refer to [openthread.io](https://openthread.io/guides/pyspinel/sniffer#thread_network_properties). - -### Run the sniffer - -For example, to sniff on Channel 15 using a device mounted at /dev/ttyUSB0 with the baudrate 115200 in the Wireshark output: - -``` -cd ~/pyspinel -python sniffer.py -c 15 -u /dev/ttyUSB0 --crc -b 115200 | wireshark -k -i - -``` +#### Thread Sniffer +Please refer to [Thread Sniffer](https://openthread.io/guides/pyspinel/sniffer) for the detailed instructions. diff --git a/examples/openthread/ot_rcp/main/esp_ot_config.h b/examples/openthread/ot_rcp/main/esp_ot_config.h index 012f31d5ce..91cbd362bd 100644 --- a/examples/openthread/ot_rcp/main/esp_ot_config.h +++ b/examples/openthread/ot_rcp/main/esp_ot_config.h @@ -27,7 +27,7 @@ .port = 0, \ .uart_config = \ { \ - .baud_rate = 92160, \ + .baud_rate = 115200, \ .data_bits = UART_DATA_8_BITS, \ .parity = UART_PARITY_DISABLE, \ .stop_bits = UART_STOP_BITS_1, \