Router/Leader

This module includes functions for Thread Routers and Leaders.

Summary

Enumerations
otCacheEntryState	enum Defines the EID cache entry state.
otNeighborTableEvent{   OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED,   OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED,   OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED,   OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED,   OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED }	enum Defines the constants used in otNeighborTableCallback to indicate changes in neighbor table.
otPowerSupply{   OT_POWER_SUPPLY_BATTERY = 0,   OT_POWER_SUPPLY_EXTERNAL = 1,   OT_POWER_SUPPLY_EXTERNAL_STABLE = 2,   OT_POWER_SUPPLY_EXTERNAL_UNSTABLE = 3 }	enum Represents the power supply property on a device.

Typedefs
otCacheEntryInfo	typedef struct otCacheEntryInfo Represents an EID cache entry.
otCacheEntryIterator	typedef struct otCacheEntryIterator Represents an iterator used for iterating through the EID cache table entries.
otCacheEntryState	typedef enum otCacheEntryState Defines the EID cache entry state.
otChildIp6AddressIterator	typedef uint16_t Used to iterate through IPv6 addresses of a Thread Child entry.
otDeviceProperties	typedef struct otDeviceProperties Represents the device properties which are used for calculating the local leader weight on a device.
otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNeighborTableEntryInfo *aEntryInfo)	typedef void(* Pointer is called to notify that there is a change in the neighbor table.

Functions
otThreadBecomeLeader(otInstance *aInstance)	otError Become a leader and start a new partition.
otThreadBecomeRouter(otInstance *aInstance)	otError Attempt to become a router.
otThreadGetAdvertisementTrickleIntervalMax(otInstance *aInstance)	uint32_t Gets the current Interval Max value used by Advertisement trickle timer.
otThreadGetChildInfoById(otInstance *aInstance, uint16_t aChildId, otChildInfo *aChildInfo)	otError Gets diagnostic information for an attached Child by its Child ID or RLOC16.
otThreadGetChildInfoByIndex(otInstance *aInstance, uint16_t aChildIndex, otChildInfo *aChildInfo)	otError The function retains diagnostic information for an attached Child by the internal table index.
otThreadGetChildNextIp6Address(otInstance *aInstance, uint16_t aChildIndex, otChildIp6AddressIterator *aIterator, otIp6Address *aAddress)	otError Gets the next IPv6 address (using an iterator) for a given child.
otThreadGetChildRouterLinks(otInstance *aInstance)	uint8_t Get the MLE_CHILD_ROUTER_LINKS parameter used in the REED role.
otThreadGetContextIdReuseDelay(otInstance *aInstance)	uint32_t Get the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role.
otThreadGetDeviceProperties(otInstance *aInstance)	const otDeviceProperties * Get the current device properties.
otThreadGetJoinerUdpPort(otInstance *aInstance)	uint16_t Gets the Joiner UDP Port.
otThreadGetLocalLeaderWeight(otInstance *aInstance)	uint8_t Gets the Thread Leader Weight used when operating in the Leader role.
otThreadGetMaxAllowedChildren(otInstance *aInstance)	uint16_t Gets the maximum number of children currently allowed.
otThreadGetMaxChildIpAddresses(otInstance *aInstance)	uint8_t Gets the maximum number of IP addresses that each MTD child may register with this device as parent.
otThreadGetMaxRouterId(otInstance *aInstance)	uint8_t The function returns the maximum allowed router ID.
otThreadGetNetworkIdTimeout(otInstance *aInstance)	uint8_t Get the NETWORK_ID_TIMEOUT parameter.
otThreadGetNextCacheEntry(otInstance *aInstance, otCacheEntryInfo *aEntryInfo, otCacheEntryIterator *aIterator)	otError Gets the next EID cache entry (using an iterator).
otThreadGetNextHopAndPathCost(otInstance *aInstance, uint16_t aDestRloc16, uint16_t *aNextHopRloc16, uint8_t *aPathCost)	void Gets the next hop and path cost towards a given RLOC16 destination.
otThreadGetParentPriority(otInstance *aInstance)	int8_t Get the assigned parent priority.
otThreadGetPreferredLeaderPartitionId(otInstance *aInstance)	uint32_t Get the preferred Thread Leader Partition Id used when operating in the Leader role.
otThreadGetPskc(otInstance *aInstance, otPskc *aPskc)	void Get the Thread PSKc.
otThreadGetPskcRef(otInstance *aInstance)	otPskcRef Get Key Reference to Thread PSKc stored.
otThreadGetRouterDowngradeThreshold(otInstance *aInstance)	uint8_t Get the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Router role.
otThreadGetRouterIdRange(otInstance *aInstance, uint8_t *aMinRouterId, uint8_t *aMaxRouterId)	void Gets the range of router IDs that are allowed to assign to nodes within the thread network.
otThreadGetRouterIdSequence(otInstance *aInstance)	uint8_t Get the current Router ID Sequence.
otThreadGetRouterInfo(otInstance *aInstance, uint16_t aRouterId, otRouterInfo *aRouterInfo)	otError The function retains diagnostic information for a given Thread Router.
otThreadGetRouterSelectionJitter(otInstance *aInstance)	uint8_t Get the ROUTER_SELECTION_JITTER parameter used in the REED/Router role.
otThreadGetRouterUpgradeThreshold(otInstance *aInstance)	uint8_t Get the ROUTER_UPGRADE_THRESHOLD parameter used in the REED role.
otThreadIsRouterEligible(otInstance *aInstance)	bool Indicates whether or not the device is router-eligible.
otThreadIsRouterIdAllocated(otInstance *aInstance, uint8_t aRouterId)	bool Indicates whether or not a Router ID is currently allocated.
otThreadIsTmfOriginFilterEnabled(otInstance *aInstance)	bool Indicates whether the filter that drops TMF UDP messages from untrusted origin is enabled or not.
otThreadRegisterNeighborTableCallback(otInstance *aInstance, otNeighborTableCallback aCallback)	void Registers a neighbor table callback function.
otThreadReleaseRouterId(otInstance *aInstance, uint8_t aRouterId)	otError Release a Router ID that has been allocated by the device in the Leader role.
otThreadSetCcmEnabled(otInstance *aInstance, bool aEnabled)	void Sets whether the device was commissioned using CCM.
otThreadSetChildRouterLinks(otInstance *aInstance, uint8_t aChildRouterLinks)	otError Set the MLE_CHILD_ROUTER_LINKS parameter used in the REED role.
otThreadSetContextIdReuseDelay(otInstance *aInstance, uint32_t aDelay)	void Set the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role.
otThreadSetDeviceProperties(otInstance *aInstance, const otDeviceProperties *aDeviceProperties)	void Set the device properties which are then used to determine and set the Leader Weight.
otThreadSetJoinerUdpPort(otInstance *aInstance, uint16_t aJoinerUdpPort)	otError Sets the Joiner UDP Port.
otThreadSetLocalLeaderWeight(otInstance *aInstance, uint8_t aWeight)	void Sets the Thread Leader Weight used when operating in the Leader role.
otThreadSetMaxAllowedChildren(otInstance *aInstance, uint16_t aMaxChildren)	otError Sets the maximum number of children currently allowed.
otThreadSetMaxChildIpAddresses(otInstance *aInstance, uint8_t aMaxIpAddresses)	otError Sets or restores the maximum number of IP addresses that each MTD child may register with this device as parent.
otThreadSetNetworkIdTimeout(otInstance *aInstance, uint8_t aTimeout)	void Set the NETWORK_ID_TIMEOUT parameter.
otThreadSetParentPriority(otInstance *aInstance, int8_t aParentPriority)	otError Set the parent priority.
otThreadSetPreferredLeaderPartitionId(otInstance *aInstance, uint32_t aPartitionId)	void Set the preferred Thread Leader Partition Id used when operating in the Leader role.
otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId)	otError Set the preferred Router Id.
otThreadSetPskc(otInstance *aInstance, const otPskc *aPskc)	otError Set the Thread PSKc.
otThreadSetPskcRef(otInstance *aInstance, otPskcRef aKeyRef)	otError Set the Key Reference to the Thread PSKc.
otThreadSetRouterDowngradeThreshold(otInstance *aInstance, uint8_t aThreshold)	void Set the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Leader role.
otThreadSetRouterEligible(otInstance *aInstance, bool aEligible)	otError Sets whether or not the device is router-eligible.
otThreadSetRouterIdRange(otInstance *aInstance, uint8_t aMinRouterId, uint8_t aMaxRouterId)	otError Sets the range of router IDs that are allowed to assign to nodes within the thread network.
otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter)	void Set the ROUTER_SELECTION_JITTER parameter used in the REED/Router role.
otThreadSetRouterUpgradeThreshold(otInstance *aInstance, uint8_t aThreshold)	void Set the ROUTER_UPGRADE_THRESHOLD parameter used in the Leader role.
otThreadSetSteeringData(otInstance *aInstance, const otExtAddress *aExtAddress)	void Set Steering data out of band.
otThreadSetThreadVersionCheckEnabled(otInstance *aInstance, bool aEnabled)	void Sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled.
otThreadSetTmfOriginFilterEnabled(otInstance *aInstance, bool aEnabled)	void Enables or disables the filter to drop TMF UDP messages from untrusted origin.

