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_SUBSRCRIBED = 1 << 12,
  OT_CHANGED_IP6_MULTICAST_UNSUBSRCRIBED = 1 << 13,
  OT_CHANGED_COMMISSIONER_STATE = 1 << 14,
  OT_CHANGED_JOINER_STATE = 1 << 15,
  OT_CHANGED_THREAD_CHANNEL = 1 << 16,
  OT_CHANGED_THREAD_PANID = 1 << 17,
  OT_CHANGED_THREAD_NETWORK_NAME = 1 << 18,
  OT_CHANGED_THREAD_EXT_PANID = 1 << 19,
  OT_CHANGED_MASTER_KEY = 1 << 20,
  OT_CHANGED_PSKC = 1 << 21,
  OT_CHANGED_SECURITY_POLICY = 1 << 22,
  OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL = 1 << 23,
  OT_CHANGED_SUPPORTED_CHANNEL_MASK = 1 << 24,
  OT_CHANGED_BORDER_AGENT_STATE = 1 << 25,
  OT_CHANGED_THREAD_NETIF_STATE = 1 << 26
}
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(OTCALL *
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)
OTAPI const char *OTCALL
This function gets the OpenThread version string.
otInstanceErasePersistentInfo(otInstance *aInstance)
This function erases all the OpenThread persistent info (network settings) stored on non-volatile memory.
otInstanceFactoryReset(otInstance *aInstance)
OTAPI void OTCALL
This method deletes all the settings stored on non-volatile memory, and then triggers platform reset.
otInstanceFinalize(otInstance *aInstance)
void
This function disables the OpenThread library.
otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)
This function initializes the OpenThread library.
otInstanceInitSingle(void)
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)
OTAPI void OTCALL
This method triggers a platform reset.
otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext)
OTAPI void OTCALL
This function removes a callback to indicate when certain configuration or state changes within OpenThread.
otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext)
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_BORDER_AGENT_STATE

Border agent state 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_SUBSRCRIBED

Subscribed to a IPv6 multicast address.

OT_CHANGED_IP6_MULTICAST_UNSUBSRCRIBED

Unsubscribed from a IPv6 multicast address.

OT_CHANGED_JOINER_STATE

Joiner state changed.

OT_CHANGED_MASTER_KEY

Master key 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_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(OTCALL * 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

OTAPI const char *OTCALL 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

OTAPI void OTCALL otInstanceFactoryReset(
  otInstance *aInstance
)

This method deletes all the settings stored on non-volatile memory, and then triggers 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.

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

OTAPI void OTCALL 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.

otRemoveStateChangeCallback

OTAPI void OTCALL 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

OTAPI otError OTCALL 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.