Instance#

This module includes functions that control the OpenThread Instance.

Typedefs#

typedef struct otInstance

Represents the OpenThread instance structure.

typedef uint32_t

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

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

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

Functions#

otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)

Initializes the OpenThread library.

Initializes the static single instance of the OpenThread library.

uint32_t
otInstanceGetId(otInstance *aInstance)

Gets the instance identifier.

bool
otInstanceIsInitialized(otInstance *aInstance)

Indicates whether or not the instance is valid/initialized.

void
otInstanceFinalize(otInstance *aInstance)

Disables the OpenThread library.

uint64_t
otInstanceGetUptime(otInstance *aInstance)

Returns the current instance uptime (in msec).

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

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

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

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

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

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

void
otInstanceReset(otInstance *aInstance)

Triggers a platform reset.

otInstanceResetToBootloader(otInstance *aInstance)

Triggers a platform reset to bootloader mode, if supported.

void
otInstanceFactoryReset(otInstance *aInstance)

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

void
otInstanceResetRadioStack(otInstance *aInstance)

Resets the internal states of the OpenThread radio stack.

otInstanceErasePersistentInfo(otInstance *aInstance)

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

const char *

Gets the OpenThread version string.

const char *
otGetRadioVersionString(otInstance *aInstance)

Gets the OpenThread radio version string.

Macros#

#define

Recommended size for string representation of uptime.

#define

IPv6 address was added.

#define

IPv6 address was removed.

#define

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

#define

The link-local address changed.

#define

The mesh-local address changed.

#define

RLOC was added.

#define

RLOC was removed.

#define

Partition ID changed.

#define

Thread Key Sequence changed.

#define

Thread Network Data changed.

#define

Child was added.

#define

Child was removed.

#define

Subscribed to a IPv6 multicast address.

#define

Unsubscribed from a IPv6 multicast address.

#define

Thread network channel changed.

#define

Thread network PAN Id changed.

#define

Thread network name changed.

#define

Thread network extended PAN ID changed.

#define

Network key changed.

#define
OT_CHANGED_PSKC (1U << 19)

PSKc changed.

#define

Security Policy changed.

#define

Channel Manager new pending Thread channel changed.

#define

Supported channel mask changed.

#define

Commissioner state changed.

#define

Thread network interface state changed.

#define

Backbone Router state changed.

#define

Local Backbone Router configuration changed.

#define

Joiner state changed.

#define

Active Operational Dataset changed.

#define

Pending Operational Dataset changed.

#define

The state of NAT64 translator changed.

#define

Parent link quality changed.

Typedef Documentation#

otInstance#

typedef struct otInstance otInstance

Represents the OpenThread instance structure.


Definition at line 71 of file include/openthread/instance.h

otChangedFlags#

typedef uint32_t otChangedFlags

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

See OT_CHANGED_* definitions.


Definition at line 212 of file include/openthread/instance.h

otStateChangedCallback#

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

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

Parameters
[in]aFlags

A bit-field indicating specific state that has changed. See OT_CHANGED_* definitions.

[in]aContext

A pointer to application-specific context.


Definition at line 221 of file include/openthread/instance.h

Function Documentation#

otInstanceInit#

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

Initializes the OpenThread library.

Parameters
[in]aInstanceBuffer

The buffer for OpenThread to use for allocating the otInstance structure.

[inout]aInstanceBufferSize

On input, the size of aInstanceBuffer. On output, if not enough space for otInstance, the number of bytes required for otInstance.

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.

Returns

  • A pointer to the new OpenThread instance.

See Also


Definition at line 90 of file include/openthread/instance.h

otInstanceInitSingle#

otInstance * otInstanceInitSingle (void )

Initializes the static single instance of the OpenThread library.

Parameters
N/A

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.

Returns

  • A pointer to the single OpenThread instance.


Definition at line 103 of file include/openthread/instance.h

otInstanceGetId#

uint32_t otInstanceGetId (otInstance * aInstance)

Gets the instance identifier.

Parameters
N/AaInstance

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

Returns

  • The instance identifier.


Definition at line 114 of file include/openthread/instance.h

otInstanceIsInitialized#

bool otInstanceIsInitialized (otInstance * aInstance)

Indicates whether or not the instance is valid/initialized.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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.

Returns

  • TRUE if the given instance is valid/initialized, FALSE otherwise.


Definition at line 128 of file include/openthread/instance.h

otInstanceFinalize#

void otInstanceFinalize (otInstance * aInstance)

Disables the OpenThread library.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Call this function when OpenThread is no longer in use.


Definition at line 138 of file include/openthread/instance.h

otInstanceGetUptime#

uint64_t otInstanceGetUptime (otInstance * aInstance)