Macros
OT_CHILD_IP6_ADDRESS_ITERATOR_INIT 0	Initializer for otChildIP6AddressIterator.

Structs
otCacheEntryInfo	Represents an EID cache entry.
otCacheEntryIterator	Represents an iterator used for iterating through the EID cache table entries.
otChildInfo	Holds diagnostic information for a Thread Child.
otDeviceProperties	Represents the device properties which are used for calculating the local leader weight on a device.
otNeighborTableEntryInfo	Represent a neighbor table entry info (child or router) and is used as a parameter in the neighbor table callback otNeighborTableCallback.

Enumerations

otCacheEntryState

 otCacheEntryState

Defines the EID cache entry state.

otNeighborTableEvent

 otNeighborTableEvent

Defines the constants used in otNeighborTableCallback to indicate changes in neighbor table.

Properties
OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED	A child is being added.
OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED	An existing child's mode is changed.
OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED	A child is being removed.
OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED	A router is being added.
OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED	A router is being removed.

otPowerSupply

 otPowerSupply

Represents the power supply property on a device.

This is used as a property in otDeviceProperties to calculate the leader weight.

Properties
OT_POWER_SUPPLY_BATTERY	Battery powered.
OT_POWER_SUPPLY_EXTERNAL	Externally powered (mains-powered).
OT_POWER_SUPPLY_EXTERNAL_STABLE	Stable external power with a battery backup or UPS.
OT_POWER_SUPPLY_EXTERNAL_UNSTABLE	Potentially unstable ext power (e.g. light bulb powered via a switch).

