Merge branch 'OpenThread' of https://github.com/SuGlider/arduino-esp32 into OpenThread

Author: SuGlider

libraries/OpenThread/README.md

@@ -0,0 +1,68 @@
+# ESP32 Arduino OpenThreadCLI
+
+The `OpenThreadCLI` class is an Arduino API for interacting with the OpenThread Command Line Interface (CLI). It allows you to manage and configure the Thread stack using a command-line interface. Below are the details of the class:
+The available OpenThread Commands are documented in the [OpenThread CLI Reference Page](https://openthread.io/reference/cli/commands)
+
+There is one main class called `OpenThreadCLI` and a global object used to operate OpenThread CLI, called `OThreadCLI`
+Some [helper functions](helper_functions.md) were made available for working with the OpenThread CLI environment.
+
+It is important to note that the current implementation can only be used with Espressif SoC that has support to IEEE 802.15.4, such as **ESP32-C6** and **ESP32-H2**.
+
+## Class Definition
+
+```cpp
+class OpenThreadCLI : public Stream {
+private:
+  static size_t setBuffer(xQueueHandle &queue, size_t len);
+  bool otStarted = false;
+
+public:
+  OpenThreadCLI();
+  ~OpenThreadCLI();
+  operator bool() const;
+
+  // Starts a task to read/write otStream. Default prompt is "ot> ". Set it to NULL to make it invisible.
+  void startOpenThreadConsole(Stream& otStream, bool echoback = true, const char* prompt = "ot> ");
+  void stopOpenThreadConsole();
+  void setPrompt(char* prompt);      // Changes the console prompt. NULL is an empty prompt.
+  void setEchoBack(bool echoback);   // Changes the console echoback option
+  void setStream(Stream& otStream);  // Changes the console Stream object
+  void onReceive(OnReceiveCb_t func);  // Called on a complete line of output from OT CLI, as OT Response
+
+  void begin(bool OThreadAutoStart = true);
+  void end();
+
+  // Default size is 256 bytes
+  size_t setTxBufferSize(size_t tx_queue_len);
+  // Default size is 1024 bytes
+  size_t setRxBufferSize(size_t rx_queue_len);
+
+  size_t write(uint8_t);
+  int available();
+  int read();
+  int peek();
+  void flush();
+};
+
+extern OpenThreadCLI OThreadCLI;
+```
+
+## Class Overview
+- The `OpenThreadCLI` class inherits from the `Stream` class, making it compatible with Arduino's standard I/O functions.
+- It provides methods for managing the OpenThread CLI, including starting and stopping the console, setting prompts, and handling received data.
+- You can customize the console behavior by adjusting parameters such as echoback and buffer sizes.
+
+## Public Methods
+- `startOpenThreadConsole(Stream& otStream, bool echoback = true, const char* prompt = "ot> ")`: Starts the OpenThread console with the specified stream, echoback option, and prompt.
+- `stopOpenThreadConsole()`: Stops the OpenThread console.
+- `setPrompt(char* prompt)`: Changes the console prompt (set to NULL for an empty prompt).
+- `setEchoBack(bool echoback)`: Changes the console echoback option.
+- `setStream(Stream& otStream)`: Changes the console Stream object.
+- `onReceive(OnReceiveCb_t func)`: Sets a callback function to handle complete lines of output from the OT CLI.
+- `begin(bool OThreadAutoStart = true)`: Initializes the OpenThread stack (optional auto-start).
+- `end()`: Deinitializes the OpenThread stack.
+- `setTxBufferSize(size_t tx_queue_len)`: Sets the transmit buffer size (default is 256 bytes).
+- `setRxBufferSize(size_t rx_queue_len)`: Sets the receive buffer size (default is 1024 bytes).
+- `write(uint8_t)`, `available()`, `read()`, `peek()`, `flush()`: Standard Stream methods implementation for OpenThread CLI object.
+
+

libraries/OpenThread/helper_functions.md

@@ -0,0 +1,58 @@
+# OpenThread Helper Functions and Types
+
+The following helper functions and types are designed to simplify writing Arduino sketches for OpenThread. They provide useful utilities for managing OpenThread stack behavior and interacting with the Thread network.
+
+## Enumerated Type: `ot_device_role_t`
+
+This enumeration defines the possible roles of a Thread device within the network:
+
+- `OT_ROLE_DISABLED`: The Thread stack is disabled.
+- `OT_ROLE_DETACHED`: The device is not currently participating in a Thread network/partition.
+- `OT_ROLE_CHILD`: The device operates as a Thread Child.
+- `OT_ROLE_ROUTER`: The device operates as a Thread Router.
+- `OT_ROLE_LEADER`: The device operates as a Thread Leader.
+
+## Struct: `ot_cmd_return_t`
+
+This structure represents the return status of an OpenThread CLI command:
+
+- `errorCode`: An integer representing the error code (if any).
+- `errorMessage`: A string containing an error message (if applicable).
+
+## Function: `otGetDeviceRole()`
+
+- Returns the current role of the device as an `ot_device_role_t` value.
+
+## Function: `otGetStringDeviceRole()`
+
+- Returns a human-readable string representation of the device role (e.g., "Child," "Router," etc.).
+
+## Function: `otGetRespCmd(const char* cmd, char* resp = NULL, uint32_t respTimeout = 5000)`
+
+- Executes an OpenThread CLI command and retrieves the response.
+- Parameters:
+  - `cmd`: The OpenThread CLI command to execute.
+  - `resp`: Optional buffer to store the response (if provided).
+  - `respTimeout`: Timeout (in milliseconds) for waiting for the response.
+
+## Function: `otExecCommand(const char* cmd, const char* arg, ot_cmd_return_t* returnCode = NULL)`
+
+- Executes an OpenThread CLI command with an argument.
+- Parameters:
+  - `cmd`: The OpenThread CLI command to execute.
+  - `arg`: The argument for the command.
+  - `returnCode`: Optional pointer to an `ot_cmd_return_t` structure to store the return status.
+
+## Function: `otPrintRespCLI(const char* cmd, Stream& output, uint32_t respTimeout)`
+
+- Executes an OpenThread CLI command and prints the response to the specified output stream.
+- Parameters:
+  - `cmd`: The OpenThread CLI command to execute.
+  - `output`: The output stream (e.g., Serial) to print the response.
+  - `respTimeout`: Timeout (in milliseconds) for waiting for the response.
+
+## Function: `otPrintNetworkInformation(Stream& output)`
+
+- Prints information about the current Thread network to the specified output stream.
+- Parameters:
+  - `output`: The output stream (e.g., Serial) to print the network information.