Instance

This module includes functions that control the OpenThread Instance.

Summary

Enumerations
anonymous enum{ OT_CHANGED_IP6_ADDRESS_ADDED = 1 << 0, OT_CHANGED_IP6_ADDRESS_REMOVED = 1 << 1, OT_CHANGED_THREAD_ROLE = 1 << 2, OT_CHANGED_THREAD_LL_ADDR = 1 << 3, OT_CHANGED_THREAD_ML_ADDR = 1 << 4, OT_CHANGED_THREAD_RLOC_ADDED = 1 << 5, OT_CHANGED_THREAD_RLOC_REMOVED = 1 << 6, OT_CHANGED_THREAD_PARTITION_ID = 1 << 7, OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER = 1 << 8, OT_CHANGED_THREAD_NETDATA = 1 << 9, OT_CHANGED_THREAD_CHILD_ADDED = 1 << 10, OT_CHANGED_THREAD_CHILD_REMOVED = 1 << 11, OT_CHANGED_IP6_MULTICAST_SUBSCRIBED = 1 << 12, OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED = 1 << 13, OT_CHANGED_THREAD_CHANNEL = 1 << 14, OT_CHANGED_THREAD_PANID = 1 << 15, OT_CHANGED_THREAD_NETWORK_NAME = 1 << 16, OT_CHANGED_THREAD_EXT_PANID = 1 << 17, OT_CHANGED_NETWORK_KEY = 1 << 18, OT_CHANGED_PSKC = 1 << 19, OT_CHANGED_SECURITY_POLICY = 1 << 20, OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL = 1 << 21, OT_CHANGED_SUPPORTED_CHANNEL_MASK = 1 << 22, OT_CHANGED_COMMISSIONER_STATE = 1 << 23, OT_CHANGED_THREAD_NETIF_STATE = 1 << 24, OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE = 1 << 25, OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL = 1 << 26, OT_CHANGED_JOINER_STATE = 1 << 27, OT_CHANGED_ACTIVE_DATASET = 1 << 28, OT_CHANGED_PENDING_DATASET = 1 << 29, OT_CHANGED_NAT64_TRANSLATOR_STATE = 1 << 30 }	enum This enumeration defines flags that are passed as part of `otStateChangedCallback`.

Enumerations

anonymous enum{
  OT_CHANGED_IP6_ADDRESS_ADDED = 1 << 0,
  OT_CHANGED_IP6_ADDRESS_REMOVED = 1 << 1,
  OT_CHANGED_THREAD_ROLE = 1 << 2,
  OT_CHANGED_THREAD_LL_ADDR = 1 << 3,
  OT_CHANGED_THREAD_ML_ADDR = 1 << 4,
  OT_CHANGED_THREAD_RLOC_ADDED = 1 << 5,
  OT_CHANGED_THREAD_RLOC_REMOVED = 1 << 6,
  OT_CHANGED_THREAD_PARTITION_ID = 1 << 7,
  OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER = 1 << 8,
  OT_CHANGED_THREAD_NETDATA = 1 << 9,
  OT_CHANGED_THREAD_CHILD_ADDED = 1 << 10,
  OT_CHANGED_THREAD_CHILD_REMOVED = 1 << 11,
  OT_CHANGED_IP6_MULTICAST_SUBSCRIBED = 1 << 12,
  OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED = 1 << 13,
  OT_CHANGED_THREAD_CHANNEL = 1 << 14,
  OT_CHANGED_THREAD_PANID = 1 << 15,
  OT_CHANGED_THREAD_NETWORK_NAME = 1 << 16,
  OT_CHANGED_THREAD_EXT_PANID = 1 << 17,
  OT_CHANGED_NETWORK_KEY = 1 << 18,
  OT_CHANGED_PSKC = 1 << 19,
  OT_CHANGED_SECURITY_POLICY = 1 << 20,
  OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL = 1 << 21,
  OT_CHANGED_SUPPORTED_CHANNEL_MASK = 1 << 22,
  OT_CHANGED_COMMISSIONER_STATE = 1 << 23,
  OT_CHANGED_THREAD_NETIF_STATE = 1 << 24,
  OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE = 1 << 25,
  OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL = 1 << 26,
  OT_CHANGED_JOINER_STATE = 1 << 27,
  OT_CHANGED_ACTIVE_DATASET = 1 << 28,
  OT_CHANGED_PENDING_DATASET = 1 << 29,
  OT_CHANGED_NAT64_TRANSLATOR_STATE = 1 << 30
}

enum

This enumeration defines flags that are passed as part of otStateChangedCallback.

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