Typedefs

otCacheEntryInfo

struct otCacheEntryInfo otCacheEntryInfo

Represents an EID cache entry.

otCacheEntryIterator

struct otCacheEntryIterator otCacheEntryIterator

Represents an iterator used for iterating through the EID cache table entries.

To initialize the iterator and start from the first entry in the cache table, set all its fields in the structure to zero (e.g., memset the iterator to zero).

otCacheEntryState

enum otCacheEntryState otCacheEntryState

Defines the EID cache entry state.

otChildIp6AddressIterator

uint16_t otChildIp6AddressIterator

Used to iterate through IPv6 addresses of a Thread Child entry.

otDeviceProperties

struct otDeviceProperties otDeviceProperties

Represents the device properties which are used for calculating the local leader weight on a device.

The parameters are set based on device's capability, whether acting as border router, its power supply config, etc.

mIsUnstable indicates operational stability of device and is determined via a vendor specific mechanism. It can include the following cases:

• Device internally detects that it loses external power supply more often than usual. What is usual is determined by the vendor.
• Device internally detects that it reboots more often than usual. What is usual is determined by the vendor.

otNeighborTableCallback

void(* otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNeighborTableEntryInfo *aEntryInfo)

Pointer is called to notify that there is a change in the neighbor table.

Details
Parameters	[in] aEvent A event flag. [in] aEntryInfo A pointer to table entry info.

Functions

otThreadBecomeLeader

otError otThreadBecomeLeader(
  otInstance *aInstance
)

Become a leader and start a new partition.

If the device is not attached, this API will force the device to start as the leader of the network. This use case is only intended for testing and demo purposes, and using the API while the device is detached can make a production application non-compliant with the Thread Specification.

If the device is already attached, this API can be used to try to take over as the leader, creating a new partition. For this to work, the local leader weight (otThreadGetLocalLeaderWeight()) must be larger than the weight of the current leader (otThreadGetLeaderWeight()). If it is not, OT_ERROR_NOT_CAPABLE is returned to indicate to the caller that they need to adjust the weight.

Taking over the leader role in this way is only allowed when triggered by an explicit user action. Using this API without such user action can make a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Return Values	OT_ERROR_NONE Successfully became a leader and started a new partition, or was leader already. OT_ERROR_INVALID_STATE Thread is disabled. OT_ERROR_NOT_CAPABLE Device cannot override the current leader due to its local leader weight being same or smaller than current leader's weight, or device is not router eligible.

otThreadBecomeRouter

otError otThreadBecomeRouter(
  otInstance *aInstance
)

