Instance

This module includes functions that control the OpenThread Instance.

Summary

Typedefs
otChangedFlags typedef
uint32_t
Represents a bit-field indicating specific state/configuration that has changed.
otInstance typedef
struct otInstance
Represents the OpenThread instance structure.
otStateChangedCallback)(otChangedFlags aFlags, void *aContext) typedef
void(*
Pointer is called to notify certain configuration or state changes within OpenThread.

Functions
otGetRadioVersionString(otInstance *aInstance)
const char *
Gets the OpenThread radio version string.
otGetVersionString(void)
const char *
Gets the OpenThread version string.
otInstanceErasePersistentInfo(otInstance *aInstance)
Erases all the OpenThread persistent info (network settings) stored on non-volatile memory.
otInstanceFactoryReset(otInstance *aInstance)
void
Deletes all the settings stored on non-volatile memory, and then triggers a platform reset.
otInstanceFinalize(otInstance *aInstance)
void
Disables the OpenThread library.
otInstanceGetId(otInstance *aInstance)
uint32_t
Gets the instance identifier.
otInstanceGetUptime(otInstance *aInstance)
uint64_t
Returns the current instance uptime (in msec).
otInstanceGetUptimeAsString(otInstance *aInstance, char *aBuffer, uint16_t aSize)
void
Returns the current instance uptime as a human-readable string.
otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)
Initializes the OpenThread library.
otInstanceInitMultiple(uint8_t aIdx)
Initializes the OpenThread instance.
otInstanceInitSingle(void)
Initializes the static single instance of the OpenThread library.
otInstanceIsInitialized(otInstance *aInstance)
bool
Indicates whether or not the instance is valid/initialized.
otInstanceReset(otInstance *aInstance)
void
Triggers a platform reset.
otInstanceResetRadioStack(otInstance *aInstance)
void
Resets the internal states of the OpenThread radio stack.
otInstanceResetToBootloader(otInstance *aInstance)
Triggers a platform reset to bootloader mode, if supported.
otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext)
void
Removes a callback to indicate when certain configuration or state changes within OpenThread.
otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext)
Registers a callback to indicate when certain configuration or state changes within OpenThread.

Macros
OT_CHANGED_ACTIVE_DATASET (1U << 28)
Active Operational Dataset changed.
OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL (1U << 21)
Channel Manager new pending Thread channel changed.
OT_CHANGED_COMMISSIONER_STATE (1U << 23)
Commissioner state changed.
OT_CHANGED_IP6_ADDRESS_ADDED (1U << 0)
IPv6 address was added.
OT_CHANGED_IP6_ADDRESS_REMOVED (1U << 1)
IPv6 address was removed.
OT_CHANGED_IP6_MULTICAST_SUBSCRIBED (1U << 12)
Subscribed to a IPv6 multicast address.
OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED (1U << 13)
Unsubscribed from a IPv6 multicast address.
OT_CHANGED_JOINER_STATE (1U << 27)
Joiner state changed.
OT_CHANGED_NAT64_TRANSLATOR_STATE (1U << 30)
The state of NAT64 translator changed.
OT_CHANGED_NETWORK_KEY (1U << 18)
Network key changed.
OT_CHANGED_PARENT_LINK_QUALITY (1U << 31)
Parent link quality changed.
OT_CHANGED_PENDING_DATASET (1U << 29)
Pending Operational Dataset changed.
OT_CHANGED_PSKC (1U << 19)
PSKc changed.
OT_CHANGED_SECURITY_POLICY (1U << 20)
Security Policy changed.
OT_CHANGED_SUPPORTED_CHANNEL_MASK (1U << 22)
Supported channel mask changed.
OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL (1U << 26)
Local Backbone Router configuration changed.
OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE (1U << 25)
Backbone Router state changed.
OT_CHANGED_THREAD_CHANNEL (1U << 14)
Thread network channel changed.
OT_CHANGED_THREAD_CHILD_ADDED (1U << 10)
Child was added.
OT_CHANGED_THREAD_CHILD_REMOVED (1U << 11)
Child was removed.
OT_CHANGED_THREAD_EXT_PANID (1U << 17)
Thread network extended PAN ID changed.
OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER (1U << 8)
Thread Key Sequence changed.
OT_CHANGED_THREAD_LL_ADDR (1U << 3)
The link-local address changed.
OT_CHANGED_THREAD_ML_ADDR (1U << 4)
The mesh-local address changed.
OT_CHANGED_THREAD_NETDATA (1U << 9)
Thread Network Data changed.
OT_CHANGED_THREAD_NETIF_STATE (1U << 24)
Thread network interface state changed.
OT_CHANGED_THREAD_NETWORK_NAME (1U << 16)
Thread network name changed.
OT_CHANGED_THREAD_PANID (1U << 15)
Thread network PAN Id changed.
OT_CHANGED_THREAD_PARTITION_ID (1U << 7)
Partition ID changed.
OT_CHANGED_THREAD_RLOC_ADDED (1U << 5)
RLOC was added.
OT_CHANGED_THREAD_RLOC_REMOVED (1U << 6)
RLOC was removed.
OT_CHANGED_THREAD_ROLE (1U << 2)
Role (disabled, detached, child, router, leader) changed.
OT_UPTIME_STRING_SIZE 24
Recommended size for string representation of uptime.