Functions
`otGetRadioVersionString(otInstance *aInstance)`	`const char *` This function gets the OpenThread radio version string.
`otGetVersionString(void)`	`const char *` This function gets the OpenThread version string.
`otInstanceErasePersistentInfo(otInstance *aInstance)`	`otError` This function 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` This function disables the OpenThread library.
`otInstanceGetUptime(otInstance *aInstance)`	`uint64_t` This function returns the current instance uptime (in msec).
`otInstanceGetUptimeAsString(otInstance aInstance, char aBuffer, uint16_t aSize)`	`void` This function returns the current instance uptime as a human-readable string.
`otInstanceInit(void aInstanceBuffer, size_t aInstanceBufferSize)`	`otInstance *` This function initializes the OpenThread library.
`otInstanceInitSingle(void)`	`otInstance *` This function initializes the static single instance of the OpenThread library.
`otInstanceIsInitialized(otInstance *aInstance)`	`bool` This function indicates whether or not the instance is valid/initialized.
`otInstanceReset(otInstance *aInstance)`	`void` This method triggers a platform reset.
`otInstanceResetRadioStack(otInstance *aInstance)`	`void` This method resets the internal states of the OpenThread radio stack.
`otRemoveStateChangeCallback(otInstance aInstance, otStateChangedCallback aCallback, void aContext)`	`void` This function removes a callback to indicate when certain configuration or state changes within OpenThread.
`otSetStateChangedCallback(otInstance aInstance, otStateChangedCallback aCallback, void aContext)`	`otError` This function registers a callback to indicate when certain configuration or state changes within OpenThread.

Enumerations

anonymous enum

 anonymous enum

This enumeration defines flags that are passed as part of otStateChangedCallback.

Properties
`OT_CHANGED_ACTIVE_DATASET`	Active Operational Dataset changed.
`OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL`	Channel Manager new pending Thread channel changed.
`OT_CHANGED_COMMISSIONER_STATE`	Commissioner state changed.
`OT_CHANGED_IP6_ADDRESS_ADDED`	IPv6 address was added.
`OT_CHANGED_IP6_ADDRESS_REMOVED`	IPv6 address was removed.
`OT_CHANGED_IP6_MULTICAST_SUBSCRIBED`	Subscribed to a IPv6 multicast address.
`OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED`	Unsubscribed from a IPv6 multicast address.
`OT_CHANGED_JOINER_STATE`	Joiner state changed.
`OT_CHANGED_NAT64_TRANSLATOR_STATE`	The state of NAT64 translator changed.
`OT_CHANGED_NETWORK_KEY`	Network key changed.
`OT_CHANGED_PENDING_DATASET`	Pending Operational Dataset changed.
`OT_CHANGED_PSKC`	PSKc changed.
`OT_CHANGED_SECURITY_POLICY`	Security Policy changed.
`OT_CHANGED_SUPPORTED_CHANNEL_MASK`	Supported channel mask changed.
`OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL`	Local Backbone Router configuration changed.
`OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE`	Backbone Router state changed.
`OT_CHANGED_THREAD_CHANNEL`	Thread network channel changed.
`OT_CHANGED_THREAD_CHILD_ADDED`	Child was added.
`OT_CHANGED_THREAD_CHILD_REMOVED`	Child was removed.
`OT_CHANGED_THREAD_EXT_PANID`	Thread network extended PAN ID changed.
`OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER`	Thread Key Sequence changed.
`OT_CHANGED_THREAD_LL_ADDR`	The link-local address changed.
`OT_CHANGED_THREAD_ML_ADDR`	The mesh-local address changed.
`OT_CHANGED_THREAD_NETDATA`	Thread Network Data changed.
`OT_CHANGED_THREAD_NETIF_STATE`	Thread network interface state changed.
`OT_CHANGED_THREAD_NETWORK_NAME`	Thread network name changed.
`OT_CHANGED_THREAD_PANID`	Thread network PAN Id changed.
`OT_CHANGED_THREAD_PARTITION_ID`	Partition ID changed.
`OT_CHANGED_THREAD_RLOC_ADDED`	RLOC was added.
`OT_CHANGED_THREAD_RLOC_REMOVED`	RLOC was removed.
`OT_CHANGED_THREAD_ROLE`	Role (disabled, detached, child, router, leader) changed.

Typedefs

otChangedFlags

uint32_t otChangedFlags

This type represents a bit-field indicating specific state/configuration that has changed.

See OT_CHANGED_* definitions.

otInstance

struct otInstance otInstance

This structure represents the OpenThread instance structure.

otStateChangedCallback

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

This function 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
)

This function 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
)

This function gets the OpenThread version string.

Details
Returns	A pointer to the OpenThread version.

otInstanceErasePersistentInfo

otError otInstanceErasePersistentInfo(
  otInstance *aInstance
)

This function 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
)

This function disables the OpenThread library.

Call this function when OpenThread is no longer in use.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

otInstanceGetUptime

uint64_t otInstanceGetUptime(
  otInstance *aInstance
)

This function returns the current instance uptime (in msec).

This function 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
)

This function returns the current instance uptime as a human-readable string.

This function 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
)

This function initializes the OpenThread library.

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

This function 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

otInstanceInitSingle

otInstance * otInstanceInitSingle(
  void
)

This function initializes the static single instance of the OpenThread library.

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

This function 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
)

This function 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
)

This method 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
)

This method 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.

otRemoveStateChangeCallback

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

This function 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
)

This function 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_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.