Attempt to become a router.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Return Values	OT_ERROR_NONE Successfully begin attempt to become a router. OT_ERROR_INVALID_STATE Thread is disabled.

otThreadGetAdvertisementTrickleIntervalMax

uint32_t otThreadGetAdvertisementTrickleIntervalMax(
  otInstance *aInstance
)

Gets the current Interval Max value used by Advertisement trickle timer.

This API requires OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE, and is intended for testing only.

Details
Returns	The Interval Max of Advertisement trickle timer in milliseconds.

otThreadGetChildInfoById

otError otThreadGetChildInfoById(
  otInstance *aInstance,
  uint16_t aChildId,
  otChildInfo *aChildInfo
)

Gets diagnostic information for an attached Child by its Child ID or RLOC16.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aChildId The Child ID or RLOC16 for the attached child. [out] aChildInfo A pointer to where the child information is placed.
Return Values	OT_ERROR_NONE aChildInfo was successfully updated with the info for the given ID. OT_ERROR_NOT_FOUND No valid child with this Child ID. OT_ERROR_INVALID_ARGS If aChildInfo is NULL.

otThreadGetChildInfoByIndex

otError otThreadGetChildInfoByIndex(
  otInstance *aInstance,
  uint16_t aChildIndex,
  otChildInfo *aChildInfo
)

The function retains diagnostic information for an attached Child by the internal table index.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aChildIndex The table index. [out] aChildInfo A pointer to where the child information is placed.
Return Values	OT_ERROR_NONE aChildInfo was successfully updated with the info for the given index. OT_ERROR_NOT_FOUND No valid child at this index. OT_ERROR_INVALID_ARGS Either aChildInfo is NULL, or aChildIndex is out of range (higher than max table index).

See also:
otGetMaxAllowedChildren

otThreadGetChildNextIp6Address

otError otThreadGetChildNextIp6Address(
  otInstance *aInstance,
  uint16_t aChildIndex,
  otChildIp6AddressIterator *aIterator,
  otIp6Address *aAddress
)

Gets the next IPv6 address (using an iterator) for a given child.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aChildIndex The child index. [in,out] aIterator A pointer to the iterator. On success the iterator will be updated to point to next entry in the list. To get the first IPv6 address the iterator should be set to OT_CHILD_IP6_ADDRESS_ITERATOR_INIT. [out] aAddress A pointer to an IPv6 address where the child's next address is placed (on success).
Return Values	OT_ERROR_NONE Successfully found the next IPv6 address (aAddress was successfully updated). OT_ERROR_NOT_FOUND The child has no subsequent IPv6 address entry. OT_ERROR_INVALID_ARGS aIterator or aAddress are NULL, or child at aChildIndex is not valid.

See also:
otThreadGetChildInfoByIndex

otThreadGetChildRouterLinks

uint8_t otThreadGetChildRouterLinks(
  otInstance *aInstance
)

Get the MLE_CHILD_ROUTER_LINKS parameter used in the REED role.

This parameter specifies the max number of neighboring routers with which the device (as an FED) will try to establish link.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The MLE_CHILD_ROUTER_LINKS value.

See also:
otThreadSetChildRouterLinks

otThreadGetContextIdReuseDelay

uint32_t otThreadGetContextIdReuseDelay(
  otInstance *aInstance
)

Get the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The CONTEXT_ID_REUSE_DELAY value.

See also:
otThreadSetContextIdReuseDelay

otThreadGetDeviceProperties

const otDeviceProperties * otThreadGetDeviceProperties(
  otInstance *aInstance
)

Get the current device properties.

Requires OPENTHREAD_CONFIG_MLE_DEVICE_PROPERTY_LEADER_WEIGHT_ENABLE.

Details
Returns	The device properties otDeviceProperties.

otThreadGetJoinerUdpPort

uint16_t otThreadGetJoinerUdpPort(
  otInstance *aInstance
)

Gets the Joiner UDP Port.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The Joiner UDP Port number.

See also:
otThreadSetJoinerUdpPort

otThreadGetLocalLeaderWeight

uint8_t otThreadGetLocalLeaderWeight(
  otInstance *aInstance
)

Gets the Thread Leader Weight used when operating in the Leader role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The Thread Leader Weight value.

See also:
otThreadSetLeaderWeight
otThreadSetDeviceProperties

otThreadGetMaxAllowedChildren

uint16_t otThreadGetMaxAllowedChildren(
  otInstance *aInstance
)

Gets the maximum number of children currently allowed.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The maximum number of children currently allowed.

See also:
otThreadSetMaxAllowedChildren

otThreadGetMaxChildIpAddresses

