From 465ebc475ff7925bee8ce1de8e4c8b87db65cdb0 Mon Sep 17 00:00:00 2001 From: SuGlider Date: Fri, 7 Nov 2025 05:27:29 -0300 Subject: [PATCH] feat(openthread): adds examples README.md files --- .../examples/CLI/COAP/coap_lamp/README.md | 166 ++++++++++++++++ .../examples/CLI/COAP/coap_switch/README.md | 177 +++++++++++++++++ .../examples/CLI/SimpleCLI/README.md | 167 ++++++++++++++++ .../examples/CLI/SimpleNode/README.md | 132 +++++++++++++ .../ExtendedRouterNode/README.md | 164 ++++++++++++++++ .../SimpleThreadNetwork/LeaderNode/README.md | 151 ++++++++++++++ .../SimpleThreadNetwork/RouterNode/README.md | 163 ++++++++++++++++ .../examples/CLI/ThreadScan/README.md | 138 +++++++++++++ .../examples/CLI/onReceive/README.md | 131 +++++++++++++ .../SimpleThreadNetwork/LeaderNode/README.md | 184 ++++++++++++++++++ .../SimpleThreadNetwork/RouterNode/README.md | 175 +++++++++++++++++ 11 files changed, 1748 insertions(+) create mode 100644 libraries/OpenThread/examples/CLI/COAP/coap_lamp/README.md create mode 100644 libraries/OpenThread/examples/CLI/COAP/coap_switch/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleCLI/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleNode/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/README.md create mode 100644 libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/README.md create mode 100644 libraries/OpenThread/examples/CLI/ThreadScan/README.md create mode 100644 libraries/OpenThread/examples/CLI/onReceive/README.md create mode 100644 libraries/OpenThread/examples/Native/SimpleThreadNetwork/LeaderNode/README.md create mode 100644 libraries/OpenThread/examples/Native/SimpleThreadNetwork/RouterNode/README.md diff --git a/libraries/OpenThread/examples/CLI/COAP/coap_lamp/README.md b/libraries/OpenThread/examples/CLI/COAP/coap_lamp/README.md new file mode 100644 index 00000000000..0e07bc66820 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/COAP/coap_lamp/README.md @@ -0,0 +1,166 @@ +# OpenThread CoAP Lamp Example + +This example demonstrates how to create a CoAP (Constrained Application Protocol) server on a Thread network that controls an RGB LED lamp.\ +The application acts as a CoAP resource server that receives PUT requests to turn the lamp on or off, demonstrating Thread-based IoT device communication. + +## Supported Targets + +| SoC | Thread | RGB LED | Status | +| --- | ------ | ------- | ------ | +| ESP32-H2 | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | Required | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example requires a companion CoAP Switch device (coap_switch example) to control the lamp. +- The lamp device acts as a Leader node and CoAP server. + +## Features + +- CoAP server implementation on Thread network +- RGB LED control with smooth fade in/out transitions +- Leader node configuration using CLI Helper Functions API +- CoAP resource creation and management +- Multicast IPv6 address for CoAP communication +- Automatic network setup with retry mechanism +- Visual status indication using RGB LED (Red = failed, Green = ready) + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- RGB LED (built-in RGB LED or external RGB LED) +- USB cable for Serial communication +- A CoAP Switch device (coap_switch example) to control the lamp + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, you can modify the network and CoAP configuration: + +```cpp +#define OT_CHANNEL "24" +#define OT_NETWORK_KEY "00112233445566778899aabbccddeeff" +#define OT_MCAST_ADDR "ff05::abcd" +#define OT_COAP_RESOURCE_NAME "Lamp" +``` + +**Important:** +- The network key and channel must match the Switch device configuration +- The multicast address and resource name must match the Switch device +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) + +## Building and Flashing + +1. Open the `coap_lamp.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Starting OpenThread. +Running as Lamp (RGB LED) - use the other C6/H2 as a Switch +OpenThread started. +Waiting for activating correct Device Role. +........ +Device is Leader. +OpenThread setup done. Node is ready. +``` + +The RGB LED will turn **green** when the device is ready to receive CoAP commands. + +## Using the Device + +### Lamp Device Setup + +The lamp device automatically: +1. Configures itself as a Thread Leader node +2. Creates a CoAP server +3. Registers a CoAP resource named "Lamp" +4. Sets up a multicast IPv6 address for CoAP communication +5. Waits for CoAP PUT requests from the Switch device + +### CoAP Resource + +The lamp exposes a CoAP resource that accepts: +- **PUT with payload "0"**: Turns the lamp OFF (fades to black) +- **PUT with payload "1"**: Turns the lamp ON (fades to white) + +### Visual Status Indication + +The RGB LED provides visual feedback: +- **Red**: Setup failed or error occurred +- **Green**: Device is ready and waiting for CoAP commands +- **White/Black**: Lamp state (controlled by CoAP commands) + +### Working with Switch Device + +1. Start the Lamp device first (this example) +2. Start the Switch device (coap_switch example) with matching network key and channel +3. Press the button on the Switch device to toggle the lamp +4. The lamp will fade in/out smoothly when toggled + +## Code Structure + +The coap_lamp example consists of the following main components: + +1. **`otDeviceSetup()` function**: + - Configures the device as a Leader node using CLI Helper Functions + - Sets up CoAP server and resource + - Waits for device to become Leader + - Returns success/failure status + +2. **`setupNode()` function**: + - Retries setup until successful + - Calls `otDeviceSetup()` with Leader role configuration + +3. **`otCOAPListen()` function**: + - Listens for CoAP requests from the Switch device + - Parses CoAP PUT requests + - Controls RGB LED based on payload (0 = OFF, 1 = ON) + - Implements smooth fade transitions + +4. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` + - Initializes OpenThread CLI + - Sets CLI timeout + - Calls `setupNode()` to configure the device + +5. **`loop()`**: + - Continuously calls `otCOAPListen()` to process incoming CoAP requests + - Small delay for responsiveness + +## Troubleshooting + +- **LED stays red**: Setup failed. Check Serial Monitor for error messages. Verify network configuration. +- **Lamp not responding to switch**: Ensure both devices use the same network key, channel, multicast address, and resource name. Check that Switch device is running. +- **Device not becoming Leader**: Clear NVS or ensure this is the first device started. Check network configuration. +- **CoAP requests not received**: Verify multicast address matches between Lamp and Switch devices. Check Thread network connectivity. +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) +- [CoAP Protocol](https://coap.technology/) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/CLI/COAP/coap_switch/README.md b/libraries/OpenThread/examples/CLI/COAP/coap_switch/README.md new file mode 100644 index 00000000000..0346af21f4b --- /dev/null +++ b/libraries/OpenThread/examples/CLI/COAP/coap_switch/README.md @@ -0,0 +1,177 @@ +# OpenThread CoAP Switch Example + +This example demonstrates how to create a CoAP (Constrained Application Protocol) client on a Thread network that controls a remote CoAP server (lamp).\ +The application acts as a CoAP client that sends PUT requests to a lamp device, demonstrating Thread-based IoT device control. + +## Supported Targets + +| SoC | Thread | Button | Status | +| --- | ------ | ------ | ------ | +| ESP32-H2 | ✅ | Required | Fully supported | +| ESP32-C6 | ✅ | Required | Fully supported | +| ESP32-C5 | ✅ | Required | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example requires a companion CoAP Lamp device (coap_lamp example) to control. +- The switch device joins the network as a Router or Child node and acts as a CoAP client. + +## Features + +- CoAP client implementation on Thread network +- Button-based control of remote lamp device +- Router/Child node configuration using CLI Helper Functions API +- CoAP PUT request sending with confirmation +- Automatic network join with retry mechanism +- Visual status indication using RGB LED (Red = failed, Blue = ready) +- Button debouncing for reliable input + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- User button (BOOT button or external button) +- RGB LED for status indication (optional, but recommended) +- USB cable for Serial communication +- A CoAP Lamp device (coap_lamp example) must be running first + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, you can modify the network and CoAP configuration: + +```cpp +#define USER_BUTTON 9 // C6/H2 Boot button (change if needed) +#define OT_CHANNEL "24" +#define OT_NETWORK_KEY "00112233445566778899aabbccddeeff" +#define OT_MCAST_ADDR "ff05::abcd" +#define OT_COAP_RESOURCE_NAME "Lamp" +``` + +**Important:** +- The network key and channel **must match** the Lamp device configuration +- The multicast address and resource name **must match** the Lamp device +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) +- **Start the Lamp device first** before starting this Switch device + +## Building and Flashing + +1. **First, start the Lamp device** using the coap_lamp example +2. Open the `coap_switch.ino` sketch in the Arduino IDE. +3. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +4. Connect your ESP32 board to your computer via USB. +5. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Starting OpenThread. +Running as Switch - use the BOOT button to toggle the other C6/H2 as a Lamp +OpenThread started. +Waiting for activating correct Device Role. +........ +Device is Router. +OpenThread setup done. Node is ready. +``` + +The RGB LED will turn **blue** when the device is ready to send CoAP commands. + +## Using the Device + +### Switch Device Setup + +The switch device automatically: +1. Joins the existing Thread network (created by the Lamp Leader) +2. Configures itself as a Router or Child node +3. Creates a CoAP client +4. Waits for button presses to send CoAP commands + +### Button Control + +- **Press the button**: Toggles the lamp state (ON/OFF) +- The switch sends CoAP PUT requests to the lamp: + - Payload "1" = Turn lamp ON + - Payload "0" = Turn lamp OFF + +### Visual Status Indication + +The RGB LED provides visual feedback: +- **Red**: Setup failed or CoAP request failed +- **Blue**: Device is ready and can send CoAP commands +- **Red (after button press)**: CoAP request failed, device will restart setup + +### Working with Lamp Device + +1. Start the Lamp device first (coap_lamp example) +2. Start this Switch device with matching network key and channel +3. Wait for Switch device to join the network (LED turns blue) +4. Press the button on the Switch device +5. The lamp on the other device should toggle ON/OFF + +## Code Structure + +The coap_switch example consists of the following main components: + +1. **`otDeviceSetup()` function**: + - Configures the device to join an existing network using CLI Helper Functions + - Sets up CoAP client + - Waits for device to become Router or Child + - Returns success/failure status + +2. **`setupNode()` function**: + - Retries setup until successful + - Calls `otDeviceSetup()` with Router/Child role configuration + +3. **`otCoapPUT()` function**: + - Sends CoAP PUT request to the lamp device + - Waits for CoAP confirmation response + - Returns success/failure status + - Uses CLI Helper Functions to send commands and read responses + +4. **`checkUserButton()` function**: + - Monitors button state with debouncing + - Toggles lamp state on button press + - Calls `otCoapPUT()` to send commands + - Restarts setup if CoAP request fails + +5. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` + - Initializes OpenThread CLI + - Sets CLI timeout + - Calls `setupNode()` to configure the device + +6. **`loop()`**: + - Continuously calls `checkUserButton()` to monitor button input + - Small delay for responsiveness + +## Troubleshooting + +- **LED stays red**: Setup failed. Check Serial Monitor for error messages. Verify network configuration matches Lamp device. +- **Button press doesn't toggle lamp**: Ensure Lamp device is running and both devices are on the same Thread network. Check that network key, channel, multicast address, and resource name match. +- **Device not joining network**: Ensure Lamp device (Leader) is running first. Verify network key and channel match exactly. +- **CoAP request timeout**: Check Thread network connectivity. Verify multicast address and resource name match the Lamp device. Ensure Lamp device is responding. +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) +- [CoAP Protocol](https://coap.technology/) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/CLI/SimpleCLI/README.md b/libraries/OpenThread/examples/CLI/SimpleCLI/README.md new file mode 100644 index 00000000000..62c0b3f7471 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleCLI/README.md @@ -0,0 +1,167 @@ +# OpenThread Simple CLI Example + +This example demonstrates how to use the OpenThread CLI (Command-Line Interface) for interactive control of a Thread network node using an ESP32 SoC microcontroller.\ +The application provides an interactive console where you can manually configure and control the Thread network using OpenThread CLI commands. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(false)` which does not automatically start a Thread network, allowing you to manually configure it using CLI commands. + +## Features + +- Interactive OpenThread CLI console via Serial Monitor +- Manual Thread network configuration using CLI commands +- Full control over Thread network parameters (network name, channel, PAN ID, network key, etc.) +- Support for all OpenThread CLI commands +- Useful for learning OpenThread CLI and debugging Thread networks + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +No configuration is required before uploading the sketch. The example starts with a fresh Thread stack that is not automatically started, allowing you to configure it manually using CLI commands. + +## Building and Flashing + +1. Open the `SimpleCLI.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +OpenThread CLI started - type 'help' for a list of commands. +ot> +``` + +The `ot> ` prompt indicates that the OpenThread CLI console is ready. You can now type OpenThread CLI commands directly. + +## Using the Device + +### Interactive CLI Commands + +Type OpenThread CLI commands in the Serial Monitor. Some useful commands to get started: + +**Get help:** +``` +help +``` + +**Initialize a new dataset:** +``` +dataset init new +``` + +**Set network parameters:** +``` +dataset networkname MyThreadNetwork +dataset channel 15 +dataset networkkey 00112233445566778899aabbccddeeff +``` + +**Commit and start the network:** +``` +dataset commit active +ifconfig up +thread start +``` + +**Check device state:** +``` +state +``` + +**View network information:** +``` +networkname +channel +panid +ipaddr +``` + +**For a complete list of OpenThread CLI commands, refer to the** [OpenThread CLI Reference](https://openthread.io/reference/cli). + +### Example Workflow + +1. **Initialize a new Thread network (Leader):** + ``` + dataset init new + dataset networkname MyNetwork + dataset channel 15 + dataset networkkey 00112233445566778899aabbccddeeff + dataset commit active + ifconfig up + thread start + ``` + +2. **Join an existing network (Router/Child):** + ``` + dataset clear + dataset networkkey 00112233445566778899aabbccddeeff + dataset channel 15 + dataset commit active + ifconfig up + thread start + ``` + +3. **Check network status:** + ``` + state + networkname + ipaddr + ``` + +## Code Structure + +The SimpleCLI example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` (no auto-start) + - Initializes OpenThread CLI + - Starts the interactive CLI console on Serial + +2. **`loop()`**: + - Empty - all interaction happens through the CLI console + +## Troubleshooting + +- **CLI not responding**: Ensure Serial Monitor is set to 115200 baud and "Both NL & CR" line ending +- **Commands not working**: Make sure OpenThread stack is initialized (check for "OpenThread CLI started" message) +- **Network not starting**: Verify that you've committed the dataset and started the interface before starting Thread +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/CLI/SimpleNode/README.md b/libraries/OpenThread/examples/CLI/SimpleNode/README.md new file mode 100644 index 00000000000..98b4eea1faa --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleNode/README.md @@ -0,0 +1,132 @@ +# OpenThread Simple Node Example + +This example demonstrates how to create a simple OpenThread node that automatically starts in a Thread network using default settings.\ +The application automatically initializes a Thread network with default parameters and displays the current device role and network information. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin()` which automatically starts a Thread network using default settings or previously stored NVS dataset information. + +## Features + +- Automatic Thread network initialization with default settings +- Automatic device role assignment (first device becomes Leader, subsequent devices become Router or Child) +- Network information display using CLI Helper Functions API +- Periodic device role monitoring +- Support for persistent network configuration via NVS + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +No configuration is required before uploading the sketch. The example uses default Thread network parameters: + +- **Network Name**: "OpenThread-ESP" +- **Mesh Local Prefix**: "fd00:db8:a0:0::/64" +- **Channel**: 15 +- **PAN ID**: 0x1234 +- **Extended PAN ID**: "dead00beef00cafe" +- **Network Key**: "00112233445566778899aabbccddeeff" +- **PSKc**: "104810e2315100afd6bc9215a6bfac53" + +**Note:** If NVS (Non-Volatile Storage) already contains dataset information, it will be loaded from there instead of using defaults. + +## Building and Flashing + +1. Open the `SimpleNode.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +OpenThread Network Information: +Role: Leader +RLOC16: 0x0000 +Network Name: OpenThread-ESP +Channel: 15 +PAN ID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +Mesh Local EID: fd00:db8:a0:0:0:ff:fe00:0 +Leader RLOC: fd00:db8:a0:0:0:ff:fe00:0 +Node RLOC: fd00:db8:a0:0:0:ff:fe00:0 + +Thread Node State: Leader +Thread Node State: Leader +... +``` + +The first device to start will become the **Leader**. Subsequent devices will automatically join as **Router** or **Child** nodes. + +## Using the Device + +### Network Behavior + +- **First device**: Automatically becomes the Leader and creates a new Thread network +- **Subsequent devices**: Automatically join the existing network as Router or Child nodes +- **Device role**: Displayed every 5 seconds in the Serial Monitor + +### Multiple Devices + +To create a multi-device Thread network: + +1. Flash the first device - it will become the Leader +2. Flash additional devices - they will automatically join the network +3. All devices must use the same network key and channel (defaults are used if NVS is empty) + +## Code Structure + +The SimpleNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin()` (auto-start with default settings) + - Initializes OpenThread CLI + - Prints current Thread network information using `OpenThread.otPrintNetworkInformation()` + +2. **`loop()`**: + - Periodically displays the current device role using `OpenThread.otGetStringDeviceRole()` + - Updates every 5 seconds + +## Troubleshooting + +- **Device not joining network**: Ensure all devices use the same network key and channel. Check that the Leader node is running first. +- **Role stuck as "Detached"**: Wait a few seconds for the device to join the network. Verify network key and channel match the Leader. +- **No network information displayed**: Check that OpenThread stack initialized successfully (look for network information in setup) +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/README.md b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/README.md new file mode 100644 index 00000000000..390e6f4fcf8 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/ExtendedRouterNode/README.md @@ -0,0 +1,164 @@ +# OpenThread Extended Router Node Example (CLI) + +This example demonstrates how to create an OpenThread Router or Child node that joins an existing Thread network, with extended functionality showing both CLI Helper Functions API and native OpenThread API usage.\ +The example shows how to retrieve network information using both methods and demonstrates error handling. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(false)` which does not automatically start a Thread network, allowing manual configuration. +- **Important:** A Leader node must be running before starting this Router/Child node. + +## Features + +- Manual Router/Child node configuration using CLI Helper Functions API +- Joins an existing Thread network created by a Leader node +- Demonstrates both CLI Helper Functions API (`otGetRespCmd()`) and native OpenThread API (`otLinkGetPanId()`) usage +- Network information display using both API methods +- Error handling and timeout management +- Comprehensive network status monitoring + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication +- A Leader node must be running on the same network + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, configure the network parameters to match the Leader node: + +```cpp +#define CLI_NETWORK_KEY "00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANEL "24" +``` + +**Important:** +- The network key **must match** the Leader node's network key +- The channel **must match** the Leader node's channel +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) + +## Building and Flashing + +1. **First, start the Leader node** using the LeaderNode example +2. Open the `ExtendedRouterNode.ino` sketch in the Arduino IDE. +3. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +4. Connect your ESP32 board to your computer via USB. +5. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Setting up OpenThread Node as Router/Child +Make sure the Leader Node is already running + +PanID[using CLI]: 0x1234 + +PanID[using OT API]: 0x1234 + +Thread NetworkInformation: +--------------------------- +Role: Router +RLOC16: 0xfc00 +Network Name: OpenThread-ESP +Channel: 24 +PAN ID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +Mesh Local EID: fd00:db8:a0:0:0:ff:fe00:fc00 +Leader RLOC: fd00:db8:a0:0:0:ff:fe00:0 +Node RLOC: fd00:db8:a0:0:0:ff:fe00:fc00 +--------------------------- +``` + +## Using the Device + +### Extended Router/Child Node Setup + +The Extended Router/Child node is automatically configured in `setup()` using the following sequence: + +1. **Clear dataset**: Clears any existing dataset +2. **Set network key**: Configures the network security key (must match Leader) +3. **Set channel**: Configures the IEEE 802.15.4 channel (must match Leader) +4. **Commit dataset**: Applies the dataset to the active configuration +5. **Start interface**: Brings up the network interface +6. **Start Thread**: Starts the Thread network and joins the existing network +7. **Wait for role**: Waits up to 90 seconds for the device to become Router or Child + +### Dual API Demonstration + +This example demonstrates two ways to access OpenThread information: + +1. **CLI Helper Functions API**: Uses `otGetRespCmd("panid", resp)` to get PAN ID via CLI +2. **Native OpenThread API**: Uses `otLinkGetPanId(esp_openthread_get_instance())` to get PAN ID directly + +Both methods should return the same value, demonstrating API equivalence. + +### Network Information + +Once the device joins the network, the `loop()` function displays comprehensive network information using `OpenThread.otPrintNetworkInformation()`, including: +- Device role +- RLOC16 +- Network name +- Channel +- PAN ID and Extended PAN ID +- Network key +- IPv6 addresses (Mesh Local EID, Leader RLOC, Node RLOC) + +## Code Structure + +The ExtendedRouterNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` (no auto-start) + - Initializes OpenThread CLI + - Configures the device to join an existing network using CLI Helper Functions: + - `otExecCommand()` - Executes CLI commands with error handling + - Commands: "dataset clear", "dataset networkkey", "dataset channel", "dataset commit active", "ifconfig up", "thread start" + - Waits for device to become Router or Child (with 90-second timeout) + - Demonstrates dual API usage for getting PAN ID + +2. **`loop()`**: + - Displays comprehensive network information using `OpenThread.otPrintNetworkInformation()` + - Updates every 10 seconds + - Shows error message if setup failed + +## Troubleshooting + +- **Device not joining network**: Ensure the Leader node is running first. Verify network key and channel match the Leader exactly. +- **Timeout error**: The device waits 90 seconds to join. If timeout occurs, check network key and channel match the Leader. +- **Network key/channel mismatch**: Double-check that both Leader and Router/Child nodes use identical network key and channel values. +- **Setup failed message**: Check Serial Monitor for specific error messages. Verify Leader node is running and within range. +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/README.md b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/README.md new file mode 100644 index 00000000000..f33f267d724 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/LeaderNode/README.md @@ -0,0 +1,151 @@ +# OpenThread Leader Node Example (CLI) + +This example demonstrates how to create an OpenThread Leader node using the CLI Helper Functions API.\ +The Leader node is the first device in a Thread network that manages the network and assigns router IDs. This example shows how to configure a Leader node manually using OpenThread CLI commands. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(false)` which does not automatically start a Thread network, allowing manual configuration. + +## Features + +- Manual Leader node configuration using CLI Helper Functions API +- Complete dataset initialization with network key and channel +- Network information display using native OpenThread API calls +- Demonstrates both CLI Helper Functions and native OpenThread API usage +- IPv6 address listing (unicast and multicast) + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, you can modify the network configuration: + +```cpp +#define CLI_NETWORK_KEY "dataset networkkey 00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANEL "dataset channel 24" +``` + +**Important:** +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) +- All devices in the same network must use the same network key and channel + +## Building and Flashing + +1. Open the `LeaderNode.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Setting up OpenThread Node as Leader +============================================= +Thread Node State: Leader +Network Name: OpenThread-ESP +Channel: 24 +PanID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +IP Address: fd00:db8:a0:0:0:ff:fe00:0 +Multicast IP Address: ff02::1 +Multicast IP Address: ff03::1 +... +``` + +## Using the Device + +### Leader Node Setup + +The Leader node is automatically configured in `setup()` using the following sequence: + +1. **Initialize new dataset**: Creates a complete dataset with random values +2. **Set network key**: Configures the network security key +3. **Set channel**: Configures the IEEE 802.15.4 channel +4. **Commit dataset**: Applies the dataset to the active configuration +5. **Start interface**: Brings up the network interface +6. **Start Thread**: Starts the Thread network + +### Network Information + +Once the device becomes a Leader, the `loop()` function displays: +- Device role (Leader) +- Network name +- Channel +- PAN ID and Extended PAN ID +- Network key +- All IPv6 addresses (unicast and multicast) + +### Joining Other Devices + +To join other devices to this network: +1. Use the same network key and channel in the Router/Child node examples +2. Start the Leader node first +3. Then start the Router/Child nodes + +## Code Structure + +The LeaderNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` (no auto-start) + - Initializes OpenThread CLI + - Configures the device as a Leader using CLI Helper Functions: + - `OThreadCLI.println()` - Sends CLI commands + - Commands: "dataset init new", "dataset networkkey", "dataset channel", "dataset commit active", "ifconfig up", "thread start" + +2. **`loop()`**: + - Checks if device role is Leader using `OpenThread.otGetDeviceRole()` + - Displays network information using native OpenThread API calls: + - `otThreadGetNetworkName()` - Network name + - `otLinkGetChannel()` - Channel + - `otLinkGetPanId()` - PAN ID + - `otThreadGetExtendedPanId()` - Extended PAN ID + - `otThreadGetNetworkKey()` - Network key + - `otIp6GetUnicastAddresses()` - Unicast IPv6 addresses + - `otIp6GetMulticastAddresses()` - Multicast IPv6 addresses + - Updates every 5 seconds + +## Troubleshooting + +- **Device not becoming Leader**: Ensure this is the first device started, or clear NVS to start fresh +- **Network key/channel mismatch**: Verify all devices use the same network key and channel +- **No network information**: Wait for the device to become Leader (may take a few seconds) +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/README.md b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/README.md new file mode 100644 index 00000000000..acb4367bc74 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/SimpleThreadNetwork/RouterNode/README.md @@ -0,0 +1,163 @@ +# OpenThread Router/Child Node Example (CLI) + +This example demonstrates how to create an OpenThread Router or Child node that joins an existing Thread network using the CLI Helper Functions API.\ +The Router/Child node joins a network created by a Leader node and can route messages or operate as an end device. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(false)` which does not automatically start a Thread network, allowing manual configuration. +- **Important:** A Leader node must be running before starting this Router/Child node. + +## Features + +- Manual Router/Child node configuration using CLI Helper Functions API +- Joins an existing Thread network created by a Leader node +- Network information display using native OpenThread API calls +- Demonstrates both CLI Helper Functions and native OpenThread API usage +- IPv6 address listing (unicast and multicast) +- Automatic role assignment (Router or Child based on network conditions) + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication +- A Leader node must be running on the same network + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, configure the network parameters to match the Leader node: + +```cpp +#define CLI_NETWORK_KEY "dataset networkkey 00112233445566778899aabbccddeeff" +#define CLI_NETWORK_CHANEL "dataset channel 24" +``` + +**Important:** +- The network key **must match** the Leader node's network key +- The channel **must match** the Leader node's channel +- The network key must be a 32-character hexadecimal string (16 bytes) +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) + +## Building and Flashing + +1. **First, start the Leader node** using the LeaderNode example +2. Open the `RouterNode.ino` sketch in the Arduino IDE. +3. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +4. Connect your ESP32 board to your computer via USB. +5. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +Setting up OpenThread Node as Router/Child +Make sure the Leader Node is already running +============================================= +Thread Node State: Router +Network Name: OpenThread-ESP +Channel: 24 +PanID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +IP Address: fd00:db8:a0:0:0:ff:fe00:fc00 +Multicast IP Address: ff02::1 +Multicast IP Address: ff03::1 +... +``` + +The device will join as either a **Router** (if network needs more routers) or **Child** (end device). + +## Using the Device + +### Router/Child Node Setup + +The Router/Child node is automatically configured in `setup()` using the following sequence: + +1. **Clear dataset**: Clears any existing dataset +2. **Set network key**: Configures the network security key (must match Leader) +3. **Set channel**: Configures the IEEE 802.15.4 channel (must match Leader) +4. **Commit dataset**: Applies the dataset to the active configuration +5. **Start interface**: Brings up the network interface +6. **Start Thread**: Starts the Thread network and joins the existing network + +### Network Information + +Once the device joins the network (as Router or Child), the `loop()` function displays: +- Device role (Router or Child) +- Network name (from the Leader) +- Channel +- PAN ID and Extended PAN ID +- Network key +- All IPv6 addresses (unicast and multicast) + +### Multi-Device Network + +To create a multi-device Thread network: + +1. Start the Leader node first (using LeaderNode example) +2. Start Router/Child nodes (using this example) +3. All devices will form a mesh network +4. Routers extend network range and route messages +5. Children are end devices that can sleep + +## Code Structure + +The RouterNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` (no auto-start) + - Initializes OpenThread CLI + - Configures the device to join an existing network using CLI Helper Functions: + - `OThreadCLI.println()` - Sends CLI commands + - Commands: "dataset clear", "dataset networkkey", "dataset channel", "dataset commit active", "ifconfig up", "thread start" + +2. **`loop()`**: + - Checks if device role is Router or Child using `OpenThread.otGetDeviceRole()` + - Displays network information using native OpenThread API calls: + - `otThreadGetNetworkName()` - Network name + - `otLinkGetChannel()` - Channel + - `otLinkGetPanId()` - PAN ID + - `otThreadGetExtendedPanId()` - Extended PAN ID + - `otThreadGetNetworkKey()` - Network key + - `otIp6GetUnicastAddresses()` - Unicast IPv6 addresses + - `otIp6GetMulticastAddresses()` - Multicast IPv6 addresses + - Updates every 5 seconds + +## Troubleshooting + +- **Device not joining network**: Ensure the Leader node is running first. Verify network key and channel match the Leader exactly. +- **Role stuck as "Detached"**: Wait a few seconds for the device to join. Check that network key and channel match the Leader. +- **Network key/channel mismatch**: Double-check that both Leader and Router/Child nodes use identical network key and channel values. +- **No network information**: Wait for the device to join the network (may take 10-30 seconds) +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/CLI/ThreadScan/README.md b/libraries/OpenThread/examples/CLI/ThreadScan/README.md new file mode 100644 index 00000000000..adbfc091cad --- /dev/null +++ b/libraries/OpenThread/examples/CLI/ThreadScan/README.md @@ -0,0 +1,138 @@ +# OpenThread Thread Scan Example + +This example demonstrates how to scan for IEEE 802.15.4 devices and Thread networks using OpenThread CLI commands.\ +The application continuously scans for nearby devices and Thread networks, showing both raw IEEE 802.15.4 scans and Thread-specific discovery scans. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin(true)` which automatically starts a Thread network, required for Thread discovery scans. + +## Features + +- IEEE 802.15.4 device scanning (works even when Thread is not started) +- Thread network discovery scanning (requires device to be in Child, Router, or Leader state) +- Continuous scanning with configurable intervals +- Demonstrates CLI Helper Functions API for scanning +- Useful for network discovery and debugging + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +No configuration is required before uploading the sketch. The example automatically starts a Thread network for discovery scanning. + +## Building and Flashing + +1. Open the `ThreadScan.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +This sketch will continuously scan the Thread Local Network and all devices IEEE 802.15.4 compatible + +Scanning for nearby IEEE 802.15.4 devices: +| J | Network Name | Extended PAN | PAN | MAC Address | Ch | dBm | LQI | ++---+------------------+------------------+------+------------------+----+-----+-----+ +| 0 | OpenThread-ESP | dead00beef00cafe | 1234 | 1234567890abcdef | 24 | -45 | 255 | +Done + +Scanning MLE Discover: +| J | Network Name | Extended PAN | PAN | MAC Address | Ch | dBm | LQI | ++---+------------------+------------------+------+------------------+----+-----+-----+ +| 0 | OpenThread-ESP | dead00beef00cafe | 1234 | 1234567890abcdef | 24 | -45 | 255 | +Done +``` + +## Using the Device + +### Scanning Behavior + +The example performs two types of scans: + +1. **IEEE 802.15.4 Scan**: + - Scans for all IEEE 802.15.4 compatible devices in the area + - Works even when the device is not part of a Thread network + - Shows devices on all channels + +2. **Thread Discovery Scan (MLE Discover)**: + - Scans for Thread networks specifically + - Only works when the device is in Child, Router, or Leader state + - Shows Thread networks with their network names and parameters + +### Scan Results + +The scan results show: +- **J**: Joinable flag (1 = can join, 0 = cannot join) +- **Network Name**: Thread network name +- **Extended PAN**: Extended PAN ID +- **PAN**: PAN ID +- **MAC Address**: Device MAC address +- **Ch**: Channel +- **dBm**: Signal strength in dBm +- **LQI**: Link Quality Indicator + +### Continuous Scanning + +The example continuously scans: +- IEEE 802.15.4 scan every 5 seconds +- Thread discovery scan every 5 seconds (only if device is in Thread network) + +## Code Structure + +The ThreadScan example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(true)` (auto-start required for discovery) + - Initializes OpenThread CLI + - Sets CLI timeout to 100ms using `OThreadCLI.setTimeout()` + +2. **`loop()`**: + - Performs IEEE 802.15.4 scan using `otPrintRespCLI("scan", Serial, 3000)` + - Checks if device is in Thread network (Child, Router, or Leader) + - If in network, performs Thread discovery scan using `otPrintRespCLI("discover", Serial, 3000)` + - Waits 5 seconds between scan cycles + +## Troubleshooting + +- **No scan results**: Ensure there are Thread devices nearby. Check that other devices are running and on the same channel. +- **Discovery scan not working**: Wait for the device to join a Thread network (should become Child, Router, or Leader) +- **Scan timeout**: Increase the timeout value in `otPrintRespCLI()` if scans are taking longer +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/CLI/onReceive/README.md b/libraries/OpenThread/examples/CLI/onReceive/README.md new file mode 100644 index 00000000000..b584aabf0a2 --- /dev/null +++ b/libraries/OpenThread/examples/CLI/onReceive/README.md @@ -0,0 +1,131 @@ +# OpenThread CLI onReceive Callback Example + +This example demonstrates how to use the OpenThread CLI callback mechanism to capture and process CLI responses asynchronously.\ +The application shows how to set up a callback function that processes CLI responses line by line, allowing non-blocking CLI interaction. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses `OpenThread.begin()` which automatically starts a Thread network with default settings. + +## Features + +- CLI response callback using `OpenThreadCLI.onReceive()` +- Asynchronous CLI response processing +- Non-blocking CLI command execution +- Demonstrates callback-based CLI interaction pattern +- Automatic Thread network startup with default settings +- Device role monitoring via CLI + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +No configuration is required before uploading the sketch. The example automatically starts a Thread network with default settings. + +## Building and Flashing + +1. Open the `onReceive.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +OpenThread CLI RESP===> disabled +OpenThread CLI RESP===> disabled +OpenThread CLI RESP===> detached +OpenThread CLI RESP===> child +OpenThread CLI RESP===> router +OpenThread CLI RESP===> router +... +``` + +The callback function processes each line of CLI response, showing the device state transitions from "disabled" to "detached" to "child" to "router" (or "leader"). + +## Using the Device + +### Callback Mechanism + +The example demonstrates the callback-based CLI interaction pattern: + +1. **Callback Registration**: `OThreadCLI.onReceive(otReceivedLine)` registers a callback function +2. **Command Execution**: `OThreadCLI.println("state")` sends CLI commands +3. **Response Processing**: The callback function `otReceivedLine()` processes responses asynchronously +4. **Non-blocking**: The main loop continues while CLI responses are processed in the callback + +### Device State Monitoring + +The example continuously monitors the device state: +- Sends "state" command every second +- Callback processes the response +- Shows state transitions as the device joins the Thread network + +### Customizing the Callback + +You can modify the `otReceivedLine()` function to: +- Parse specific CLI responses +- Extract data from CLI output +- Trigger actions based on CLI responses +- Filter or process specific response patterns + +## Code Structure + +The onReceive example consists of the following main components: + +1. **`otReceivedLine()` callback function**: + - Reads all available data from OpenThread CLI + - Filters out empty lines (EOL sequences) + - Prints non-empty lines with a prefix + +2. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin()` (auto-start) + - Initializes OpenThread CLI + - Registers the callback function using `OThreadCLI.onReceive(otReceivedLine)` + +3. **`loop()`**: + - Sends "state" CLI command every second using `OThreadCLI.println("state")` + - The callback function processes the response asynchronously + - Non-blocking operation allows other tasks to run + +## Troubleshooting + +- **No callback responses**: Ensure the callback is registered in setup. Check that OpenThread CLI is initialized. +- **Empty lines in output**: The callback filters empty lines, which is normal behavior +- **State not changing**: Wait for the device to join the Thread network. First device becomes Leader, subsequent devices become Router or Child. +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread CLI Helper Functions API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_cli.html) +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/Native/SimpleThreadNetwork/LeaderNode/README.md b/libraries/OpenThread/examples/Native/SimpleThreadNetwork/LeaderNode/README.md new file mode 100644 index 00000000000..466de99a3ef --- /dev/null +++ b/libraries/OpenThread/examples/Native/SimpleThreadNetwork/LeaderNode/README.md @@ -0,0 +1,184 @@ +# OpenThread Leader Node Example (Native API) + +This example demonstrates how to create an OpenThread Leader node using the Classes API (native OpenThread API).\ +The Leader node is the first device in a Thread network that manages the network and assigns router IDs. This example shows how to configure a Leader node using the `OpenThread` and `DataSet` classes. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses the Classes API (`OpenThread` and `DataSet` classes) instead of CLI Helper Functions. +- This example uses `OpenThread.begin(false)` which does not use NVS dataset information, allowing fresh configuration. + +## Features + +- Leader node configuration using Classes API +- Dataset creation and configuration using `DataSet` class +- Network information display using `OpenThread` class methods +- IPv6 address management (unicast and multicast) +- Address cache management on role changes +- Comprehensive network status monitoring + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, you can modify the network configuration: + +```cpp +dataset.setNetworkName("ESP_OpenThread"); +dataset.setChannel(15); +dataset.setPanId(0x1234); +uint8_t networkKey[OT_NETWORK_KEY_SIZE] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; +dataset.setNetworkKey(networkKey); +``` + +**Important:** +- The network key must be a 16-byte array +- The channel must be between 11 and 26 (IEEE 802.15.4 channels) +- All devices in the same network must use the same network key and channel +- Extended PAN ID should be unique for your network + +## Building and Flashing + +1. Open the `LeaderNode.ino` sketch in the Arduino IDE. +2. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +3. Connect your ESP32 board to your computer via USB. +4. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +============================================== +OpenThread Network Information: +Role: Leader +RLOC16: 0x0000 +Network Name: ESP_OpenThread +Channel: 15 +PAN ID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +Mesh Local EID: fd00:db8:a0:0:0:ff:fe00:0 +Leader RLOC: fd00:db8:a0:0:0:ff:fe00:0 +Node RLOC: fd00:db8:a0:0:0:ff:fe00:0 + +--- Unicast Addresses (Using Count + Index API) --- + [0]: fd00:db8:a0:0:0:ff:fe00:0 + [1]: fe80:0:0:0:0:ff:fe00:0 + +--- Multicast Addresses (Using std::vector API) --- + [0]: ff02::1 + [1]: ff03::1 + [2]: ff03::fc +... +``` + +## Using the Device + +### Leader Node Setup + +The Leader node is automatically configured in `setup()` using the Classes API: + +1. **Initialize OpenThread**: `threadLeaderNode.begin(false)` - Starts OpenThread stack without using NVS +2. **Create dataset**: `dataset.initNew()` - Creates a new complete dataset +3. **Configure dataset**: Sets network name, extended PAN ID, network key, channel, and PAN ID +4. **Apply dataset**: `threadLeaderNode.commitDataSet(dataset)` - Applies the dataset +5. **Start network**: `threadLeaderNode.networkInterfaceUp()` and `threadLeaderNode.start()` - Starts the Thread network + +### Network Information + +The `loop()` function displays comprehensive network information using Classes API methods: +- Device role and RLOC16 +- Network name, channel, PAN ID +- Extended PAN ID and network key +- IPv6 addresses (Mesh Local EID, Leader RLOC, Node RLOC) +- Unicast addresses (using count + index API) +- Multicast addresses (using std::vector API) + +### Address Cache Management + +The example demonstrates address cache management: +- Clears address cache when device role changes +- Tracks role changes to optimize address resolution + +### Joining Other Devices + +To join other devices to this network: +1. Use the same network key and channel in the Router/Child node examples +2. Start the Leader node first +3. Then start the Router/Child nodes + +## Code Structure + +The LeaderNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` + - Creates and configures a `DataSet` object: + - `dataset.initNew()` - Initialize new dataset + - `dataset.setNetworkName()` - Set network name + - `dataset.setExtendedPanId()` - Set extended PAN ID + - `dataset.setNetworkKey()` - Set network key + - `dataset.setChannel()` - Set channel + - `dataset.setPanId()` - Set PAN ID + - Applies dataset: `threadLeaderNode.commitDataSet(dataset)` + - Starts network: `threadLeaderNode.networkInterfaceUp()` and `threadLeaderNode.start()` + +2. **`loop()`**: + - Gets current device role using `threadLeaderNode.otGetDeviceRole()` + - Displays network information using Classes API methods: + - `threadLeaderNode.otGetStringDeviceRole()` - Device role as string + - `threadLeaderNode.getRloc16()` - RLOC16 + - `threadLeaderNode.getNetworkName()` - Network name + - `threadLeaderNode.getChannel()` - Channel + - `threadLeaderNode.getPanId()` - PAN ID + - `threadLeaderNode.getExtendedPanId()` - Extended PAN ID + - `threadLeaderNode.getNetworkKey()` - Network key + - `threadLeaderNode.getMeshLocalEid()` - Mesh Local EID + - `threadLeaderNode.getLeaderRloc()` - Leader RLOC + - `threadLeaderNode.getRloc()` - Node RLOC + - `threadLeaderNode.getUnicastAddressCount()` and `threadLeaderNode.getUnicastAddress(i)` - Unicast addresses + - `threadLeaderNode.getAllMulticastAddresses()` - Multicast addresses + - Manages address cache on role changes + - Updates every 5 seconds + +## Troubleshooting + +- **Device not becoming Leader**: Ensure this is the first device started, or clear NVS to start fresh +- **Network key/channel mismatch**: Verify all devices use the same network key and channel +- **No network information**: Wait for the device to become Leader (may take a few seconds) +- **Address cache issues**: The example automatically clears cache on role changes +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Dataset API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_dataset.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. + diff --git a/libraries/OpenThread/examples/Native/SimpleThreadNetwork/RouterNode/README.md b/libraries/OpenThread/examples/Native/SimpleThreadNetwork/RouterNode/README.md new file mode 100644 index 00000000000..57cb07bd8f9 --- /dev/null +++ b/libraries/OpenThread/examples/Native/SimpleThreadNetwork/RouterNode/README.md @@ -0,0 +1,175 @@ +# OpenThread Router/Child Node Example (Native API) + +This example demonstrates how to create an OpenThread Router or Child node that joins an existing Thread network using the Classes API (native OpenThread API).\ +The Router/Child node joins a network created by a Leader node and can route messages or operate as an end device. This example shows how to configure a Router/Child node using the `OpenThread` and `DataSet` classes. + +## Supported Targets + +| SoC | Thread | Status | +| --- | ------ | ------ | +| ESP32-H2 | ✅ | Fully supported | +| ESP32-C6 | ✅ | Fully supported | +| ESP32-C5 | ✅ | Fully supported | + +### Note on Thread Support: + +- Thread support must be enabled in the ESP-IDF configuration (`CONFIG_OPENTHREAD_ENABLED`). This is done automatically when using the ESP32 Arduino OpenThread library. +- This example uses the Classes API (`OpenThread` and `DataSet` classes) instead of CLI Helper Functions. +- This example uses `OpenThread.begin(false)` which does not use NVS dataset information, allowing fresh configuration. +- **Important:** A Leader node must be running before starting this Router/Child node. + +## Features + +- Router/Child node configuration using Classes API +- Dataset configuration using `DataSet` class +- Joins an existing Thread network created by a Leader node +- Network information display using `OpenThread` class methods +- Active dataset retrieval and display +- Comprehensive network status monitoring + +## Hardware Requirements + +- ESP32 compatible development board with Thread support (ESP32-H2, ESP32-C6, or ESP32-C5) +- USB cable for Serial communication +- A Leader node must be running on the same network + +## Software Setup + +### Prerequisites + +1. Install the Arduino IDE (2.0 or newer recommended) +2. Install ESP32 Arduino Core with OpenThread support +3. ESP32 Arduino libraries: + - `OpenThread` + +### Configuration + +Before uploading the sketch, configure the network parameters to match the Leader node: + +```cpp +uint8_t networkKey[OT_NETWORK_KEY_SIZE] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; +dataset.setNetworkKey(networkKey); +``` + +**Important:** +- The network key **must match** the Leader node's network key exactly +- The network key must be a 16-byte array +- Only the network key is required to join (other parameters are learned from the Leader) +- **Start the Leader node first** before starting this Router/Child node + +## Building and Flashing + +1. **First, start the Leader node** using the LeaderNode example (Native API) +2. Open the `RouterNode.ino` sketch in the Arduino IDE. +3. Select your ESP32 board from the **Tools > Board** menu (ESP32-H2, ESP32-C6, or ESP32-C5). +4. Connect your ESP32 board to your computer via USB. +5. Click the **Upload** button to compile and flash the sketch. + +## Expected Output + +Once the sketch is running, open the Serial Monitor at a baud rate of **115200**. You should see output similar to the following: + +``` +============================================== +OpenThread Network Information (Active Dataset): +Role: Router +RLOC16: 0xfc00 +Network Name: ESP_OpenThread +Channel: 15 +PAN ID: 0x1234 +Extended PAN ID: dead00beef00cafe +Network Key: 00112233445566778899aabbccddeeff +Mesh Local EID: fd00:db8:a0:0:0:ff:fe00:fc00 +Node RLOC: fd00:db8:a0:0:0:ff:fe00:fc00 +Leader RLOC: fd00:db8:a0:0:0:ff:fe00:0 +``` + +The device will join as either a **Router** (if network needs more routers) or **Child** (end device). + +## Using the Device + +### Router/Child Node Setup + +The Router/Child node is automatically configured in `setup()` using the Classes API: + +1. **Initialize OpenThread**: `threadChildNode.begin(false)` - Starts OpenThread stack without using NVS +2. **Clear dataset**: `dataset.clear()` - Clears any existing dataset +3. **Configure dataset**: Sets only the network key (must match Leader) +4. **Apply dataset**: `threadChildNode.commitDataSet(dataset)` - Applies the dataset +5. **Start network**: `threadChildNode.networkInterfaceUp()` and `threadChildNode.start()` - Starts the Thread network and joins existing network + +### Network Information + +The `loop()` function displays network information using Classes API methods: +- Device role and RLOC16 +- Active dataset information (retrieved using `threadChildNode.getCurrentDataSet()`): + - Network name, channel, PAN ID + - Extended PAN ID and network key +- Runtime information: + - Mesh Local EID, Node RLOC, Leader RLOC + +### Active Dataset Retrieval + +This example demonstrates how to retrieve the active dataset: +- Uses `threadChildNode.getCurrentDataSet()` to get the current active dataset +- Displays dataset parameters that were learned from the Leader node +- Shows that only the network key needs to be configured to join + +### Multi-Device Network + +To create a multi-device Thread network: + +1. Start the Leader node first (using Native API LeaderNode example) +2. Start Router/Child nodes (using this example) +3. All devices will form a mesh network +4. Routers extend network range and route messages +5. Children are end devices that can sleep + +## Code Structure + +The RouterNode example consists of the following main components: + +1. **`setup()`**: + - Initializes Serial communication + - Starts OpenThread stack with `OpenThread.begin(false)` + - Creates and configures a `DataSet` object: + - `dataset.clear()` - Clear existing dataset + - `dataset.setNetworkKey()` - Set network key (must match Leader) + - Applies dataset: `threadChildNode.commitDataSet(dataset)` + - Starts network: `threadChildNode.networkInterfaceUp()` and `threadChildNode.start()` + +2. **`loop()`**: + - Gets current device role using `threadChildNode.otGetDeviceRole()` + - Retrieves active dataset using `threadChildNode.getCurrentDataSet()` + - Displays network information using Classes API methods: + - `threadChildNode.otGetStringDeviceRole()` - Device role as string + - `threadChildNode.getRloc16()` - RLOC16 + - `activeDataset.getNetworkName()` - Network name from dataset + - `activeDataset.getChannel()` - Channel from dataset + - `activeDataset.getPanId()` - PAN ID from dataset + - `activeDataset.getExtendedPanId()` - Extended PAN ID from dataset + - `activeDataset.getNetworkKey()` - Network key from dataset + - `threadChildNode.getMeshLocalEid()` - Mesh Local EID + - `threadChildNode.getRloc()` - Node RLOC + - `threadChildNode.getLeaderRloc()` - Leader RLOC + - Updates every 5 seconds + +## Troubleshooting + +- **Device not joining network**: Ensure the Leader node is running first. Verify network key matches the Leader exactly. +- **Role stuck as "Detached"**: Wait a few seconds for the device to join. Check that network key matches the Leader. +- **Network key mismatch**: Double-check that both Leader and Router/Child nodes use identical network key values. +- **No network information**: Wait for the device to join the network (may take 10-30 seconds) +- **Active dataset empty**: Ensure device has successfully joined the network before checking dataset +- **No serial output**: Check baudrate (115200) and USB connection + +## Related Documentation + +- [OpenThread Core API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_core.html) +- [OpenThread Dataset API](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread_dataset.html) +- [OpenThread Overview](https://docs.espressif.com/projects/arduino-esp32/en/latest/openthread/openthread.html) + +## License + +This example is licensed under the Apache License, Version 2.0. +