Typedefs

otChangedFlags

uint32_t otChangedFlags

Represents a bit-field indicating specific state/configuration that has changed.

See OT_CHANGED_* definitions.

otInstance

struct otInstance otInstance

Represents the OpenThread instance structure.

otStateChangedCallback

void(* otStateChangedCallback)(otChangedFlags aFlags, void *aContext)

Pointer is called to notify certain configuration or state changes within OpenThread.

Details
Parameters
[in] aFlags
A bit-field indicating specific state that has changed. See OT_CHANGED_* definitions.
[in] aContext
A pointer to application-specific context.

Functions

otGetRadioVersionString

const char * otGetRadioVersionString(
  otInstance *aInstance
)

Gets the OpenThread radio version string.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
A pointer to the OpenThread radio version.

otGetVersionString

const char * otGetVersionString(
  void
)

Gets the OpenThread version string.

Details
Returns
A pointer to the OpenThread version.

otInstanceErasePersistentInfo

otError otInstanceErasePersistentInfo(
  otInstance *aInstance
)

Erases all the OpenThread persistent info (network settings) stored on non-volatile memory.

Erase is successful only if the device is in disabled state/role.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_ERROR_NONE
All persistent info/state was erased successfully.
OT_ERROR_INVALID_STATE
Device is not in disabled state/role.

otInstanceFactoryReset

void otInstanceFactoryReset(
  otInstance *aInstance
)

Deletes all the settings stored on non-volatile memory, and then triggers a platform reset.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otInstanceFinalize

void otInstanceFinalize(
  otInstance *aInstance
)

Disables the OpenThread library.

Call this function when OpenThread is no longer in use.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otInstanceGetId

uint32_t otInstanceGetId(
  otInstance *aInstance
)

Gets the instance identifier.

The instance identifier is set to a random value when the instance is constructed, and then its value will not change after initialization.

Details
Returns
The instance identifier.

otInstanceGetUptime

uint64_t otInstanceGetUptime(
  otInstance *aInstance
)

Returns the current instance uptime (in msec).

Requires OPENTHREAD_CONFIG_UPTIME_ENABLE to be enabled.

The uptime is given as number of milliseconds since OpenThread instance was initialized.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The uptime (number of milliseconds).

otInstanceGetUptimeAsString

void otInstanceGetUptimeAsString(
  otInstance *aInstance,
  char *aBuffer,
  uint16_t aSize
)

Returns the current instance uptime as a human-readable string.

Requires OPENTHREAD_CONFIG_UPTIME_ENABLE to be enabled.

The string follows the format "::." for hours, minutes, seconds and millisecond (if uptime is shorter than one day) or "

d.::." (if longer than a day).

If the resulting string does not fit in aBuffer (within its aSize characters), the string will be truncated but the outputted string is always null-terminated.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aBuffer
A pointer to a char array to output the string.
[in] aSize
The size of aBuffer (in bytes). Recommended to use OT_UPTIME_STRING_SIZE.

otInstanceInit

otInstance * otInstanceInit(
  void *aInstanceBuffer,
  size_t *aInstanceBufferSize
)

Initializes the OpenThread library.

Initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be called before any other calls to OpenThread.

Is available and can only be used when support for multiple OpenThread instances is enabled.

Details
Parameters
[in] aInstanceBuffer
The buffer for OpenThread to use for allocating the otInstance structure.
[in,out] aInstanceBufferSize
On input, the size of aInstanceBuffer. On output, if not enough space for otInstance, the number of bytes required for otInstance.
Returns
A pointer to the new OpenThread instance.
See also:
otInstanceFinalize

otInstanceInitMultiple

otInstance * otInstanceInitMultiple(
  uint8_t aIdx
)

Initializes the OpenThread instance.

This function initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be called before any other calls to OpenThread. This method utilizes static buffer to initialize the OpenThread instance.

This function is available and can only be used when support for multiple OpenThread static instances is enabled (OPENTHREAD_CONFIG_MULTIPLE_STATIC_INSTANCE_ENABLE)

Details
Parameters
[in] aIdx
The index of the OpenThread instance to initialize.
Returns
A pointer to the new OpenThread instance.

otInstanceInitSingle

otInstance * otInstanceInitSingle(
  void
)

Initializes the static single instance of the OpenThread library.

Initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be called before any other calls to OpenThread.

Is available and can only be used when support for multiple OpenThread instances is disabled.

Details
Returns
A pointer to the single OpenThread instance.

otInstanceIsInitialized

bool otInstanceIsInitialized(
  otInstance *aInstance
)

Indicates whether or not the instance is valid/initialized.

The instance is considered valid if it is acquired and initialized using either otInstanceInitSingle() (in single instance case) or otInstanceInit() (in multi instance case). A subsequent call to otInstanceFinalize() causes the instance to be considered as uninitialized.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
TRUE if the given instance is valid/initialized, FALSE otherwise.

otInstanceReset

void otInstanceReset(
  otInstance *aInstance
)

Triggers a platform reset.

The reset process ensures that all the OpenThread state/info (stored in volatile memory) is erased. Note that the otPlatformReset does not erase any persistent state/info saved in non-volatile memory.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otInstanceResetRadioStack

void otInstanceResetRadioStack(
  otInstance *aInstance
)

Resets the internal states of the OpenThread radio stack.

Callbacks and configurations are preserved.

This API is only available under radio builds (OPENTHREAD_RADIO = 1).

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.

otInstanceResetToBootloader

otError otInstanceResetToBootloader(
  otInstance *aInstance
)

Triggers a platform reset to bootloader mode, if supported.

Requires OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENABLE.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_ERROR_NONE
Reset to bootloader successfully.
OT_ERROR_BUSY
Failed due to another operation is ongoing.
OT_ERROR_NOT_CAPABLE
Not capable of resetting to bootloader.

otRemoveStateChangeCallback

void otRemoveStateChangeCallback(
  otInstance *aInstance,
  otStateChangedCallback aCallback,
  void *aContext
)

Removes a callback to indicate when certain configuration or state changes within OpenThread.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aCallback
A pointer to a function that is called with certain configuration or state changes.
[in] aContext
A pointer to application-specific context.

otSetStateChangedCallback

otError otSetStateChangedCallback(
  otInstance *aInstance,
  otStateChangedCallback aCallback,
  void *aContext
)

Registers a callback to indicate when certain configuration or state changes within OpenThread.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aCallback
A pointer to a function that is called with certain configuration or state changes.
[in] aContext
A pointer to application-specific context.
Return Values
OT_ERROR_NONE
Added the callback to the list of callbacks.
OT_ERROR_ALREADY
The callback was already registered.
OT_ERROR_NO_BUFS
Could not add the callback due to resource constraints.

Macros

OT_CHANGED_ACTIVE_DATASET

 OT_CHANGED_ACTIVE_DATASET (1U << 28)

Active Operational Dataset changed.

OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL

 OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL (1U << 21)

Channel Manager new pending Thread channel changed.

OT_CHANGED_COMMISSIONER_STATE

 OT_CHANGED_COMMISSIONER_STATE (1U << 23)

Commissioner state changed.

OT_CHANGED_IP6_ADDRESS_ADDED

 OT_CHANGED_IP6_ADDRESS_ADDED (1U << 0)

IPv6 address was added.