uint8_t otThreadGetMaxChildIpAddresses(
  otInstance *aInstance
)

Gets the maximum number of IP addresses that each MTD child may register with this device as parent.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The maximum number of IP addresses that each MTD child may register with this device as parent.

See also:
otThreadSetMaxChildIpAddresses

otThreadGetMaxRouterId

uint8_t otThreadGetMaxRouterId(
  otInstance *aInstance
)

The function returns the maximum allowed router ID.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The maximum allowed router ID.

otThreadGetNetworkIdTimeout

uint8_t otThreadGetNetworkIdTimeout(
  otInstance *aInstance
)

Get the NETWORK_ID_TIMEOUT parameter.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The NETWORK_ID_TIMEOUT value.

See also:
otThreadSetNetworkIdTimeout

otThreadGetNextCacheEntry

otError otThreadGetNextCacheEntry(
  otInstance *aInstance,
  otCacheEntryInfo *aEntryInfo,
  otCacheEntryIterator *aIterator
)

Gets the next EID cache entry (using an iterator).

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aEntryInfo A pointer to where the EID cache entry information is placed. [in,out] aIterator A pointer to an iterator. It will be updated to point to next entry on success. To get the first entry, initialize the iterator by setting all its fields to zero (e.g., memset the iterator structure to zero).
Return Values	OT_ERROR_NONE Successfully populated aEntryInfo for next EID cache entry. OT_ERROR_NOT_FOUND No more entries in the address cache table.

otThreadGetNextHopAndPathCost

void otThreadGetNextHopAndPathCost(
  otInstance *aInstance,
  uint16_t aDestRloc16,
  uint16_t *aNextHopRloc16,
  uint8_t *aPathCost
)

Gets the next hop and path cost towards a given RLOC16 destination.

Can be used with either aNextHopRloc16 or aPathCost being NULL indicating caller does not want to get the value.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDestRloc16 The RLOC16 of destination. [out] aNextHopRloc16 A pointer to return RLOC16 of next hop, 0xfffe if no next hop. [out] aPathCost A pointer to return path cost towards destination.

otThreadGetParentPriority

int8_t otThreadGetParentPriority(
  otInstance *aInstance
)

Get the assigned parent priority.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The assigned parent priority value, -2 means not assigned.

See also:
otThreadSetParentPriority

otThreadGetPreferredLeaderPartitionId

uint32_t otThreadGetPreferredLeaderPartitionId(
  otInstance *aInstance
)

Get the preferred Thread Leader Partition Id used when operating in the Leader role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The Thread Leader Partition Id value.

otThreadGetPskc

void otThreadGetPskc(
  otInstance *aInstance,
  otPskc *aPskc
)

Get the Thread PSKc.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aPskc A pointer to an otPskc to return the retrieved Thread PSKc.

See also:
otThreadSetPskc

otThreadGetPskcRef

otPskcRef otThreadGetPskcRef(
  otInstance *aInstance
)

Get Key Reference to Thread PSKc stored.

Requires the build-time feature OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE to be enabled.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	Key Reference to PSKc

See also:
otThreadSetPskcRef

otThreadGetRouterDowngradeThreshold

uint8_t otThreadGetRouterDowngradeThreshold(
  otInstance *aInstance
)

Get the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Router role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The ROUTER_DOWNGRADE_THRESHOLD value.

See also:
otThreadSetRouterDowngradeThreshold

otThreadGetRouterIdRange

void otThreadGetRouterIdRange(
  otInstance *aInstance,
  uint8_t *aMinRouterId,
  uint8_t *aMaxRouterId
)

Gets the range of router IDs that are allowed to assign to nodes within the thread network.

Note: This API requires OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE, and is only used for test purpose. All the router IDs in the range [aMinRouterId, aMaxRouterId] are allowed.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aMinRouterId The minimum router ID. [out] aMaxRouterId The maximum router ID.

See also:
otThreadSetRouterIdRange

otThreadGetRouterIdSequence

uint8_t otThreadGetRouterIdSequence(
  otInstance *aInstance
)

Get the current Router ID Sequence.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The Router ID Sequence.

otThreadGetRouterInfo

otError otThreadGetRouterInfo(
  otInstance *aInstance,
  uint16_t aRouterId,
  otRouterInfo *aRouterInfo
)

The function retains diagnostic information for a given Thread Router.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aRouterId The router ID or RLOC16 for a given router. [out] aRouterInfo A pointer to where the router information is placed.
Return Values	OT_ERROR_NONE Successfully retrieved the router info for given id. OT_ERROR_NOT_FOUND No router entry with the given id. OT_ERROR_INVALID_ARGS aRouterInfo is NULL.

