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)`	`otError` 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)`	`otInstance *` Initializes the OpenThread library.
`otInstanceInitMultiple(uint8_t aIdx)`	`otInstance *` Initializes the OpenThread instance.
`otInstanceInitSingle(void)`	`otInstance *` 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)`	`otError` 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)`	`otError` Registers a callback to indicate when certain configuration or state changes within OpenThread.

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

 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.