OT_CHANGED_IP6_ADDRESS_REMOVED

 OT_CHANGED_IP6_ADDRESS_REMOVED (1U << 1)

IPv6 address was removed.

OT_CHANGED_IP6_MULTICAST_SUBSCRIBED

 OT_CHANGED_IP6_MULTICAST_SUBSCRIBED (1U << 12)

Subscribed to a IPv6 multicast address.

OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED

 OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED (1U << 13)

Unsubscribed from a IPv6 multicast address.

OT_CHANGED_JOINER_STATE

 OT_CHANGED_JOINER_STATE (1U << 27)

Joiner state changed.

OT_CHANGED_NAT64_TRANSLATOR_STATE

 OT_CHANGED_NAT64_TRANSLATOR_STATE (1U << 30)

The state of NAT64 translator changed.

OT_CHANGED_NETWORK_KEY

 OT_CHANGED_NETWORK_KEY (1U << 18)

Network key changed. 

 OT_CHANGED_PARENT_LINK_QUALITY (1U << 31)

Parent link quality changed.

OT_CHANGED_PENDING_DATASET

 OT_CHANGED_PENDING_DATASET (1U << 29)

Pending Operational Dataset changed.

OT_CHANGED_PSKC

 OT_CHANGED_PSKC (1U << 19)

PSKc changed.

OT_CHANGED_SECURITY_POLICY

 OT_CHANGED_SECURITY_POLICY (1U << 20)

Security Policy changed.

OT_CHANGED_SUPPORTED_CHANNEL_MASK

 OT_CHANGED_SUPPORTED_CHANNEL_MASK (1U << 22)

Supported channel mask changed.

OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL

 OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL (1U << 26)

Local Backbone Router configuration changed.

OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE

 OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE (1U << 25)

Backbone Router state changed.

OT_CHANGED_THREAD_CHANNEL

 OT_CHANGED_THREAD_CHANNEL (1U << 14)

Thread network channel changed.

OT_CHANGED_THREAD_CHILD_ADDED

 OT_CHANGED_THREAD_CHILD_ADDED (1U << 10)

Child was added.

OT_CHANGED_THREAD_CHILD_REMOVED

 OT_CHANGED_THREAD_CHILD_REMOVED (1U << 11)

Child was removed.

OT_CHANGED_THREAD_EXT_PANID

 OT_CHANGED_THREAD_EXT_PANID (1U << 17)

Thread network extended PAN ID changed.

OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER

 OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER (1U << 8)

Thread Key Sequence changed.

OT_CHANGED_THREAD_LL_ADDR

 OT_CHANGED_THREAD_LL_ADDR (1U << 3)

The link-local address changed.

OT_CHANGED_THREAD_ML_ADDR

 OT_CHANGED_THREAD_ML_ADDR (1U << 4)

The mesh-local address changed.

OT_CHANGED_THREAD_NETDATA

 OT_CHANGED_THREAD_NETDATA (1U << 9)

Thread Network Data changed.

OT_CHANGED_THREAD_NETIF_STATE

 OT_CHANGED_THREAD_NETIF_STATE (1U << 24)

Thread network interface state changed.

OT_CHANGED_THREAD_NETWORK_NAME

 OT_CHANGED_THREAD_NETWORK_NAME (1U << 16)

Thread network name changed.

OT_CHANGED_THREAD_PANID

 OT_CHANGED_THREAD_PANID (1U << 15)

Thread network PAN Id changed.

OT_CHANGED_THREAD_PARTITION_ID

 OT_CHANGED_THREAD_PARTITION_ID (1U << 7)

Partition ID changed.

OT_CHANGED_THREAD_RLOC_ADDED

 OT_CHANGED_THREAD_RLOC_ADDED (1U << 5)

RLOC was added.

OT_CHANGED_THREAD_RLOC_REMOVED

 OT_CHANGED_THREAD_RLOC_REMOVED (1U << 6)

RLOC was removed.

OT_CHANGED_THREAD_ROLE

 OT_CHANGED_THREAD_ROLE (1U << 2)

Role (disabled, detached, child, router, leader) changed.

OT_UPTIME_STRING_SIZE

 OT_UPTIME_STRING_SIZE 24

Recommended size for string representation of uptime.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.