otThreadGetRouterSelectionJitter

uint8_t otThreadGetRouterSelectionJitter(
  otInstance *aInstance
)

Get the ROUTER_SELECTION_JITTER parameter used in the REED/Router role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The ROUTER_SELECTION_JITTER value.

See also:
otThreadSetRouterSelectionJitter

otThreadGetRouterUpgradeThreshold

uint8_t otThreadGetRouterUpgradeThreshold(
  otInstance *aInstance
)

Get the ROUTER_UPGRADE_THRESHOLD parameter used in the REED role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	The ROUTER_UPGRADE_THRESHOLD value.

See also:
otThreadSetRouterUpgradeThreshold

otThreadIsRouterEligible

bool otThreadIsRouterEligible(
  otInstance *aInstance
)

Indicates whether or not the device is router-eligible.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Return Values	TRUE If device is router-eligible. FALSE If device is not router-eligible.

otThreadIsRouterIdAllocated

bool otThreadIsRouterIdAllocated(
  otInstance *aInstance,
  uint8_t aRouterId
)

Indicates whether or not a Router ID is currently allocated.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aRouterId The router ID to check.
Return Values	TRUE The aRouterId is allocated. FALSE The aRouterId is not allocated.

otThreadIsTmfOriginFilterEnabled

bool otThreadIsTmfOriginFilterEnabled(
  otInstance *aInstance
)

Indicates whether the filter that drops TMF UDP messages from untrusted origin is enabled or not.

This is intended for testing only and available when OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE config is enabled.

Details
Return Values	TRUE The filter is enabled. FALSE The filter is not enabled.

otThreadRegisterNeighborTableCallback

void otThreadRegisterNeighborTableCallback(
  otInstance *aInstance,
  otNeighborTableCallback aCallback
)

Registers a neighbor table callback function.

