This module includes functions that control the OpenThread Instance.

Macros
#define	OT_UPTIME_STRING_SIZE 24
	Recommended size for string representation of uptime.

Typedefs
typedef struct otInstance	otInstance
	This structure represents the OpenThread instance structure.

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

typedef void(*	otStateChangedCallback ) ( otChangedFlags aFlags, void *aContext)
	This function pointer is called to notify certain configuration or state changes within OpenThread.

Enumerations
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 }
	This enumeration defines flags that are passed as part of `otStateChangedCallback` .

Functions
otInstance *	otInstanceInit (void aInstanceBuffer, size_t aInstanceBufferSize)
	This function initializes the OpenThread library.

otInstance *	otInstanceInitSingle (void)
	This function initializes the static single instance of the OpenThread library.

bool	otInstanceIsInitialized ( otInstance *aInstance)
	This function indicates whether or not the instance is valid/initialized.

void	otInstanceFinalize ( otInstance *aInstance)
	This function disables the OpenThread library.

uint64_t	otInstanceGetUptime ( otInstance *aInstance)
	This function returns the current instance uptime (in msec).

void	otInstanceGetUptimeAsString ( otInstance aInstance, char aBuffer, uint16_t aSize)
	This function returns the current instance uptime as a human-readable string.

otError	otSetStateChangedCallback ( otInstance aInstance, otStateChangedCallback aCallback, void aContext)
	This function registers a callback to indicate when certain configuration or state changes within OpenThread.

void	otRemoveStateChangeCallback ( otInstance aInstance, otStateChangedCallback aCallback, void aContext)
	This function removes a callback to indicate when certain configuration or state changes within OpenThread.

void	otInstanceReset ( otInstance *aInstance)
	This method triggers a platform reset.

void	otInstanceFactoryReset ( otInstance *aInstance)
	Deletes all the settings stored on non-volatile memory, and then triggers a platform reset.

void	otInstanceResetRadioStack ( otInstance *aInstance)
	This method resets the internal states of the OpenThread radio stack.

otError	otInstanceErasePersistentInfo ( otInstance *aInstance)
	This function erases all the OpenThread persistent info (network settings) stored on non-volatile memory.

const char *	otGetVersionString (void)
	This function gets the OpenThread version string.

const char *	otGetRadioVersionString ( otInstance *aInstance)
	This function gets the OpenThread radio version string.

Detailed Description

This module includes functions that control the OpenThread Instance.

Typedef Documentation

◆ otChangedFlags

typedef uint32_t otChangedFlags

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

See OT_CHANGED_* definitions.

◆ otStateChangedCallback

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

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

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

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

Enumerator
OT_CHANGED_IP6_ADDRESS_ADDED	IPv6 address was added.
OT_CHANGED_IP6_ADDRESS_REMOVED	IPv6 address was removed.
OT_CHANGED_THREAD_ROLE	Role (disabled, detached, child, router, leader) changed.
OT_CHANGED_THREAD_LL_ADDR	The link-local address changed.
OT_CHANGED_THREAD_ML_ADDR	The mesh-local address changed.
OT_CHANGED_THREAD_RLOC_ADDED	RLOC was added.
OT_CHANGED_THREAD_RLOC_REMOVED	RLOC was removed.
OT_CHANGED_THREAD_PARTITION_ID	Partition ID changed.
OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER	Thread Key Sequence changed.
OT_CHANGED_THREAD_NETDATA	Thread Network Data changed.
OT_CHANGED_THREAD_CHILD_ADDED	Child was added.
OT_CHANGED_THREAD_CHILD_REMOVED	Child 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_THREAD_CHANNEL	Thread network channel changed.
OT_CHANGED_THREAD_PANID	Thread network PAN Id changed.
OT_CHANGED_THREAD_NETWORK_NAME	Thread network name changed.
OT_CHANGED_THREAD_EXT_PANID	Thread network extended PAN ID changed.
OT_CHANGED_NETWORK_KEY	Network key changed.
OT_CHANGED_PSKC	PSKc changed.
OT_CHANGED_SECURITY_POLICY	Security Policy changed.
OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL	Channel Manager new pending Thread channel changed.
OT_CHANGED_SUPPORTED_CHANNEL_MASK	Supported channel mask changed.
OT_CHANGED_COMMISSIONER_STATE	Commissioner state changed.
OT_CHANGED_THREAD_NETIF_STATE	Thread network interface state changed.
OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE	Backbone Router state changed.
OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL	Local Backbone Router configuration changed.
OT_CHANGED_JOINER_STATE	Joiner state changed.
OT_CHANGED_ACTIVE_DATASET	Active Operational Dataset changed.
OT_CHANGED_PENDING_DATASET	Pending Operational Dataset changed.

Function Documentation

◆ otGetRadioVersionString()

const char* otGetRadioVersionString ( otInstance * aInstance )

This function gets the OpenThread radio version string.

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.

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.

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.

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.

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.

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 "<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.

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.

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.

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.

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.

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 ).

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.

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.

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.

Instance API > Execution

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ otChangedFlags

◆ otStateChangedCallback

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ otGetRadioVersionString()

◆ otGetVersionString()

◆ otInstanceErasePersistentInfo()

◆ otInstanceFactoryReset()

◆ otInstanceFinalize()

◆ otInstanceGetUptime()

◆ otInstanceGetUptimeAsString()

◆ otInstanceInit()

◆ otInstanceInitSingle()

◆ otInstanceIsInitialized()

◆ otInstanceReset()

◆ otInstanceResetRadioStack()

◆ otRemoveStateChangeCallback()

◆ otSetStateChangedCallback()

Instance
API > Execution