Instance#
This module includes functions that control the OpenThread Instance.
Typedefs#
Represents the OpenThread instance structure.
Represents a bit-field indicating specific state/configuration that has changed.
Pointer is called to notify certain configuration or state changes within OpenThread.
Functions#
Initializes the OpenThread library.
Initializes the static single instance of the OpenThread library.
Initializes the OpenThread instance.
Gets the instance identifier.
Indicates whether or not the instance is valid/initialized.
Disables the OpenThread library.
Returns the current instance uptime (in msec).
Returns the current instance uptime as a human-readable string.
Registers a callback to indicate when certain configuration or state changes within OpenThread.
Removes a callback to indicate when certain configuration or state changes within OpenThread.
Triggers a platform reset.
Triggers a platform reset to bootloader mode, if supported.
Deletes all the settings stored on non-volatile memory, and then triggers a platform reset.
Resets the internal states of the OpenThread radio stack.
Erases all the OpenThread persistent info (network settings) stored on non-volatile memory.
Gets the OpenThread version string.
Gets the OpenThread radio version string.
Macros#
Recommended size for string representation of uptime.
IPv6 address was added.
IPv6 address was removed.
Role (disabled, detached, child, router, leader) changed.
The link-local address changed.
The mesh-local address changed.
RLOC was added.
RLOC was removed.
Partition ID changed.
Thread Key Sequence changed.
Thread Network Data changed.
Child was added.
Child was removed.
Subscribed to a IPv6 multicast address.
Unsubscribed from a IPv6 multicast address.
Thread network channel changed.
Thread network PAN Id changed.
Thread network name changed.
Thread network extended PAN ID changed.
Network key changed.
PSKc changed.
Security Policy changed.
Channel Manager new pending Thread channel changed.
Supported channel mask changed.
Commissioner state changed.
Thread network interface state changed.
Backbone Router state changed.
Local Backbone Router configuration changed.
Joiner state changed.
Active Operational Dataset changed.
Pending Operational Dataset changed.
The state of NAT64 translator changed.
Parent link quality changed.
Typedef Documentation#
otInstance#
typedef struct otInstance otInstance
Represents the OpenThread instance structure.
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.
229
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.
[in] | aFlags | A bit-field indicating specific state that has changed. See |
[in] | aContext | A pointer to application-specific context. |
238
of file include/openthread/instance.h
Function Documentation#
otInstanceInit#
otInstance * otInstanceInit (void * aInstanceBuffer, size_t * aInstanceBufferSize)
Initializes the OpenThread library.
[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
90
of file include/openthread/instance.h
otInstanceInitSingle#
otInstance * otInstanceInitSingle (void )
Initializes the static single instance of the OpenThread library.
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.
103
of file include/openthread/instance.h
otInstanceInitMultiple#
otInstance * otInstanceInitMultiple (uint8_t aIdx)
Initializes the OpenThread instance.
[in] | aIdx | The index of the OpenThread instance to initialize. |
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
)
Returns
A pointer to the new OpenThread instance.
120
of file include/openthread/instance.h
otInstanceGetId#
uint32_t otInstanceGetId (otInstance * aInstance)
Gets the instance identifier.
N/A | aInstance |
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.
131
of file include/openthread/instance.h
otInstanceIsInitialized#
bool otInstanceIsInitialized (otInstance * aInstance)
Indicates whether or not the instance is valid/initialized.
[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.
145
of file include/openthread/instance.h
otInstanceFinalize#
void otInstanceFinalize (otInstance * aInstance)
Disables the OpenThread library.
[in] | aInstance | A pointer to an OpenThread instance. |
Call this function when OpenThread is no longer in use.
155
of file include/openthread/instance.h
otInstanceGetUptime#
uint64_t otInstanceGetUptime (otInstance * aInstance)
Returns the current instance uptime (in msec).
[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).
169
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.
[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 |
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.
189
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.
[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. |
252
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.
[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. |
262
of file include/openthread/instance.h
otInstanceReset#
void otInstanceReset (otInstance * aInstance)
Triggers a platform reset.
[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.
273
of file include/openthread/instance.h
otInstanceResetToBootloader#
otError otInstanceResetToBootloader (otInstance * aInstance)
Triggers a platform reset to bootloader mode, if supported.
[in] | aInstance | A pointer to an OpenThread instance. |
Requires OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENABLE
.
287
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.
[in] | aInstance | A pointer to an OpenThread instance. |
295
of file include/openthread/instance.h
otInstanceResetRadioStack#
void otInstanceResetRadioStack (otInstance * aInstance)
Resets the internal states of the OpenThread radio stack.
[in] | aInstance | A pointer to an OpenThread instance. |
Callbacks and configurations are preserved.
This API is only available under radio builds (OPENTHREAD_RADIO = 1
).
307
of file include/openthread/instance.h
otInstanceErasePersistentInfo#
otError otInstanceErasePersistentInfo (otInstance * aInstance)
Erases all the OpenThread persistent info (network settings) stored on non-volatile memory.
[in] | aInstance | A pointer to an OpenThread instance. |
Erase is successful only if the device is in disabled
state/role.
319
of file include/openthread/instance.h
otGetVersionString#
const char * otGetVersionString (void )
Gets the OpenThread version string.
N/A |
Returns
A pointer to the OpenThread version.
327
of file include/openthread/instance.h
otGetRadioVersionString#
const char * otGetRadioVersionString (otInstance * aInstance)
Gets the OpenThread radio version string.
[in] | aInstance | A pointer to an OpenThread instance. |
Returns
A pointer to the OpenThread radio version.
337
of file include/openthread/instance.h
Macro Definition Documentation#
OT_UPTIME_STRING_SIZE#
#define OT_UPTIME_STRING_SIZEValue:
24
Recommended size for string representation of uptime.
171
of file include/openthread/instance.h
OT_CHANGED_IP6_ADDRESS_ADDED#
#define OT_CHANGED_IP6_ADDRESS_ADDEDValue:
(1U << 0)
IPv6 address was added.
191
of file include/openthread/instance.h
OT_CHANGED_IP6_ADDRESS_REMOVED#
#define OT_CHANGED_IP6_ADDRESS_REMOVEDValue:
(1U << 1)
IPv6 address was removed.
192
of file include/openthread/instance.h
OT_CHANGED_THREAD_ROLE#
#define OT_CHANGED_THREAD_ROLEValue:
(1U << 2)
Role (disabled, detached, child, router, leader) changed.
193
of file include/openthread/instance.h
OT_CHANGED_THREAD_LL_ADDR#
#define OT_CHANGED_THREAD_LL_ADDRValue:
(1U << 3)
The link-local address changed.
194
of file include/openthread/instance.h
OT_CHANGED_THREAD_ML_ADDR#
#define OT_CHANGED_THREAD_ML_ADDRValue:
(1U << 4)
The mesh-local address changed.
195
of file include/openthread/instance.h
OT_CHANGED_THREAD_RLOC_ADDED#
#define OT_CHANGED_THREAD_RLOC_ADDEDValue:
(1U << 5)
RLOC was added.
196
of file include/openthread/instance.h
OT_CHANGED_THREAD_RLOC_REMOVED#
#define OT_CHANGED_THREAD_RLOC_REMOVEDValue:
(1U << 6)
RLOC was removed.
197
of file include/openthread/instance.h
OT_CHANGED_THREAD_PARTITION_ID#
#define OT_CHANGED_THREAD_PARTITION_IDValue:
(1U << 7)
Partition ID changed.
198
of file include/openthread/instance.h
OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER#
#define OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTERValue:
(1U << 8)
Thread Key Sequence changed.
199
of file include/openthread/instance.h
OT_CHANGED_THREAD_NETDATA#
#define OT_CHANGED_THREAD_NETDATAValue:
(1U << 9)
Thread Network Data changed.
200
of file include/openthread/instance.h
OT_CHANGED_THREAD_CHILD_ADDED#
#define OT_CHANGED_THREAD_CHILD_ADDEDValue:
(1U << 10)
Child was added.
201
of file include/openthread/instance.h
OT_CHANGED_THREAD_CHILD_REMOVED#
#define OT_CHANGED_THREAD_CHILD_REMOVEDValue:
(1U << 11)
Child was removed.
202
of file include/openthread/instance.h
OT_CHANGED_IP6_MULTICAST_SUBSCRIBED#
#define OT_CHANGED_IP6_MULTICAST_SUBSCRIBEDValue:
(1U << 12)
Subscribed to a IPv6 multicast address.
203
of file include/openthread/instance.h
OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED#
#define OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBEDValue:
(1U << 13)
Unsubscribed from a IPv6 multicast address.
204
of file include/openthread/instance.h
OT_CHANGED_THREAD_CHANNEL#
#define OT_CHANGED_THREAD_CHANNELValue:
(1U << 14)
Thread network channel changed.
205
of file include/openthread/instance.h
OT_CHANGED_THREAD_PANID#
#define OT_CHANGED_THREAD_PANIDValue:
(1U << 15)
Thread network PAN Id changed.
206
of file include/openthread/instance.h
OT_CHANGED_THREAD_NETWORK_NAME#
#define OT_CHANGED_THREAD_NETWORK_NAMEValue:
(1U << 16)
Thread network name changed.
207
of file include/openthread/instance.h
OT_CHANGED_THREAD_EXT_PANID#
#define OT_CHANGED_THREAD_EXT_PANIDValue:
(1U << 17)
Thread network extended PAN ID changed.
208
of file include/openthread/instance.h
OT_CHANGED_NETWORK_KEY#
#define OT_CHANGED_NETWORK_KEYValue:
(1U << 18)
Network key changed.
209
of file include/openthread/instance.h
OT_CHANGED_PSKC#
#define OT_CHANGED_PSKCValue:
(1U << 19)
PSKc changed.
210
of file include/openthread/instance.h
OT_CHANGED_SECURITY_POLICY#
#define OT_CHANGED_SECURITY_POLICYValue:
(1U << 20)
Security Policy changed.
211
of file include/openthread/instance.h
OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL#
#define OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNELValue:
(1U << 21)
Channel Manager new pending Thread channel changed.
212
of file include/openthread/instance.h
OT_CHANGED_SUPPORTED_CHANNEL_MASK#
#define OT_CHANGED_SUPPORTED_CHANNEL_MASKValue:
(1U << 22)
Supported channel mask changed.
213
of file include/openthread/instance.h
OT_CHANGED_COMMISSIONER_STATE#
#define OT_CHANGED_COMMISSIONER_STATEValue:
(1U << 23)
Commissioner state changed.
214
of file include/openthread/instance.h
OT_CHANGED_THREAD_NETIF_STATE#
#define OT_CHANGED_THREAD_NETIF_STATEValue:
(1U << 24)
Thread network interface state changed.
215
of file include/openthread/instance.h
OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE#
#define OT_CHANGED_THREAD_BACKBONE_ROUTER_STATEValue:
(1U << 25)
Backbone Router state changed.
216
of file include/openthread/instance.h
OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL#
#define OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCALValue:
(1U << 26)
Local Backbone Router configuration changed.
217
of file include/openthread/instance.h
OT_CHANGED_JOINER_STATE#
#define OT_CHANGED_JOINER_STATEValue:
(1U << 27)
Joiner state changed.
218
of file include/openthread/instance.h
OT_CHANGED_ACTIVE_DATASET#
#define OT_CHANGED_ACTIVE_DATASETValue:
(1U << 28)
Active Operational Dataset changed.
219
of file include/openthread/instance.h
OT_CHANGED_PENDING_DATASET#
#define OT_CHANGED_PENDING_DATASETValue:
(1U << 29)
Pending Operational Dataset changed.
220
of file include/openthread/instance.h
OT_CHANGED_NAT64_TRANSLATOR_STATE#
#define OT_CHANGED_NAT64_TRANSLATOR_STATEValue:
(1U << 30)
The state of NAT64 translator changed.
221
of file include/openthread/instance.h
OT_CHANGED_PARENT_LINK_QUALITY#
#define OT_CHANGED_PARENT_LINK_QUALITYValue:
(1U << 31)
Parent link quality changed.
222
of file include/openthread/instance.h