New OpenThread CLI Arduino Library for ESP32-C6 and ESP32-H2 (#9908)

* feat(OThread): Add Library

* fix(OpenThread): fixes file list in CMakeLists.txt

* fix(openthread): Fixes JSON CI Files

* fix(openthread): Fixes JSON CI Files

* fix(openthread): Include Openthread guarding

* fix(openthread): COAP parametrization

* fix(openthread): Include Openthread guarding

* fix(openthread): Improves commentaries and code

* fix(openthread): Improves code

* fix(openthread): Includes StreamString.h

* feat(openthread): New Scan Example

* feat(openthread): Improved Scan Example

* feat(openthread): README.md

Initial documentation for ESP3 Arduino OpenThread CLI API.

* feat(openthread): helper functions documentation

Create helper_functions.md for ESP32 Arduino OpenThread API

* fix(openthread): begin end

* feat(openthread): onReceice example

* fix(openthread): tx queue error

* fix(doc): fixing documentation apresentation

Fixes the documentation first paragraph in order to make it easier fore reading. It also displays in the very top which SoC are supported by the library.

* fix(doc): documentation format

* feat(openthread): commentary

* fix(openthread): Typo, start/stop console

* fix(openthread): library properties

* ci(pre-commit): Apply automatic fixes

* feat(openthread): formatting text

* ci(pre-commit): Apply automatic fixes

---------

Co-authored-by: Lucas Saavedra Vaz <[email protected]>
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>

CMakeLists.txt

@@ -95,6 +95,7 @@ set(ARDUINO_ALL_LIBRARIES
   LittleFS
   NetBIOS
   Network
+  OpenThread
   PPP
   Preferences
   RainMaker
@@ -158,6 +159,10 @@ set(ARDUINO_LIBRARY_LittleFS_SRCS libraries/LittleFS/src/LittleFS.cpp)
 
 set(ARDUINO_LIBRARY_NetBIOS_SRCS libraries/NetBIOS/src/NetBIOS.cpp)
 
+set(ARDUINO_LIBRARY_OpenThread_SRCS
+  libraries/OpenThread/src/OThreadCLI.cpp
+  libraries/OpenThread/src/OThreadCLI_Util.cpp)
+
 set(ARDUINO_LIBRARY_PPP_SRCS
   libraries/PPP/src/PPP.cpp
   libraries/PPP/src/ppp.c)

libraries/OpenThread/README.md

@@ -0,0 +1,72 @@
+| Supported Targets | ESP32-C6 | ESP32-H2 |
+| ----------------- | -------- | -------- |
+
+# 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.
+
+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.
+
+The available OpenThread Commands are documented in the [OpenThread CLI Reference Page](https://openthread.io/reference/cli/commands)
+
+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**.
+
+Below are the details of the class:
+
+## 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 startConsole(Stream& otStream, bool echoback = true, const char* prompt = "ot> ");
+  void stopConsole();
+  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
+- `startConsole(Stream& otStream, bool echoback = true, const char* prompt = "ot> ")`: Starts the OpenThread console with the specified stream, echoback option, and prompt.
+- `stopConsole()`: 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/examples/COAP/coap_lamp/ci.json

@@ -0,0 +1,9 @@
+{
+    "targets": {
+      "esp32": false,
+      "esp32c2": false,
+      "esp32c3": false,
+      "esp32s2": false,
+      "esp32s3": false
+    }
+  }

libraries/OpenThread/examples/COAP/coap_lamp/coap_lamp.ino

@@ -0,0 +1,149 @@
+#include "OThreadCLI.h"
+#include "OThreadCLI_Util.h"
+
+#define OT_CHANNEL            "24"
+#define OT_NETWORK_KEY        "00112233445566778899aabbccddeeff"
+#define OT_MCAST_ADDR         "ff05::abcd"
+#define OT_COAP_RESOURCE_NAME "Lamp"
+
+const char *otSetupLeader[] = {
+  // -- clear/disable all
+  // stop CoAP
+  "coap", "stop",
+  // stop Thread
+  "thread", "stop",
+  // stop the interface
+  "ifconfig", "down",
+  // clear the dataset
+  "dataset", "clear",
+  // -- set dataset
+  // create a new complete dataset with random data
+  "dataset", "init new",
+  // set the channel
+  "dataset channel", OT_CHANNEL,
+  // set the network key
+  "dataset networkkey", OT_NETWORK_KEY,
+  // commit the dataset
+  "dataset", "commit active",
+  // -- network start
+  // start the interface
+  "ifconfig", "up",
+  // start the Thread network
+  "thread", "start"
+};
+
+const char *otCoapLamp[] = {
+  // -- create a multicast IPv6 Address for this device
+  "ipmaddr add", OT_MCAST_ADDR,
+  // -- start and create a CoAP resource
+  // start CoAP as server
+  "coap", "start",
+  // create a CoAP resource
+  "coap resource", OT_COAP_RESOURCE_NAME,
+  // set the CoAP resource initial value
+  "coap set", "0"
+};
+
+bool otDeviceSetup(const char **otSetupCmds, uint8_t nCmds1, const char **otCoapCmds, uint8_t nCmds2, ot_device_role_t expectedRole) {
+  Serial.println("Starting OpenThread.");
+  Serial.println("Running as Lamp (RGB LED) - use the other C6/H2 as a Switch");
+  uint8_t i;
+  for (i = 0; i < nCmds1; i++) {
+    if (!otExecCommand(otSetupCmds[i * 2], otSetupCmds[i * 2 + 1])) {
+      break;
+    }
+  }
+  if (i != nCmds1) {
+    log_e("Sorry, OpenThread Network setup failed!");
+    neopixelWrite(RGB_BUILTIN, 255, 0, 0);  // RED ... failed!
+    return false;
+  }
+  Serial.println("OpenThread started.\r\nWaiting for activating correct Device Role.");
+  // wait for the expected Device Role to start
+  uint8_t tries = 24;  // 24 x 2.5 sec = 1 min
+  while (tries && otGetDeviceRole() != expectedRole) {
+    Serial.print(".");
+    delay(2500);
+    tries--;
+  }
+  Serial.println();
+  if (!tries) {
+    log_e("Sorry, Device Role failed by timeout! Current Role: %s.", otGetStringDeviceRole());
+    neopixelWrite(RGB_BUILTIN, 255, 0, 0);  // RED ... failed!
+    return false;
+  }
+  Serial.printf("Device is %s.\r\n", otGetStringDeviceRole());
+  for (i = 0; i < nCmds2; i++) {
+    if (!otExecCommand(otCoapCmds[i * 2], otCoapCmds[i * 2 + 1])) {
+      break;
+    }
+  }
+  if (i != nCmds2) {
+    log_e("Sorry, OpenThread CoAP setup failed!");
+    neopixelWrite(RGB_BUILTIN, 255, 0, 0);  // RED ... failed!
+    return false;
+  }
+  Serial.println("OpenThread setup done. Node is ready.");
+  // all fine! LED goes Green
+  neopixelWrite(RGB_BUILTIN, 0, 64, 8);  // GREEN ... Lamp is ready!
+  return true;
+}
+
+void setupNode() {
+  // tries to set the Thread Network node and only returns when succeded
+  bool startedCorrectly = false;
+  while (!startedCorrectly) {
+    startedCorrectly |=
+      otDeviceSetup(otSetupLeader, sizeof(otSetupLeader) / sizeof(char *) / 2, otCoapLamp, sizeof(otCoapLamp) / sizeof(char *) / 2, OT_ROLE_LEADER);
+    if (!startedCorrectly) {
+      Serial.println("Setup Failed...\r\nTrying again...");
+    }
+  }
+}
+
+// this function is used by the Lamp mode to listen for CoAP frames from the Switch Node
+void otCOAPListen() {
+  // waits for the client to send a CoAP request
+  char cliResp[256] = {0};
+  size_t len = OThreadCLI.readBytesUntil('\n', cliResp, sizeof(cliResp));
+  cliResp[len - 1] = '\0';
+  if (strlen(cliResp)) {
+    String sResp(cliResp);
+    // cliResp shall be something like:
+    // "coap request from fd0c:94df:f1ae:b39a:ec47:ec6d:15e8:804a PUT with payload: 30"
+    // payload may be 30 or 31 (HEX) '0' or '1' (ASCII)
+    log_d("Msg[%s]", cliResp);
+    if (sResp.startsWith("coap request from") && sResp.indexOf("PUT") > 0) {
+      char payload = sResp.charAt(sResp.length() - 1);  //  last character in the payload
+      log_i("CoAP PUT [%s]\r\n", payload == '0' ? "OFF" : "ON");
+      if (payload == '0') {
+        for (int16_t c = 248; c > 16; c -= 8) {
+          neopixelWrite(RGB_BUILTIN, c, c, c);  // ramp down
+          delay(5);
+        }
+        neopixelWrite(RGB_BUILTIN, 0, 0, 0);  // Lamp Off
+      } else {
+        for (int16_t c = 16; c < 248; c += 8) {
+          neopixelWrite(RGB_BUILTIN, c, c, c);  // ramp up
+          delay(5);
+        }
+        neopixelWrite(RGB_BUILTIN, 255, 255, 255);  // Lamp On
+      }
+    }
+  }
+}
+
+void setup() {
+  Serial.begin(115200);
+  // LED starts RED, indicating not connected to Thread network.
+  neopixelWrite(RGB_BUILTIN, 64, 0, 0);
+  OThreadCLI.begin(false);     // No AutoStart is necessary
+  OThreadCLI.setTimeout(250);  // waits 250ms for the OpenThread CLI response
+  setupNode();
+  // LED goes Green when all is ready and Red when failed.
+}
+
+void loop() {
+  otCOAPListen();
+  delay(10);
+}

libraries/OpenThread/examples/COAP/coap_switch/ci.json

@@ -0,0 +1,9 @@
+{
+    "targets": {
+      "esp32": false,
+      "esp32c2": false,
+      "esp32c3": false,
+      "esp32s2": false,
+      "esp32s3": false
+    }
+  }