Instance#

This module includes functions that control the OpenThread Instance.

Enumerations#

enum
@2 {
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
}

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

Typedefs#

typedef struct otInstance

This structure represents the OpenThread instance structure.

typedef uint32_t

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.

Functions#

otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)

This function initializes the OpenThread library.

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.

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.

otInstanceErasePersistentInfo(otInstance *aInstance)

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

const char *

This function gets the OpenThread version string.

const char *
otGetRadioVersionString(otInstance *aInstance)

This function gets the OpenThread radio version string.

Macros#

#define

Recommended size for string representation of uptime.

Enumeration Documentation#

@2#

@2

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.

OT_CHANGED_NAT64_TRANSLATOR_STATE

The state of NAT64 translator changed.


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

Typedef Documentation#

otInstance#

typedef struct otInstance otInstance

This structure represents the OpenThread instance structure.


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

otChangedFlags#

typedef uint32_t otChangedFlags

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

See OT_CHANGED_* definitions.


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

otStateChangedCallback#

typedef void(* otStateChangedCallback) (otChangedFlags aFlags, void *aContext) )(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.


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

Function Documentation#

otInstanceInit#

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

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

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.

Returns

  • A pointer to the new OpenThread instance.

See Also


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

otInstanceInitSingle#

otInstance * otInstanceInitSingle (void )

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

Parameters
N/A

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.


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

otInstanceIsInitialized#

bool otInstanceIsInitialized (otInstance * aInstance)

This function 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 117 of file include/openthread/instance.h

otInstanceFinalize#

void otInstanceFinalize (otInstance * aInstance)

This function 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 127 of file include/openthread/instance.h

otInstanceGetUptime#

uint64_t otInstanceGetUptime (otInstance * aInstance)

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

Parameters
[in]aInstance

A pointer to an OpenThread instance.

This function 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 141 of file include/openthread/instance.h

otInstanceGetUptimeAsString#

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

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

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.


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

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.


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

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.


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

otInstanceReset#

void otInstanceReset (otInstance * aInstance)

This method 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 251 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 259 of file include/openthread/instance.h

otInstanceResetRadioStack#

void otInstanceResetRadioStack (otInstance * aInstance)

This method 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 271 of file include/openthread/instance.h

otInstanceErasePersistentInfo#

otError otInstanceErasePersistentInfo (otInstance * aInstance)

This function 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 283 of file include/openthread/instance.h

otGetVersionString#

const char * otGetVersionString (void )

This function gets the OpenThread version string.

Parameters
N/A

Returns

  • A pointer to the OpenThread version.


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

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.


Definition at line 301 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 143 of file include/openthread/instance.h