docs/en/openthread/openthread_core.rst
################ OpenThread Class ################
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:
Use Cases:
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 ESP-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 ESP-IDF default settings.
begin() returns only after the worker task has finished initializing the OpenThread stack and reloaded any persisted Active Operational Dataset from NVS. After it returns successfully, APIs such as hasActiveDataset() can reliably query the stack state without an additional delay loop.
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 parametersThis 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);
hasActiveDataset ^^^^^^^^^^^^^^^^
Checks whether OpenThread has a committed Active Operational Dataset.
.. code-block:: arduino
bool hasActiveDataset() const;
This function returns true when an Active Operational Dataset is available in the OpenThread stack. The dataset may have been loaded from NVS during OpenThread::begin() or committed by the application with commitDataSet().
This is useful when a sketch needs to decide whether to resume an existing Thread network or provision a new one:
.. code-block:: arduino
OpenThread::begin(false);
if (OThread.hasActiveDataset()) {
OThread.networkInterfaceUp();
OThread.start();
} else {
DataSet dataset;
dataset.initNew();
dataset.setNetworkName("MyThreadNetwork");
dataset.setChannel(15);
OThread.commitDataSet(dataset);
OThread.networkInterfaceUp();
OThread.start();
}
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 disabledOT_ROLE_DETACHED - Not currently participating in a Thread networkOT_ROLE_CHILD - The Thread Child roleOT_ROLE_ROUTER - The Thread Router roleOT_ROLE_LEADER - The Thread Leader roleNote: 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:
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<IPAddress> 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<IPAddress> 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. The Arduino wrapper methods acquire the ESP OpenThread stack lock internally, but raw ot* calls made through this pointer are outside that protection and must follow the ESP-IDF OpenThread locking rules.
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");
}
Basic Thread Network Setup
.. code-block:: arduino
#include <OThread.h>
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: %lu\r\n", (unsigned long)unicastCount);
for (size_t i = 0; i < unicastCount; i++) {
Serial.printf(" [%lu] %s\r\n", (unsigned long)i, OThread.getUnicastAddress(i).toString().c_str());
}
// Print multicast addresses
size_t multicastCount = OThread.getMulticastAddressCount();
Serial.printf("Multicast addresses: %lu\r\n", (unsigned long)multicastCount);
for (size_t i = 0; i < multicastCount; i++) {
Serial.printf(" [%lu] %s\r\n", (unsigned long)i, OThread.getMulticastAddress(i).toString().c_str());
}
// Clear cache to force refresh
OThread.clearAllAddressCache();
}