The provided callback (if non-NULL) will be invoked when there is a change in the neighbor table (e.g., a child or a router neighbor entry is being added/removed or an existing child's mode is changed).

Subsequent calls to this method will overwrite the previous callback. Note that this callback in invoked while the neighbor/child table is being updated and always before the otStateChangedCallback.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aCallback A pointer to callback handler function.

otThreadReleaseRouterId

otError otThreadReleaseRouterId(
  otInstance *aInstance,
  uint8_t aRouterId
)

Release a Router ID that has been allocated by the device in the Leader role.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aRouterId The Router ID to release. Valid range is [0, 62].
Return Values	OT_ERROR_NONE Successfully released the router id. OT_ERROR_INVALID_ARGS aRouterId is not in the range [0, 62]. OT_ERROR_INVALID_STATE The device is not currently operating as a leader. OT_ERROR_NOT_FOUND The router id is not currently allocated.

otThreadSetCcmEnabled

void otThreadSetCcmEnabled(
  otInstance *aInstance,
  bool aEnabled
)

Sets whether the device was commissioned using CCM.

Note: This API requires OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE, and is only used by Thread Test Harness to indicate whether this device was commissioned using CCM.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aEnabled TRUE if the device was commissioned using CCM, FALSE otherwise.

otThreadSetChildRouterLinks

otError otThreadSetChildRouterLinks(
  otInstance *aInstance,
  uint8_t aChildRouterLinks
)

Set the MLE_CHILD_ROUTER_LINKS parameter used in the REED role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aChildRouterLinks The MLE_CHILD_ROUTER_LINKS value.
Return Values	OT_ERROR_NONE Successfully set the value. OT_ERROR_INVALID_STATE Thread protocols are enabled.

See also:
otThreadGetChildRouterLinks

otThreadSetContextIdReuseDelay

void otThreadSetContextIdReuseDelay(
  otInstance *aInstance,
  uint32_t aDelay
)

Set the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDelay The CONTEXT_ID_REUSE_DELAY value.

See also:
otThreadGetContextIdReuseDelay

otThreadSetDeviceProperties

void otThreadSetDeviceProperties(
  otInstance *aInstance,
  const otDeviceProperties *aDeviceProperties
)

Set the device properties which are then used to determine and set the Leader Weight.

Requires OPENTHREAD_CONFIG_MLE_DEVICE_PROPERTY_LEADER_WEIGHT_ENABLE.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDeviceProperties The device properties.

otThreadSetJoinerUdpPort

otError otThreadSetJoinerUdpPort(
  otInstance *aInstance,
  uint16_t aJoinerUdpPort
)

Sets the Joiner UDP Port.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aJoinerUdpPort The Joiner UDP Port number.
Return Values	OT_ERROR_NONE Successfully set the Joiner UDP Port.

See also:
otThreadGetJoinerUdpPort

otThreadSetLocalLeaderWeight

void otThreadSetLocalLeaderWeight(
  otInstance *aInstance,
  uint8_t aWeight
)

Sets the Thread Leader Weight used when operating in the Leader role.

Directly sets the Leader Weight to the new value, replacing its previous value (which may have been determined from the current otDeviceProperties).

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aWeight The Thread Leader Weight value.

See also:
otThreadGetLeaderWeight

otThreadSetMaxAllowedChildren

otError otThreadSetMaxAllowedChildren(
  otInstance *aInstance,
  uint16_t aMaxChildren
)

Sets the maximum number of children currently allowed.

This parameter can only be set when Thread protocol operation has been stopped.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aMaxChildren The maximum allowed children.
Return Values	OT_ERROR_NONE Successfully set the max. OT_ERROR_INVALID_ARGS If aMaxChildren is not in the range [1, OPENTHREAD_CONFIG_MLE_MAX_CHILDREN]. OT_ERROR_INVALID_STATE If Thread isn't stopped.

See also:
otThreadGetMaxAllowedChildren

otThreadSetMaxChildIpAddresses

otError otThreadSetMaxChildIpAddresses(
  otInstance *aInstance,
  uint8_t aMaxIpAddresses
)

Sets or restores the maximum number of IP addresses that each MTD child may register with this device as parent.

Pass 0 to clear the setting and restore the default.

Available when OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE is enabled.

Note: Only used by Thread Test Harness to limit the address registrations of the reference parent in order to test the MTD DUT reaction.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aMaxIpAddresses The maximum number of IP addresses that each MTD child may register with this device as parent. 0 to clear the setting and restore the default.
Return Values	OT_ERROR_NONE Successfully set/cleared the number. OT_ERROR_INVALID_ARGS If exceeds the allowed maximum number.

See also:
otThreadGetMaxChildIpAddresses

otThreadSetNetworkIdTimeout

void otThreadSetNetworkIdTimeout(
  otInstance *aInstance,
  uint8_t aTimeout
)

Set the NETWORK_ID_TIMEOUT parameter.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aTimeout The NETWORK_ID_TIMEOUT value.

See also:
otThreadGetNetworkIdTimeout

otThreadSetParentPriority

otError otThreadSetParentPriority(
  otInstance *aInstance,
  int8_t aParentPriority
)

Set the parent priority.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aParentPriority The parent priority value.
Return Values	OT_ERROR_NONE Successfully set the parent priority. OT_ERROR_INVALID_ARGS If the parent priority value is not among 1, 0, -1 and -2.

See also:
otThreadGetParentPriority

otThreadSetPreferredLeaderPartitionId

void otThreadSetPreferredLeaderPartitionId(
  otInstance *aInstance,
  uint32_t aPartitionId
)

Set the preferred Thread Leader Partition Id used when operating in the Leader role.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aPartitionId The Thread Leader Partition Id value.

otThreadSetPreferredRouterId

otError otThreadSetPreferredRouterId(
  otInstance *aInstance,
  uint8_t aRouterId
)

Set the preferred Router Id.

Upon becoming a router/leader the node attempts to use this Router Id. If the preferred Router Id is not set or if it can not be used, a randomly generated router id is picked. This property can be set only when the device role is either detached or disabled.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aRouterId The preferred Router Id.
Return Values	OT_ERROR_NONE Successfully set the preferred Router Id. OT_ERROR_INVALID_STATE Could not set (role is not detached or disabled)

otThreadSetPskc

otError otThreadSetPskc(
  otInstance *aInstance,
  const otPskc *aPskc
)

Set the Thread PSKc.

Will only succeed when Thread protocols are disabled. A successful call to this function will also invalidate the Active and Pending Operational Datasets in non-volatile memory.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aPskc A pointer to the new Thread PSKc.
Return Values	OT_ERROR_NONE Successfully set the Thread PSKc. OT_ERROR_INVALID_STATE Thread protocols are enabled.

See also:
otThreadGetPskc

otThreadSetPskcRef

otError otThreadSetPskcRef(
  otInstance *aInstance,
  otPskcRef aKeyRef
)

Set the Key Reference to the Thread PSKc.

Requires the build-time feature OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE to be enabled.

Will only succeed when Thread protocols are disabled. Upon success, this will also invalidate the Active and Pending Operational Datasets in non-volatile memory.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aKeyRef Key Reference to the new Thread PSKc.
Return Values	OT_ERROR_NONE Successfully set the Thread PSKc. OT_ERROR_INVALID_STATE Thread protocols are enabled.

See also:
otThreadGetPskcRef

otThreadSetRouterDowngradeThreshold

void otThreadSetRouterDowngradeThreshold(
  otInstance *aInstance,
  uint8_t aThreshold
)

Set the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Leader role.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aThreshold The ROUTER_DOWNGRADE_THRESHOLD value.

See also:
otThreadGetRouterDowngradeThreshold

otThreadSetRouterEligible

otError otThreadSetRouterEligible(
  otInstance *aInstance,
  bool aEligible
)

Sets whether or not the device is router-eligible.

If aEligible is false and the device is currently operating as a router, this call will cause the device to detach and attempt to reattach as a child.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aEligible TRUE to configure the device as router-eligible, FALSE otherwise.
Return Values	OT_ERROR_NONE Successfully set the router-eligible configuration. OT_ERROR_NOT_CAPABLE The device is not capable of becoming a router.

otThreadSetRouterIdRange

otError otThreadSetRouterIdRange(
  otInstance *aInstance,
  uint8_t aMinRouterId,
  uint8_t aMaxRouterId
)

Sets the range of router IDs that are allowed to assign to nodes within the thread network.

Note: This API requires OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE, and is only used for test purpose. All the router IDs in the range [aMinRouterId, aMaxRouterId] are allowed.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aMinRouterId The minimum router ID. [in] aMaxRouterId The maximum router ID.
Return Values	OT_ERROR_NONE Successfully set the range. OT_ERROR_INVALID_ARGS aMinRouterId > aMaxRouterId, or the range is not covered by [0, 62].

See also:
otThreadGetRouterIdRange

otThreadSetRouterSelectionJitter

void otThreadSetRouterSelectionJitter(
  otInstance *aInstance,
  uint8_t aRouterJitter
)

Set the ROUTER_SELECTION_JITTER parameter used in the REED/Router role.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aRouterJitter The ROUTER_SELECTION_JITTER value.

See also:
otThreadGetRouterSelectionJitter

otThreadSetRouterUpgradeThreshold

void otThreadSetRouterUpgradeThreshold(
  otInstance *aInstance,
  uint8_t aThreshold
)

Set the ROUTER_UPGRADE_THRESHOLD parameter used in the Leader role.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aThreshold The ROUTER_UPGRADE_THRESHOLD value.

See also:
otThreadGetRouterUpgradeThreshold

otThreadSetSteeringData

void otThreadSetSteeringData(
  otInstance *aInstance,
  const otExtAddress *aExtAddress
)

Set Steering data out of band.

Configuration option OPENTHREAD_CONFIG_MLE_STEERING_DATA_SET_OOB_ENABLE should be set to enable setting of steering data out of band.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aExtAddress Address used to update the steering data. All zeros to clear the steering data (no steering data). All 0xFFs to set steering data/bloom filter to accept/allow all. A specific EUI64 which is then added to current steering data/bloom filter.

otThreadSetThreadVersionCheckEnabled

void otThreadSetThreadVersionCheckEnabled(
  otInstance *aInstance,
  bool aEnabled
)

Sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled.

Note: This API requires OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE, and is only used by Thread Test Harness to indicate that thread protocol version check VR should be skipped.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aEnabled TRUE to enable Security Policy TLV version-threshold for routing, FALSE otherwise.

otThreadSetTmfOriginFilterEnabled

void otThreadSetTmfOriginFilterEnabled(
  otInstance *aInstance,
  bool aEnabled
)

Enables or disables the filter to drop TMF UDP messages from untrusted origin.

TMF messages are only trusted when they originate from a trusted source, such as the Thread interface. In special cases, such as when a device uses platform UDP socket to send TMF messages, they will be dropped due to untrusted origin. This filter is enabled by default.

When this filter is disabled, UDP messages sent to the TMF port that originate from untrusted origin (such as host, CLI or an external IPv6 node) will be allowed.

Note: This API requires OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE and is only used by Thread Test Harness to test network behavior by sending special TMF messages from the CLI on a POSIX host.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aEnabled TRUE to enable filter, FALSE otherwise.

Macros

OT_CHILD_IP6_ADDRESS_ITERATOR_INIT

 OT_CHILD_IP6_ADDRESS_ITERATOR_INIT 0

Initializer for otChildIP6AddressIterator.

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.