Returns the current instance uptime (in msec).

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Requires OPENTHREAD_CONFIG_UPTIME_ENABLE to be enabled.

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

Returns

  • The uptime (number of milliseconds).


Definition at line 152 of file include/openthread/instance.h

otInstanceGetUptimeAsString#

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

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

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.

Requires OPENTHREAD_CONFIG_UPTIME_ENABLE to be enabled.

The string follows the format "<hh>:<mm>:<ss>.<mmmm>" for hours, minutes, seconds and millisecond (if uptime is shorter than one day) or "<dd>d.<hh>:<mm>:<ss>.<mmmm>" (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.


Definition at line 172 of file include/openthread/instance.h

otSetStateChangedCallback#

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

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

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.


Definition at line 235 of file include/openthread/instance.h

otRemoveStateChangeCallback#

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

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

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.


Definition at line 245 of file include/openthread/instance.h

otInstanceReset#

void otInstanceReset (otInstance * aInstance)

Triggers a platform reset.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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.


Definition at line 256 of file include/openthread/instance.h

otInstanceResetToBootloader#

otError otInstanceResetToBootloader (otInstance * aInstance)

Triggers a platform reset to bootloader mode, if supported.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Requires OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENABLE.


Definition at line 270 of file include/openthread/instance.h

otInstanceFactoryReset#

void otInstanceFactoryReset (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.


Definition at line 278 of file include/openthread/instance.h

otInstanceResetRadioStack#

void otInstanceResetRadioStack (otInstance * aInstance)

Resets the internal states of the OpenThread radio stack.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Callbacks and configurations are preserved.

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


Definition at line 290 of file include/openthread/instance.h

otInstanceErasePersistentInfo#

otError otInstanceErasePersistentInfo (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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


Definition at line 302 of file include/openthread/instance.h

otGetVersionString#

const char * otGetVersionString (void )

Gets the OpenThread version string.

Parameters
N/A

Returns

  • A pointer to the OpenThread version.


Definition at line 310 of file include/openthread/instance.h

otGetRadioVersionString#

const char * otGetRadioVersionString (otInstance * aInstance)

Gets the OpenThread radio version string.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

Returns

  • A pointer to the OpenThread radio version.


Definition at line 320 of file include/openthread/instance.h

Macro Definition Documentation#

OT_UPTIME_STRING_SIZE#

#define OT_UPTIME_STRING_SIZE
Value:
24

Recommended size for string representation of uptime.


Definition at line 154 of file include/openthread/instance.h

OT_CHANGED_IP6_ADDRESS_ADDED#

#define OT_CHANGED_IP6_ADDRESS_ADDED
Value:
(1U << 0)

IPv6 address was added.


Definition at line 174 of file include/openthread/instance.h

OT_CHANGED_IP6_ADDRESS_REMOVED#

#define OT_CHANGED_IP6_ADDRESS_REMOVED
Value:
(1U << 1)

IPv6 address was removed.


Definition at line 175 of file include/openthread/instance.h

OT_CHANGED_THREAD_ROLE#

#define OT_CHANGED_THREAD_ROLE
Value:
(1U << 2)

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


Definition at line 176 of file include/openthread/instance.h

OT_CHANGED_THREAD_LL_ADDR#

#define OT_CHANGED_THREAD_LL_ADDR
Value:
(1U << 3)

The link-local address changed.


Definition at line 177 of file include/openthread/instance.h

OT_CHANGED_THREAD_ML_ADDR#

#define OT_CHANGED_THREAD_ML_ADDR
Value:
(1U << 4)

The mesh-local address changed.


Definition at line 178 of file include/openthread/instance.h

OT_CHANGED_THREAD_RLOC_ADDED#

#define OT_CHANGED_THREAD_RLOC_ADDED
Value:
(1U << 5)

RLOC was added.


Definition at line 179 of file include/openthread/instance.h

OT_CHANGED_THREAD_RLOC_REMOVED#

#define OT_CHANGED_THREAD_RLOC_REMOVED
Value:
(1U << 6)

RLOC was removed.


Definition at line 180 of file include/openthread/instance.h

OT_CHANGED_THREAD_PARTITION_ID#

#define OT_CHANGED_THREAD_PARTITION_ID
Value:
(1U << 7)

Partition ID changed.


Definition at line 181 of file include/openthread/instance.h

OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER#

#define OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER
Value:
(1U << 8)

Thread Key Sequence changed.


Definition at line 182 of file include/openthread/instance.h

OT_CHANGED_THREAD_NETDATA#

#define OT_CHANGED_THREAD_NETDATA
Value:
(1U << 9)

Thread Network Data changed.


Definition at line 183 of file include/openthread/instance.h

OT_CHANGED_THREAD_CHILD_ADDED#

#define OT_CHANGED_THREAD_CHILD_ADDED
Value:
(1U << 10)

Child was added.


Definition at line 184 of file include/openthread/instance.h

OT_CHANGED_THREAD_CHILD_REMOVED#

#define OT_CHANGED_THREAD_CHILD_REMOVED
Value:
(1U << 11)

Child was removed.


Definition at line 185 of file include/openthread/instance.h

OT_CHANGED_IP6_MULTICAST_SUBSCRIBED#

#define OT_CHANGED_IP6_MULTICAST_SUBSCRIBED
Value:
(1U << 12)

Subscribed to a IPv6 multicast address.


Definition at line 186 of file include/openthread/instance.h

OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED#

#define OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED
Value:
(1U << 13)

Unsubscribed from a IPv6 multicast address.


Definition at line 187 of file include/openthread/instance.h

OT_CHANGED_THREAD_CHANNEL#

#define OT_CHANGED_THREAD_CHANNEL
Value:
(1U << 14)

Thread network channel changed.


Definition at line 188 of file include/openthread/instance.h

OT_CHANGED_THREAD_PANID#

#define OT_CHANGED_THREAD_PANID
Value:
(1U << 15)

Thread network PAN Id changed.


Definition at line 189 of file include/openthread/instance.h

OT_CHANGED_THREAD_NETWORK_NAME#

#define OT_CHANGED_THREAD_NETWORK_NAME
Value:
(1U << 16)

Thread network name changed.


Definition at line 190 of file include/openthread/instance.h

OT_CHANGED_THREAD_EXT_PANID#

#define OT_CHANGED_THREAD_EXT_PANID
Value:
(1U << 17)

Thread network extended PAN ID changed.


Definition at line 191 of file include/openthread/instance.h

OT_CHANGED_NETWORK_KEY#

#define OT_CHANGED_NETWORK_KEY
Value:
(1U << 18)

Network key changed.


Definition at line 192 of file include/openthread/instance.h

OT_CHANGED_PSKC#

#define OT_CHANGED_PSKC
Value:
(1U << 19)

PSKc changed.


Definition at line 193 of file include/openthread/instance.h

OT_CHANGED_SECURITY_POLICY#

#define OT_CHANGED_SECURITY_POLICY
Value:
(1U << 20)

Security Policy changed.


Definition at line 194 of file include/openthread/instance.h

OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL#

#define OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL
Value:
(1U << 21)

Channel Manager new pending Thread channel changed.


Definition at line 195 of file include/openthread/instance.h

OT_CHANGED_SUPPORTED_CHANNEL_MASK#

#define OT_CHANGED_SUPPORTED_CHANNEL_MASK
Value:
(1U << 22)

Supported channel mask changed.


Definition at line 196 of file include/openthread/instance.h

OT_CHANGED_COMMISSIONER_STATE#

#define OT_CHANGED_COMMISSIONER_STATE
Value:
(1U << 23)

Commissioner state changed.


Definition at line 197 of file include/openthread/instance.h

OT_CHANGED_THREAD_NETIF_STATE#

#define OT_CHANGED_THREAD_NETIF_STATE
Value:
(1U << 24)

Thread network interface state changed.


Definition at line 198 of file include/openthread/instance.h

OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE#

#define OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE
Value:
(1U << 25)

Backbone Router state changed.


Definition at line 199 of file include/openthread/instance.h

OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL#

#define OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL
Value:
(1U << 26)

Local Backbone Router configuration changed.


Definition at line 200 of file include/openthread/instance.h

OT_CHANGED_JOINER_STATE#

#define OT_CHANGED_JOINER_STATE
Value:
(1U << 27)

Joiner state changed.


Definition at line 201 of file include/openthread/instance.h

OT_CHANGED_ACTIVE_DATASET#

#define OT_CHANGED_ACTIVE_DATASET
Value:
(1U << 28)

Active Operational Dataset changed.


Definition at line 202 of file include/openthread/instance.h

OT_CHANGED_PENDING_DATASET#

#define OT_CHANGED_PENDING_DATASET
Value:
(1U << 29)

Pending Operational Dataset changed.


Definition at line 203 of file include/openthread/instance.h

OT_CHANGED_NAT64_TRANSLATOR_STATE#

#define OT_CHANGED_NAT64_TRANSLATOR_STATE
Value:
(1U << 30)

The state of NAT64 translator changed.


Definition at line 204 of file include/openthread/instance.h

OT_CHANGED_PARENT_LINK_QUALITY#

#define OT_CHANGED_PARENT_LINK_QUALITY
Value:
(1U << 31)

Parent link quality changed.


Definition at line 205 of file include/openthread/instance.h