diff --git a/docs/en/libraries.rst b/docs/en/libraries.rst index daddca2b1d8..c50f91f305f 100644 --- a/docs/en/libraries.rst +++ b/docs/en/libraries.rst @@ -103,6 +103,18 @@ Matter APIs matter/matter_ep matter/ep_* +OpenThread APIs +--------------- + +.. toctree:: + :maxdepth: 1 + :glob: + + openthread/openthread + openthread/openthread_cli + openthread/openthread_core + openthread/openthread_dataset + Zigbee APIs ----------- diff --git a/docs/en/openthread/openthread.rst b/docs/en/openthread/openthread.rst new file mode 100644 index 00000000000..cfface5ca0f --- /dev/null +++ b/docs/en/openthread/openthread.rst @@ -0,0 +1,297 @@ +########## +OpenThread +########## + +About +----- + +The OpenThread library provides support for creating Thread network devices using ESP32 SoCs with IEEE 802.15.4 radio support. The library offers two different programming interfaces for interacting with the OpenThread stack: + +* **Stream-based CLI enhanced with Helper Functions API**: Command-line interface helper functions that send OpenThread CLI commands and parse responses +* **Classes API**: Object-oriented classes that directly call OpenThread API functions + +The OpenThread library is built on top of `ESP OpenThread `_ and provides a high-level Arduino-style interface for creating Thread devices. + +Thread Protocol Overview +************************ + +Thread is an IPv6-based, low-power wireless mesh networking protocol designed for smart home and IoT applications. It provides secure, reliable, and scalable connectivity for battery-powered devices. + +**Key Features:** + +* **IPv6-based**: Native IPv6 addressing and routing +* **Mesh Networking**: Self-healing mesh topology with automatic routing +* **Low Power**: Optimized for battery-operated devices +* **Security**: Built-in security features including encryption and authentication +* **Scalability**: Supports up to 250+ devices per network +* **Reliability**: Automatic route discovery and self-healing capabilities + +Thread Network Topology +*********************** + +.. code-block:: text + + ┌─────────────────┐ + │ Internet │ + └─────────────────┘ + ▲ + │ + │ + ┌─────────────────┐ + │ Wi-Fi Router │ + │ │ + └─────────────────┘ + │ + ┌───────────────┴───────────────┐ + │ │ + ▼ ▼ + ┌───────────────────────┐ ┌──────────────────┐ + │ Other Wi-Fi Devices │ │ Thread Border │ + │ │ │ Router │ + └───────────────────────┘ └──────────────────┘ + │ + │ Thread Network + │ + ┌─────────────────────────┼─────────────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ + │ Thread Leader │◄─────►│ Thread Router │◄─────►│ Thread Child │ + │ │ │ │ │ │ + └─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ + └──────────────────────────┴──────────────────────────┘ + Other Thread Nodes + + +**Thread Device Roles:** + +* **Leader**: Manages the Thread network, assigns router IDs, and maintains network state. This device shall be powered by a wall adapter. +* **Router**: Extends network range, routes messages, maintains network topology. This device shall be powered by a wall adapter. +* **Child**: End device that can sleep for extended periods (battery-powered devices). It can be powered by a battery or a wall adapter. +* **Detached**: Device not currently participating in a Thread network. +* **Disabled**: The Thread stack and interface is disabled. + +**Other Thread Network Devices:** + +* **Thread Border Router**: A device that connects a Thread network to other IP-based networks in the extrenal world. The Thread Border Router is connected to both the Thread network and external IP networks (like Wi-Fi router), enabling Thread devices to communicate with devices on other networks and the Internet. A Border Router can be implemented on a device with any Thread device role (Leader, Router, or Child). It can also act as gateway to other protocols such as MQTT or Zigbee. + +OpenThread Library Structure +---------------------------- + +**The library provides two main programming interfaces:** + +* **CLI Helper Functions API**: Functions that interact with OpenThread through the CLI interface + * ``otGetRespCmd()``: Execute CLI command and get response + * ``otExecCommand()``: Execute CLI command with arguments + * ``otPrintRespCLI()``: Execute CLI command and print response to Stream + * ``OpenThreadCLI``: Stream-based CLI interface class + +* **Classes API**: Object-oriented classes that directly call OpenThread API functions + * ``OpenThread``: Main class for managing Thread network operations + * ``DataSet``: Class for managing Thread operational datasets + +OpenThread Class +**************** + +The ``OpenThread`` class is the main entry point for Thread operations using the Classes API. It provides direct access to OpenThread API functions for managing the Thread network. + +* **Network Management**: Starting, stopping, and managing the Thread network +* **Device Role Management**: Getting and monitoring device role (Leader, Router, Child, Detached, Disabled) +* **Dataset Management**: Setting and getting operational dataset parameters +* **Address Management**: Getting mesh-local addresses, RLOC, and multicast addresses +* **Network Information**: Getting network name, channel, PAN ID, and other network parameters + +The ``OpenThread`` class is implemented as a singleton, meaning there's only one instance available globally. You access it directly as ``OThread`` without creating an instance. + +.. toctree:: + :maxdepth: 2 + + openthread_core + +DataSet Class +************* + +The ``DataSet`` class provides a convenient way to manage Thread operational datasets. It allows you to create, configure, and apply operational datasets to the Thread network. + +* **Dataset Creation**: Create new operational datasets +* **Parameter Configuration**: Set network name, channel, PAN ID, network key, and extended PAN ID +* **Dataset Application**: Apply datasets to the Thread network +* **Dataset Retrieval**: Get current dataset parameters + +.. toctree:: + :maxdepth: 2 + + openthread_dataset + +OpenThreadCLI +************* + +The ``OpenThreadCLI`` class provides a Stream-based interface for interacting with the OpenThread CLI. It allows you to send CLI commands and receive responses programmatically. + +* **CLI Interface**: Stream-based interface for sending commands and receiving responses +* **Command Execution**: Execute OpenThread CLI commands programmatically +* **Response Handling**: Parse and handle CLI command responses +* **Console Mode**: Interactive console mode for debugging and testing + +.. toctree:: + :maxdepth: 2 + + openthread_cli + +CLI Helper Functions API +************************* + +The CLI Helper Functions API provides utility functions for executing OpenThread CLI commands and parsing responses. This API is useful when you need to interact with OpenThread through the CLI interface. + +* **Command Execution**: Execute CLI commands with arguments +* **Response Parsing**: Get and parse CLI command responses +* **Error Handling**: Handle CLI command errors and return codes + +**Key Functions:** + +* ``otGetRespCmd()``: Execute CLI command and get response string +* ``otExecCommand()``: Execute CLI command with arguments and error handling +* ``otPrintRespCLI()``: Execute CLI command and print response to Stream + +For detailed documentation on the CLI Helper Functions API, see the :doc:`openthread_cli` documentation. + +Supported Hardware +------------------ + +The OpenThread library requires ESP32 SoCs with IEEE 802.15.4 radio support: + +* **ESP32-H2**: Native Thread support with IEEE 802.15.4 radio +* **ESP32-C6**: Thread support with IEEE 802.15.4 radio (when Thread is enabled) +* **ESP32-C5**: Thread support with IEEE 802.15.4 radio (when Thread is enabled) + +**Note:** Thread support must be enabled in the ESP-IDF configuration (``CONFIG_OPENTHREAD_ENABLED``). This is done automatically when using the ESP32 Arduino OpenThread library. + +Common Problems and Issues +-------------------------- + +Troubleshooting +--------------- + +Common Issues +************* + +**Thread network not starting** + * Ensure the device has IEEE 802.15.4 radio support (ESP32-H2, ESP32-C6, ESP32-C5) + * Check that Thread is enabled in ESP-IDF configuration (``CONFIG_OPENTHREAD_ENABLED``) + * Verify that ``OpenThread::begin()`` is called before using Thread functions + * Check Serial Monitor for initialization errors + +**Device not joining network** + * Verify the operational dataset parameters (network name, network key, channel, PAN ID) + * Ensure the device is within range of the Thread network + * Check that the network key and extended PAN ID match the network you're trying to join + * Verify the device role is not "Detached" + +**CLI commands not working** + * Ensure ``OpenThreadCLI::begin()`` is called before using CLI functions + * Check that ``OpenThreadCLI::startConsole()`` is called with a valid Stream + * Verify the CLI is properly initialized and running + * Check Serial Monitor for CLI initialization errors + +**Address not available** + * Wait for the device to join the Thread network (role should be Child, Router, or Leader) + * Check that the network interface is up using ``networkInterfaceUp()`` + * Verify the device has obtained a mesh-local address + * Check network connectivity using ``getRloc()`` or ``getMeshLocalEid()`` + +**Dataset not applying** + * Ensure all required dataset parameters are set (network name, network key, channel) + * Verify the dataset is valid before applying + * Check that OpenThread is started before applying the dataset + * Verify the dataset parameters match the target network + +Initialization Order +******************** + +For proper initialization, follow this order: + +1. Initialize OpenThread stack: ``OpenThread::begin()`` +2. Initialize OpenThreadCLI (if using CLI): ``OpenThreadCLI::begin()`` +3. Start CLI console (if using CLI): ``OpenThreadCLI::startConsole()`` +4. Configure dataset (if needed): Create and configure ``DataSet`` +5. Apply dataset (if needed): ``OThread.commitDataSet(dataset)`` +6. Start Thread network: ``OThread.start()`` +7. Bring network interface up: ``OThread.networkInterfaceUp()`` + +Example +------- + +Basic OpenThread Setup +********************** + +Using the Classes API: + +.. code-block:: arduino + + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread stack + OpenThread::begin(); + + // Wait for OpenThread to be ready + while (!OThread) { + delay(100); + } + + // Create and configure dataset + DataSet dataset; + dataset.initNew(); + dataset.setNetworkName("MyThreadNetwork"); + dataset.setChannel(15); + + // Apply dataset and start network + OThread.commitDataSet(dataset); + OThread.start(); + OThread.networkInterfaceUp(); + + // Print network information + OpenThread::otPrintNetworkInformation(Serial); + } + +Using the CLI Helper Functions API: + +.. code-block:: arduino + + #include + #include + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread stack + OpenThread::begin(); + + // Initialize and start CLI + OThreadCLI.begin(); + OThreadCLI.startConsole(Serial); + + // Wait for CLI to be ready + while (!OThreadCLI) { + delay(100); + } + + // Execute CLI commands + char resp[256]; + if (otGetRespCmd("state", resp)) { + Serial.printf("Thread state: %s\r\n", resp); + } + + if (otExecCommand("networkname", "MyThreadNetwork", NULL)) { + Serial.println("Network name set successfully"); + } + + if (otExecCommand("ifconfig", "up", NULL)) { + Serial.println("Network interface up"); + } + } + diff --git a/docs/en/openthread/openthread_cli.rst b/docs/en/openthread/openthread_cli.rst new file mode 100644 index 00000000000..1e73aca23db --- /dev/null +++ b/docs/en/openthread/openthread_cli.rst @@ -0,0 +1,581 @@ +############## +OpenThread CLI +############## + +About +----- + +The OpenThread CLI (Command-Line Interface) provides two ways to interact with the OpenThread stack through CLI commands: + +* **CLI Helper Functions API**: Utility functions that execute CLI commands and parse responses +* **OpenThreadCLI Class**: Stream-based interface for interactive CLI access + +The CLI Helper Functions API is useful for programmatic control using OpenThread CLI commands, while the ``OpenThreadCLI`` class provides a Stream interface for interactive console access. + +CLI Helper Functions API +************************ + +The CLI Helper Functions API consists of utility functions that execute OpenThread CLI commands and handle responses. These functions interact with the OpenThread CLI through the ``OpenThreadCLI`` interface. + +otGetRespCmd +^^^^^^^^^^^^ + +Executes a CLI command and gets the response. + +.. code-block:: arduino + + bool otGetRespCmd(const char *cmd, char *resp = NULL, uint32_t respTimeout = 5000); + +* ``cmd`` - The CLI command to execute (e.g., ``"state"``, ``"networkname"``) +* ``resp`` - Buffer to store the response (optional, can be ``NULL``) +* ``respTimeout`` - Timeout in milliseconds for waiting for response (default: 5000ms) + +This function executes a CLI command and collects all response lines until "Done" or "Error" is received. If ``resp`` is not ``NULL``, the response is stored in the buffer. + +**Returns:** ``true`` if command executed successfully, ``false`` on error or timeout. + +**Example:** + +.. code-block:: arduino + + char response[256]; + if (otGetRespCmd("state", response)) { + Serial.printf("Thread state: %s\r\n", response); + } + + if (otGetRespCmd("networkname", response)) { + Serial.printf("Network name: %s\r\n", response); + } + +otExecCommand +^^^^^^^^^^^^^ + +Executes a CLI command with arguments. + +.. code-block:: arduino + + bool otExecCommand(const char *cmd, const char *arg, ot_cmd_return_t *returnCode = NULL); + +* ``cmd`` - The CLI command to execute (e.g., ``"networkname"``, ``"channel"``) +* ``arg`` - The command argument (can be ``NULL`` for commands without arguments) +* ``returnCode`` - Pointer to ``ot_cmd_return_t`` structure to receive error information (optional) + +This function executes a CLI command with an optional argument and returns the success status. If ``returnCode`` is provided, it will be populated with error information on failure. + +**Returns:** ``true`` if command executed successfully, ``false`` on error. + +**Error Structure:** + +.. code-block:: arduino + + typedef struct { + int errorCode; // OpenThread error code + String errorMessage; // Error message string + } ot_cmd_return_t; + +**Example:** + +.. code-block:: arduino + + ot_cmd_return_t errorInfo; + + // Set network name + if (otExecCommand("networkname", "MyThreadNetwork", &errorInfo)) { + Serial.println("Network name set successfully"); + } else { + Serial.printf("Error %d: %s\r\n", errorInfo.errorCode, errorInfo.errorMessage.c_str()); + } + + // Set channel + if (otExecCommand("channel", "15", &errorInfo)) { + Serial.println("Channel set successfully"); + } + + // Bring interface up + if (otExecCommand("ifconfig", "up", NULL)) { + Serial.println("Interface is up"); + } + +otPrintRespCLI +^^^^^^^^^^^^^^ + +Executes a CLI command and prints the response to a Stream. + +.. code-block:: arduino + + bool otPrintRespCLI(const char *cmd, Stream &output, uint32_t respTimeout); + +* ``cmd`` - The CLI command to execute +* ``output`` - The Stream object to print responses to (e.g., ``Serial``) +* ``respTimeout`` - Timeout in milliseconds per response line (default: 5000ms) + +This function executes a CLI command and prints all response lines to the specified Stream until "Done" or "Error" is received. + +**Returns:** ``true`` if command executed successfully, ``false`` on error or timeout. + +**Example:** + +.. code-block:: arduino + + // Print all IP addresses + if (otPrintRespCLI("ipaddr", Serial, 5000)) { + Serial.println("IP addresses printed"); + } + + // Print all multicast addresses + if (otPrintRespCLI("ipmaddr", Serial, 5000)) { + Serial.println("Multicast addresses printed"); + } + +OpenThreadCLI Class +******************* + +The ``OpenThreadCLI`` class provides a Stream-based interface for interacting with the OpenThread CLI. It allows you to send CLI commands and receive responses programmatically or through an interactive console. + +Initialization +************** + +begin +^^^^^ + +Initializes the OpenThread CLI. + +.. code-block:: arduino + + void begin(); + +This function initializes the OpenThread CLI interface. It must be called after ``OpenThread::begin()`` and before using any CLI functions. + +**Note:** The OpenThread stack must be started before initializing the CLI. + +end +^^^ + +Stops and cleans up the OpenThread CLI. + +.. code-block:: arduino + + void end(); + +This function stops the CLI interface and cleans up all CLI resources. + +Console Management +****************** + +startConsole +^^^^^^^^^^^^ + +Starts an interactive console for CLI access. + +.. code-block:: arduino + + void startConsole(Stream &otStream, bool echoback = true, const char *prompt = "ot> "); + +* ``otStream`` - The Stream object for console I/O (e.g., ``Serial``) +* ``echoback`` - If ``true``, echo characters back to the console (default: ``true``) +* ``prompt`` - The console prompt string (default: ``"ot> "``, can be ``NULL`` for no prompt) + +This function starts an interactive console task that allows you to type CLI commands directly. The console will echo input and display responses. + +**Example:** + +.. code-block:: arduino + + OThreadCLI.startConsole(Serial, true, "ot> "); + +stopConsole +^^^^^^^^^^^ + +Stops the interactive console. + +.. code-block:: arduino + + void stopConsole(); + +This function stops the interactive console task. + +setStream +^^^^^^^^^ + +Changes the console Stream object. + +.. code-block:: arduino + + void setStream(Stream &otStream); + +* ``otStream`` - The new Stream object for console I/O + +This function changes the Stream object used by the console. + +setEchoBack +^^^^^^^^^^^ + +Changes the echo back setting. + +.. code-block:: arduino + + void setEchoBack(bool echoback); + +* ``echoback`` - If ``true``, echo characters back to the console + +This function changes whether characters are echoed back to the console. + +setPrompt +^^^^^^^^^ + +Changes the console prompt. + +.. code-block:: arduino + + void setPrompt(char *prompt); + +* ``prompt`` - The new prompt string (can be ``NULL`` for no prompt) + +This function changes the console prompt string. + +onReceive +^^^^^^^^^ + +Sets a callback function for CLI responses. + +.. code-block:: arduino + + void onReceive(OnReceiveCb_t func); + +* ``func`` - Callback function to call when a complete line of output is received + +The callback function is called whenever a complete line of output is received from the OpenThread CLI. This allows you to process CLI responses asynchronously. + +**Callback Signature:** + +.. code-block:: arduino + + typedef std::function OnReceiveCb_t; + +**Example:** + +.. code-block:: arduino + + void handleCLIResponse() { + while (OThreadCLI.available() > 0) { + char c = OThreadCLI.read(); + // Process response character + } + } + + OThreadCLI.onReceive(handleCLIResponse); + +Buffer Management +***************** + +setTxBufferSize +^^^^^^^^^^^^^^^ + +Sets the transmit buffer size. + +.. code-block:: arduino + + size_t setTxBufferSize(size_t tx_queue_len); + +* ``tx_queue_len`` - The size of the transmit buffer in bytes (default: 256) + +This function sets the size of the transmit buffer used for sending CLI commands. + +**Returns:** The actual buffer size set, or 0 on error. + +setRxBufferSize +^^^^^^^^^^^^^^^ + +Sets the receive buffer size. + +.. code-block:: arduino + + size_t setRxBufferSize(size_t rx_queue_len); + +* ``rx_queue_len`` - The size of the receive buffer in bytes (default: 1024) + +This function sets the size of the receive buffer used for receiving CLI responses. + +**Returns:** The actual buffer size set, or 0 on error. + +Stream Interface +**************** + +The ``OpenThreadCLI`` class implements the Arduino ``Stream`` interface, allowing you to use it like any other Stream object. + +write +^^^^^ + +Writes a byte to the CLI. + +.. code-block:: arduino + + size_t write(uint8_t c); + +* ``c`` - The byte to write + +This function writes a single byte to the CLI transmit buffer. + +**Returns:** The number of bytes written (1 on success, 0 on failure). + +available +^^^^^^^^^ + +Checks if data is available to read. + +.. code-block:: arduino + + int available(); + +This function returns the number of bytes available in the receive buffer. + +**Returns:** Number of bytes available, or -1 if CLI is not initialized. + +read +^^^^ + +Reads a byte from the CLI. + +.. code-block:: arduino + + int read(); + +This function reads a single byte from the CLI receive buffer. + +**Returns:** The byte read, or -1 if no data is available. + +peek +^^^^ + +Peeks at the next byte without removing it. + +.. code-block:: arduino + + int peek(); + +This function returns the next byte in the receive buffer without removing it. + +**Returns:** The byte, or -1 if no data is available. + +flush +^^^^^ + +Flushes the transmit buffer. + +.. code-block:: arduino + + void flush(); + +This function waits for all data in the transmit buffer to be sent. + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns whether the CLI is started. + +.. code-block:: arduino + + operator bool() const; + +This operator returns ``true`` if the CLI is started and ready, ``false`` otherwise. + +**Example:** + +.. code-block:: arduino + + if (OThreadCLI) { + Serial.println("CLI is ready"); + } + +Example +------- + +Using CLI Helper Functions API +****************************** + +.. code-block:: arduino + + #include + #include + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Initialize CLI + OThreadCLI.begin(); + while (!OThreadCLI) { + delay(100); + } + + // Get network state + char resp[256]; + if (otGetRespCmd("state", resp)) { + Serial.printf("Thread state: %s\r\n", resp); + } + + // Set network name + ot_cmd_return_t errorInfo; + if (otExecCommand("networkname", "MyThreadNetwork", &errorInfo)) { + Serial.println("Network name set"); + } else { + Serial.printf("Error: %s\r\n", errorInfo.errorMessage.c_str()); + } + + // Set channel + if (otExecCommand("channel", "15", NULL)) { + Serial.println("Channel set"); + } + + // Bring interface up + if (otExecCommand("ifconfig", "up", NULL)) { + Serial.println("Interface up"); + } + + // Print IP addresses + otPrintRespCLI("ipaddr", Serial, 5000); + } + +Using OpenThreadCLI Class +************************* + +Interactive Console +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + #include + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Initialize and start CLI console + OThreadCLI.begin(); + OThreadCLI.startConsole(Serial, true, "ot> "); + + Serial.println("OpenThread CLI Console Ready"); + Serial.println("Type OpenThread CLI commands (e.g., 'state', 'networkname')"); + } + +Programmatic CLI Access +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + #include + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Initialize CLI + OThreadCLI.begin(); + while (!OThreadCLI) { + delay(100); + } + + // Send CLI commands programmatically + OThreadCLI.println("state"); + delay(100); + while (OThreadCLI.available() > 0) { + char c = OThreadCLI.read(); + Serial.write(c); + } + + // Send command with argument + OThreadCLI.print("networkname "); + OThreadCLI.println("MyThreadNetwork"); + delay(100); + while (OThreadCLI.available() > 0) { + char c = OThreadCLI.read(); + Serial.write(c); + } + } + +Using Callback for Responses +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + #include + #include + + void handleCLIResponse() { + String response = ""; + while (OThreadCLI.available() > 0) { + char c = OThreadCLI.read(); + if (c == '\n' || c == '\r') { + if (response.length() > 0) { + Serial.printf("CLI Response: %s\r\n", response.c_str()); + response = ""; + } + } else { + response += c; + } + } + } + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Initialize CLI with callback + OThreadCLI.begin(); + OThreadCLI.onReceive(handleCLIResponse); + + // Send commands + OThreadCLI.println("state"); + delay(500); + OThreadCLI.println("networkname"); + delay(500); + } + +Common OpenThread CLI Commands +****************************** + +Here are some commonly used OpenThread CLI commands: + +* ``state`` - Get the current Thread state +* ``networkname `` - Set or get the network name +* ``channel `` - Set or get the channel (11-26) +* ``panid `` - Set or get the PAN ID +* ``extpanid `` - Set or get the extended PAN ID +* ``networkkey `` - Set or get the network key +* ``ifconfig up`` - Bring the network interface up +* ``ifconfig down`` - Bring the network interface down +* ``ipaddr`` - List all IPv6 addresses +* ``ipmaddr`` - List all multicast addresses +* ``rloc16`` - Get the RLOC16 +* ``leaderdata`` - Get leader data +* ``router table`` - Get router table +* ``child table`` - Get child table + +For a complete list of OpenThread CLI commands, refer to the `OpenThread CLI Reference `_. + diff --git a/docs/en/openthread/openthread_core.rst b/docs/en/openthread/openthread_core.rst new file mode 100644 index 00000000000..be207a29398 --- /dev/null +++ b/docs/en/openthread/openthread_core.rst @@ -0,0 +1,580 @@ +################ +OpenThread Class +################ + +About +----- + +The ``OpenThread`` class provides direct access to OpenThread API functions for managing Thread network operations. This is the **Classes API** approach, which offers object-oriented methods that directly call OpenThread API functions. + +**Key Features:** +* Direct OpenThread API access +* Network management (start, stop, interface control) +* Dataset management +* Address management with caching +* Network information retrieval +* Device role monitoring + +**Use Cases:** +* Thread network configuration and management +* Direct control over Thread operations +* Programmatic network setup +* Address and routing information access + +API Reference +------------- + +Initialization +************** + +begin +^^^^^ + +Initializes the OpenThread stack. + +.. code-block:: arduino + + static void begin(bool OThreadAutoStart = true); + +* ``OThreadAutoStart`` - If ``true``, automatically starts Thread with default dataset from NVS or IDF settings (default: ``true``) + +This function initializes the OpenThread stack and creates the OpenThread task. If ``OThreadAutoStart`` is ``true``, it will attempt to start Thread using the active dataset from NVS or IDF default settings. + +**Note:** This is a static function and should be called before creating an ``OpenThread`` instance. + +end +^^^ + +Stops and cleans up the OpenThread stack. + +.. code-block:: arduino + + static void end(); + +This function stops the OpenThread task and cleans up all OpenThread resources. It should be called when you no longer need the OpenThread stack. + +**Note:** This is a static function. + +Network Control +*************** + +start +^^^^^ + +Starts the Thread network. + +.. code-block:: arduino + + void start(); + +This function enables the Thread network. The device will attempt to join or form a Thread network based on the active dataset. + +**Note:** The network interface must be brought up separately using ``networkInterfaceUp()``. + +stop +^^^^ + +Stops the Thread network. + +.. code-block:: arduino + + void stop(); + +This function disables the Thread network. The device will leave the Thread network and stop participating in Thread operations. + +networkInterfaceUp +^^^^^^^^^^^^^^^^^^ + +Brings the Thread network interface up. + +.. code-block:: arduino + + void networkInterfaceUp(); + +This function enables the Thread IPv6 interface (equivalent to CLI command ``ifconfig up``). The device will be able to send and receive IPv6 packets over the Thread network. + +networkInterfaceDown +^^^^^^^^^^^^^^^^^^^^ + +Brings the Thread network interface down. + +.. code-block:: arduino + + void networkInterfaceDown(); + +This function disables the Thread IPv6 interface (equivalent to CLI command ``ifconfig down``). The device will stop sending and receiving IPv6 packets. + +Dataset Management +****************** + +commitDataSet +^^^^^^^^^^^^^ + +Commits an operational dataset to the Thread network. + +.. code-block:: arduino + + void commitDataSet(const DataSet &dataset); + +* ``dataset`` - The ``DataSet`` object containing the operational dataset parameters + +This function sets the active operational dataset for the Thread network. The dataset must be properly configured before committing. + +**Example:** + +.. code-block:: arduino + + DataSet dataset; + dataset.initNew(); + dataset.setNetworkName("MyThreadNetwork"); + dataset.setChannel(15); + dataset.setNetworkKey(networkKey); + OThread.commitDataSet(dataset); + +getCurrentDataSet +^^^^^^^^^^^^^^^^^ + +Gets the current active operational dataset. + +.. code-block:: arduino + + const DataSet &getCurrentDataSet() const; + +This function returns a reference to a ``DataSet`` object containing the current active operational dataset parameters. + +Network Information +******************* + +getNetworkName +^^^^^^^^^^^^^^ + +Gets the Thread network name. + +.. code-block:: arduino + + String getNetworkName() const; + +This function returns the network name as a ``String``. + +getExtendedPanId +^^^^^^^^^^^^^^^^ + +Gets the extended PAN ID. + +.. code-block:: arduino + + const uint8_t *getExtendedPanId() const; + +This function returns a pointer to an 8-byte array containing the extended PAN ID. + +getNetworkKey +^^^^^^^^^^^^^ + +Gets the network key. + +.. code-block:: arduino + + const uint8_t *getNetworkKey() const; + +This function returns a pointer to a 16-byte array containing the network key. + +**Note:** The network key is stored in static storage and persists after the function returns. + +getChannel +^^^^^^^^^^ + +Gets the Thread channel. + +.. code-block:: arduino + + uint8_t getChannel() const; + +This function returns the Thread channel number (11-26). + +getPanId +^^^^^^^^ + +Gets the PAN ID. + +.. code-block:: arduino + + uint16_t getPanId() const; + +This function returns the PAN ID as a 16-bit value. + +Device Role +*********** + +otGetDeviceRole +^^^^^^^^^^^^^^^ + +Gets the current device role. + +.. code-block:: arduino + + static ot_device_role_t otGetDeviceRole(); + +This function returns the current Thread device role: + +* ``OT_ROLE_DISABLED`` - The Thread stack is disabled +* ``OT_ROLE_DETACHED`` - Not currently participating in a Thread network +* ``OT_ROLE_CHILD`` - The Thread Child role +* ``OT_ROLE_ROUTER`` - The Thread Router role +* ``OT_ROLE_LEADER`` - The Thread Leader role + +**Note:** This is a static function. + +otGetStringDeviceRole +^^^^^^^^^^^^^^^^^^^^^ + +Gets the current device role as a string. + +.. code-block:: arduino + + static const char *otGetStringDeviceRole(); + +This function returns a human-readable string representation of the current device role. + +**Note:** This is a static function. + +otPrintNetworkInformation +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Prints network information to a Stream. + +.. code-block:: arduino + + static void otPrintNetworkInformation(Stream &output); + +* ``output`` - The Stream object to print to (e.g., ``Serial``) + +This function prints comprehensive network information including: +* Device role +* RLOC16 +* Network name +* Channel +* PAN ID +* Extended PAN ID +* Network key + +**Note:** This is a static function. + +Address Management +****************** + +getMeshLocalPrefix +^^^^^^^^^^^^^^^^^^ + +Gets the mesh-local prefix. + +.. code-block:: arduino + + const otMeshLocalPrefix *getMeshLocalPrefix() const; + +This function returns a pointer to the mesh-local prefix structure. + +getMeshLocalEid +^^^^^^^^^^^^^^^ + +Gets the mesh-local EID (Endpoint Identifier). + +.. code-block:: arduino + + IPAddress getMeshLocalEid() const; + +This function returns the mesh-local IPv6 address as an ``IPAddress`` object. + +getLeaderRloc +^^^^^^^^^^^^^ + +Gets the Thread Leader RLOC (Routing Locator). + +.. code-block:: arduino + + IPAddress getLeaderRloc() const; + +This function returns the IPv6 address of the Thread Leader as an ``IPAddress`` object. + +getRloc +^^^^^^^ + +Gets the node RLOC (Routing Locator). + +.. code-block:: arduino + + IPAddress getRloc() const; + +This function returns the IPv6 RLOC address of this node as an ``IPAddress`` object. + +getRloc16 +^^^^^^^^^ + +Gets the RLOC16 (16-bit Routing Locator). + +.. code-block:: arduino + + uint16_t getRloc16() const; + +This function returns the 16-bit RLOC of this node. + +Unicast Address Management +************************** + +getUnicastAddressCount +^^^^^^^^^^^^^^^^^^^^^^ + +Gets the number of unicast addresses. + +.. code-block:: arduino + + size_t getUnicastAddressCount() const; + +This function returns the number of unicast IPv6 addresses assigned to this node. The count is cached for performance. + +getUnicastAddress +^^^^^^^^^^^^^^^^^ + +Gets a unicast address by index. + +.. code-block:: arduino + + IPAddress getUnicastAddress(size_t index) const; + +* ``index`` - The index of the address (0-based) + +This function returns the unicast IPv6 address at the specified index as an ``IPAddress`` object. + +**Note:** Addresses are cached for performance. Use ``clearUnicastAddressCache()`` to refresh the cache. + +getAllUnicastAddresses +^^^^^^^^^^^^^^^^^^^^^^ + +Gets all unicast addresses. + +.. code-block:: arduino + + std::vector getAllUnicastAddresses() const; + +This function returns a vector containing all unicast IPv6 addresses assigned to this node. + +Multicast Address Management +**************************** + +getMulticastAddressCount +^^^^^^^^^^^^^^^^^^^^^^^^ + +Gets the number of multicast addresses. + +.. code-block:: arduino + + size_t getMulticastAddressCount() const; + +This function returns the number of multicast IPv6 addresses subscribed by this node. The count is cached for performance. + +getMulticastAddress +^^^^^^^^^^^^^^^^^^^ + +Gets a multicast address by index. + +.. code-block:: arduino + + IPAddress getMulticastAddress(size_t index) const; + +* ``index`` - The index of the address (0-based) + +This function returns the multicast IPv6 address at the specified index as an ``IPAddress`` object. + +**Note:** Addresses are cached for performance. Use ``clearMulticastAddressCache()`` to refresh the cache. + +getAllMulticastAddresses +^^^^^^^^^^^^^^^^^^^^^^^^ + +Gets all multicast addresses. + +.. code-block:: arduino + + std::vector getAllMulticastAddresses() const; + +This function returns a vector containing all multicast IPv6 addresses subscribed by this node. + +Cache Management +**************** + +clearUnicastAddressCache +^^^^^^^^^^^^^^^^^^^^^^^^ + +Clears the unicast address cache. + +.. code-block:: arduino + + void clearUnicastAddressCache() const; + +This function clears the cached unicast addresses. The cache will be automatically repopulated on the next address access. + +clearMulticastAddressCache +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Clears the multicast address cache. + +.. code-block:: arduino + + void clearMulticastAddressCache() const; + +This function clears the cached multicast addresses. The cache will be automatically repopulated on the next address access. + +clearAllAddressCache +^^^^^^^^^^^^^^^^^^^^ + +Clears all address caches. + +.. code-block:: arduino + + void clearAllAddressCache() const; + +This function clears both unicast and multicast address caches. + +Advanced Access +*************** + +getInstance +^^^^^^^^^^^ + +Gets the OpenThread instance pointer. + +.. code-block:: arduino + + otInstance *getInstance(); + +This function returns a pointer to the underlying OpenThread instance. This allows direct access to OpenThread API functions for advanced use cases. + +**Warning:** Direct use of the OpenThread instance requires knowledge of the OpenThread API. Use with caution. + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns whether OpenThread is started. + +.. code-block:: arduino + + operator bool() const; + +This operator returns ``true`` if OpenThread is started and ready, ``false`` otherwise. + +**Example:** + +.. code-block:: arduino + + if (OThread) { + Serial.println("OpenThread is ready"); + } + +Example +------- + +Basic Thread Network Setup +************************** + +.. code-block:: arduino + + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread stack + OpenThread::begin(); + + // Wait for OpenThread to be ready + while (!OThread) { + delay(100); + } + + // Create and configure dataset + DataSet dataset; + dataset.initNew(); + dataset.setNetworkName("MyThreadNetwork"); + dataset.setChannel(15); + + // Set network key (16 bytes) + uint8_t networkKey[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, + 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; + dataset.setNetworkKey(networkKey); + + // Apply dataset and start network + OThread.commitDataSet(dataset); + OThread.start(); + OThread.networkInterfaceUp(); + + // Wait for network to be ready + while (OpenThread::otGetDeviceRole() == OT_ROLE_DETACHED) { + delay(100); + } + + // Print network information + OpenThread::otPrintNetworkInformation(Serial); + + // Get and print addresses + Serial.printf("Mesh Local EID: %s\r\n", OThread.getMeshLocalEid().toString().c_str()); + Serial.printf("RLOC: %s\r\n", OThread.getRloc().toString().c_str()); + Serial.printf("RLOC16: 0x%04x\r\n", OThread.getRloc16()); + } + +Monitoring Device Role +********************** + +.. code-block:: arduino + + void loop() { + ot_device_role_t role = OpenThread::otGetDeviceRole(); + const char *roleStr = OpenThread::otGetStringDeviceRole(); + + Serial.printf("Current role: %s\r\n", roleStr); + + switch (role) { + case OT_ROLE_LEADER: + Serial.println("This device is the Thread Leader"); + break; + case OT_ROLE_ROUTER: + Serial.println("This device is a Thread Router"); + break; + case OT_ROLE_CHILD: + Serial.println("This device is a Thread Child"); + break; + case OT_ROLE_DETACHED: + Serial.println("This device is not attached to a network"); + break; + case OT_ROLE_DISABLED: + Serial.println("Thread is disabled"); + break; + } + + delay(5000); + } + +Address Management +****************** + +.. code-block:: arduino + + void printAddresses() { + // Print unicast addresses + size_t unicastCount = OThread.getUnicastAddressCount(); + Serial.printf("Unicast addresses: %zu\r\n", unicastCount); + for (size_t i = 0; i < unicastCount; i++) { + Serial.printf(" [%zu] %s\r\n", i, OThread.getUnicastAddress(i).toString().c_str()); + } + + // Print multicast addresses + size_t multicastCount = OThread.getMulticastAddressCount(); + Serial.printf("Multicast addresses: %zu\r\n", multicastCount); + for (size_t i = 0; i < multicastCount; i++) { + Serial.printf(" [%zu] %s\r\n", i, OThread.getMulticastAddress(i).toString().c_str()); + } + + // Clear cache to force refresh + OThread.clearAllAddressCache(); + } + diff --git a/docs/en/openthread/openthread_dataset.rst b/docs/en/openthread/openthread_dataset.rst new file mode 100644 index 00000000000..f6bb88d67e3 --- /dev/null +++ b/docs/en/openthread/openthread_dataset.rst @@ -0,0 +1,462 @@ +############# +DataSet Class +############# + +About +----- + +The ``DataSet`` class provides a convenient way to create, configure, and manage Thread operational datasets. An operational dataset contains all the parameters needed to join or form a Thread network, including network name, channel, PAN ID, network key, and extended PAN ID. + +**Key Features:** +* Create new operational datasets +* Configure dataset parameters +* Apply datasets to the Thread network +* Retrieve dataset parameters +* Clear and reset datasets + +**Use Cases:** +* Creating new Thread networks +* Joining existing Thread networks +* Configuring network parameters +* Network migration and reconfiguration + +API Reference +------------- + +Constructor +*********** + +DataSet +^^^^^^^ + +Creates a new DataSet object. + +.. code-block:: arduino + + DataSet(); + +This constructor creates an empty dataset. You must either call ``initNew()`` to create a new dataset or configure parameters manually. + +Dataset Management +****************** + +clear +^^^^^ + +Clears all dataset parameters. + +.. code-block:: arduino + + void clear(); + +This function clears all dataset parameters, resetting the dataset to an empty state. + +initNew +^^^^^^^ + +Initializes a new operational dataset. + +.. code-block:: arduino + + void initNew(); + +This function creates a new operational dataset with randomly generated values for network key, extended PAN ID, and other parameters. The dataset will be ready to form a new Thread network. + +**Note:** OpenThread must be started (``OpenThread::begin()``) before calling this function. + +**Example:** + +.. code-block:: arduino + + DataSet dataset; + dataset.initNew(); // Creates new dataset with random values + dataset.setNetworkName("MyNewNetwork"); + dataset.setChannel(15); + +getDataset +^^^^^^^^^^ + +Gets the underlying OpenThread dataset structure. + +.. code-block:: arduino + + const otOperationalDataset &getDataset() const; + +This function returns a reference to the underlying ``otOperationalDataset`` structure. This is used internally when applying the dataset to the Thread network. + +**Note:** This function is typically used internally by ``OpenThread::commitDataSet()``. + +Setters +******* + +setNetworkName +^^^^^^^^^^^^^^ + +Sets the network name. + +.. code-block:: arduino + + void setNetworkName(const char *name); + +* ``name`` - The network name string (maximum 16 characters) + +This function sets the network name for the Thread network. The network name is a human-readable identifier for the network. + +**Example:** + +.. code-block:: arduino + + dataset.setNetworkName("MyThreadNetwork"); + +setExtendedPanId +^^^^^^^^^^^^^^^^ + +Sets the extended PAN ID. + +.. code-block:: arduino + + void setExtendedPanId(const uint8_t *extPanId); + +* ``extPanId`` - Pointer to an 8-byte array containing the extended PAN ID + +This function sets the extended PAN ID, which uniquely identifies the Thread network partition. + +**Example:** + +.. code-block:: arduino + + uint8_t extPanId[8] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77}; + dataset.setExtendedPanId(extPanId); + +setNetworkKey +^^^^^^^^^^^^^ + +Sets the network key. + +.. code-block:: arduino + + void setNetworkKey(const uint8_t *key); + +* ``key`` - Pointer to a 16-byte array containing the network key + +This function sets the network key, which is used for encryption and authentication in the Thread network. + +**Example:** + +.. code-block:: arduino + + uint8_t networkKey[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, + 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; + dataset.setNetworkKey(networkKey); + +setChannel +^^^^^^^^^^ + +Sets the Thread channel. + +.. code-block:: arduino + + void setChannel(uint8_t channel); + +* ``channel`` - The Thread channel number (11-26) + +This function sets the IEEE 802.15.4 channel used by the Thread network. Valid channels are 11 through 26. + +**Example:** + +.. code-block:: arduino + + dataset.setChannel(15); // Use channel 15 + +setPanId +^^^^^^^^ + +Sets the PAN ID. + +.. code-block:: arduino + + void setPanId(uint16_t panId); + +* ``panId`` - The PAN ID (16-bit value) + +This function sets the PAN (Personal Area Network) ID for the Thread network. + +**Example:** + +.. code-block:: arduino + + dataset.setPanId(0x1234); // Set PAN ID to 0x1234 + +Getters +******* + +getNetworkName +^^^^^^^^^^^^^^ + +Gets the network name. + +.. code-block:: arduino + + const char *getNetworkName() const; + +This function returns a pointer to the network name string. + +**Returns:** Pointer to the network name, or ``NULL`` if not set. + +getExtendedPanId +^^^^^^^^^^^^^^^^ + +Gets the extended PAN ID. + +.. code-block:: arduino + + const uint8_t *getExtendedPanId() const; + +This function returns a pointer to the 8-byte extended PAN ID array. + +**Returns:** Pointer to the extended PAN ID array, or ``NULL`` if not set. + +getNetworkKey +^^^^^^^^^^^^^ + +Gets the network key. + +.. code-block:: arduino + + const uint8_t *getNetworkKey() const; + +This function returns a pointer to the 16-byte network key array. + +**Returns:** Pointer to the network key array, or ``NULL`` if not set. + +getChannel +^^^^^^^^^^ + +Gets the Thread channel. + +.. code-block:: arduino + + uint8_t getChannel() const; + +This function returns the Thread channel number. + +**Returns:** The channel number (11-26), or 0 if not set. + +getPanId +^^^^^^^^ + +Gets the PAN ID. + +.. code-block:: arduino + + uint16_t getPanId() const; + +This function returns the PAN ID. + +**Returns:** The PAN ID, or 0 if not set. + +Dataset Application +******************* + +apply +^^^^^ + +Applies the dataset to an OpenThread instance. + +.. code-block:: arduino + + void apply(otInstance *instance); + +* ``instance`` - Pointer to the OpenThread instance + +This function applies the dataset to the specified OpenThread instance, making it the active operational dataset. + +**Note:** This function is typically used internally. For normal use, use ``OpenThread::commitDataSet()`` instead. + +**Example:** + +.. code-block:: arduino + + otInstance *instance = OThread.getInstance(); + dataset.apply(instance); + +Example +------- + +Creating a New Network +********************** + +.. code-block:: arduino + + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Create a new dataset + DataSet dataset; + dataset.initNew(); // Generate random values + + // Configure network parameters + dataset.setNetworkName("MyNewThreadNetwork"); + dataset.setChannel(15); + + // Set network key (16 bytes) + uint8_t networkKey[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, + 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; + dataset.setNetworkKey(networkKey); + + // Set extended PAN ID (8 bytes) + uint8_t extPanId[8] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef}; + dataset.setExtendedPanId(extPanId); + + // Set PAN ID + dataset.setPanId(0x1234); + + // Apply dataset and start network + OThread.commitDataSet(dataset); + OThread.start(); + OThread.networkInterfaceUp(); + + Serial.println("New Thread network created"); + } + +Joining an Existing Network +*************************** + +.. code-block:: arduino + + #include + + void setup() { + Serial.begin(115200); + + // Initialize OpenThread + OpenThread::begin(); + while (!OThread) { + delay(100); + } + + // Create dataset for existing network + DataSet dataset; + + // Configure with existing network parameters + dataset.setNetworkName("ExistingThreadNetwork"); + dataset.setChannel(15); + + // Set the network key from the existing network + uint8_t networkKey[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, + 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}; + dataset.setNetworkKey(networkKey); + + // Set the extended PAN ID from the existing network + uint8_t extPanId[8] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef}; + dataset.setExtendedPanId(extPanId); + + // Set PAN ID + dataset.setPanId(0x1234); + + // Apply dataset and start network + OThread.commitDataSet(dataset); + OThread.start(); + OThread.networkInterfaceUp(); + + Serial.println("Joining existing Thread network"); + } + +Reading Current Dataset +*********************** + +.. code-block:: arduino + + void printCurrentDataset() { + // Get current dataset from OpenThread + const DataSet ¤tDataset = OThread.getCurrentDataSet(); + + // Print dataset parameters + Serial.println("Current Thread Dataset:"); + Serial.printf(" Network Name: %s\r\n", currentDataset.getNetworkName()); + Serial.printf(" Channel: %d\r\n", currentDataset.getChannel()); + Serial.printf(" PAN ID: 0x%04x\r\n", currentDataset.getPanId()); + + // Print extended PAN ID + const uint8_t *extPanId = currentDataset.getExtendedPanId(); + if (extPanId) { + Serial.print(" Extended PAN ID: "); + for (int i = 0; i < 8; i++) { + Serial.printf("%02x", extPanId[i]); + } + Serial.println(); + } + + // Print network key (first 4 bytes for security) + const uint8_t *networkKey = currentDataset.getNetworkKey(); + if (networkKey) { + Serial.print(" Network Key: "); + for (int i = 0; i < 4; i++) { + Serial.printf("%02x", networkKey[i]); + } + Serial.println("..."); + } + } + +Modifying Dataset Parameters +**************************** + +.. code-block:: arduino + + void modifyNetworkChannel() { + // Get current dataset + DataSet dataset = OThread.getCurrentDataSet(); + + // Modify channel + dataset.setChannel(20); // Change to channel 20 + + // Apply modified dataset + OThread.commitDataSet(dataset); + + Serial.println("Network channel changed to 20"); + } + +Best Practices +-------------- + +Dataset Security +**************** + +* **Network Key**: Keep the network key secure and never expose it in logs or serial output +* **Extended PAN ID**: Use unique extended PAN IDs to avoid network conflicts +* **Channel Selection**: Choose channels that avoid interference with Wi-Fi networks (channels 11, 15, 20, 25 are often good choices) + +Required Parameters +******************* + +For a dataset to be valid and usable, you typically need: + +* **Network Name**: Required for human identification +* **Network Key**: Required for security (16 bytes) +* **Channel**: Required for radio communication (11-26) +* **Extended PAN ID**: Recommended for network identification (8 bytes) +* **PAN ID**: Optional, will be assigned if not set + +Parameter Validation +******************** + +The DataSet class performs basic validation: + +* Network name length is checked (maximum 16 characters) +* Channel range is validated (11-26) +* Null pointer checks for array parameters + +However, it's your responsibility to ensure: + +* Network key is properly generated (use ``initNew()`` for random generation) +* Extended PAN ID is unique within your network environment +* All required parameters are set before applying the dataset +