Is there an API to monitor changes in all Router and Child nodes in a Thread network?

[lancersky2017]

Hi Experts,
We are doing some work on Thread network diagnostics. Is there an API to monitor changes in all Router and Child nodes in a Thread network? How do I know if the children of other router nodes have changed, such as leaving the network or reattaching to the network?
Thanks.

[jwhui]

Thread provides a way to query topology state from other devices. You can use this to periodically query state over time and track changes.

You may find the meshdiag CLI command useful.

[lancersky2017]

Thanks @jwhui . I'm concerned that frequent calls to meshdiag might affect network performance. So I think that if TBR can know that there are node change events in the network, such as the addition and removal of Routers, it will actively call meshdiag once.

[abtink]

Some info which may help you:

• Check the existing Notifier events: OT_CHANGED_THREAD_CHILD_ADDED and OT_CHANGED_THREAD_CHILD_REMOVED
• There is also otThreadRegisterNeighborTableCallback()
  

  openthread/include/openthread/thread_ftd.h

  Lines 789 to 839 in 19dadd9

  	/**
  	* Defines the constants used in `otNeighborTableCallback` to indicate changes in neighbor table.
  	*
  	*/
  	typedef enum
  	{
  	OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED, ///< A child is being added.
  	OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED, ///< A child is being removed.
  	OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED, ///< An existing child's mode is changed.
  	OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED, ///< A router is being added.
  	OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, ///< A router is being removed.
  	} otNeighborTableEvent;
  	/**
  	* Represent a neighbor table entry info (child or router) and is used as a parameter in the neighbor table
  	* callback `otNeighborTableCallback`.
  	*
  	*/
  	typedef struct
  	{
  	otInstance *mInstance; ///< The OpenThread instance.
  	union
  	{
  	otChildInfo mChild; ///< The child neighbor info.
  	otNeighborInfo mRouter; ///< The router neighbor info.
  	} mInfo;
  	} otNeighborTableEntryInfo;
  	/**
  	* Pointer is called to notify that there is a change in the neighbor table.
  	*
  	* @param[in] aEvent A event flag.
  	* @param[in] aEntryInfo A pointer to table entry info.
  	*
  	*/
  	typedef void (*otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNeighborTableEntryInfo *aEntryInfo);
  	/**
  	* 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`.
  	*
  	* @param[in] aInstance A pointer to an OpenThread instance.
  	* @param[in] aCallback A pointer to callback handler function.
  	*
  	*/
  	void otThreadRegisterNeighborTableCallback(otInstance *aInstance, otNeighborTableCallback aCallback);

• Note that the above mechanisms apply only to the device's immediate neighbors (those with a direct link).
• There's currently no mechanism/API to be notified of changes to remote devices, i.e., children of other routers, or routers that are multiple hops away and not direct neighbors. "MeshDiag" provides mechanism to query and learn.

---

OpenThread also provides "HistoryTracker" feature (can be enabled on more capable devices with more resources):

openthread/include/openthread/history_tracker.h

Lines 39 to 44 in 19dadd9

	/**
	* @addtogroup api-history-tracker
	*
	* @brief
	* Records the history of different events, for example RX and TX messages or network info changes. All tracked
	* entries are timestamped.

It can track changes to "route table" which tells us when/if any router (neighbor or remote) is added/removed:

openthread/include/openthread/history_tracker.h

Lines 195 to 222 in 19dadd9

	/**
	* Defines the events in a router info (i.e. whether router is added, removed, or changed).
	*
	*/
	typedef enum
	{
	OT_HISTORY_TRACKER_ROUTER_EVENT_ADDED = 0, ///< Router is added (router ID allocated).
	OT_HISTORY_TRACKER_ROUTER_EVENT_REMOVED = 1, ///< Router entry is removed (router ID released).
	OT_HISTORY_TRACKER_ROUTER_EVENT_NEXT_HOP_CHANGED = 2, ///< Router entry next hop and cost changed.
	OT_HISTORY_TRACKER_ROUTER_EVENT_COST_CHANGED = 3, ///< Router entry path cost changed (next hop as before).
	} otHistoryTrackerRouterEvent;
	#define OT_HISTORY_TRACKER_NO_NEXT_HOP 63 ///< No next hop - For `mNextHop` in `otHistoryTrackerRouterInfo`.
	#define OT_HISTORY_TRACKER_INFINITE_PATH_COST 0 ///< Infinite path cost - used in `otHistoryTrackerRouterInfo`.
	/**
	* Represents a router table entry event.
	*
	*/
	typedef struct otHistoryTrackerRouterInfo
	{
	uint8_t mEvent : 2; ///< Router entry event (`OT_HISTORY_TRACKER_ROUTER_EVENT_*` enumeration).
	uint8_t mRouterId : 6; ///< Router ID.
	uint8_t mNextHop; ///< Next Hop Router ID - `OT_HISTORY_TRACKER_NO_NEXT_HOP` if no next hop.
	uint8_t mOldPathCost : 4; ///< Old path cost - `OT_HISTORY_TRACKER_INFINITE_PATH_COST` if infinite or unknown.
	uint8_t mPathCost : 4; ///< New path cost - `OT_HISTORY_TRACKER_INFINITE_PATH_COST` if infinite or unknown.
	} otHistoryTrackerRouterInfo;

openthread/include/openthread/history_tracker.h

Lines 373 to 390 in 19dadd9

	/**
	* Iterates over the entries in the router history list.
	*
	* @param[in] aInstance A pointer to the OpenThread instance.
	* @param[in,out] aIterator A pointer to an iterator. MUST be initialized or the behavior is undefined.
	* @param[out] aEntryAge A pointer to a variable to output the entry's age. MUST NOT be NULL.
	* Age is provided as the duration (in milliseconds) from when entry was recorded to
	* @p aIterator initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries
	* older than max age.
	*
	* @returns The `otHistoryTrackerRouterInfo` entry or `NULL` if no more entries in the list.
	*
	*/
	const otHistoryTrackerRouterInfo *otHistoryTrackerIterateRouterHistory(otInstance *aInstance,
	otHistoryTrackerIterator *aIterator,
	uint32_t *aEntryAge);

It also tracks history of changed to neighbors (child/router):

openthread/include/openthread/history_tracker.h

Lines 163 to 194 in 19dadd9

	/**
	* Defines the events in a neighbor info (i.e. whether neighbor is added, removed, or changed).
	*
	* Event `OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING` is applicable to child neighbors only. It is triggered after
	* the device (re)starts and when the previous children list is retrieved from non-volatile settings and the device
	* tries to restore connection to them.
	*
	*/
	typedef enum
	{
	OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED = 0, ///< Neighbor is added.
	OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED = 1, ///< Neighbor is removed.
	OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED = 2, ///< Neighbor changed (e.g., device mode flags changed).
	OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING = 3, ///< Neighbor is being restored (applicable to child only).
	} otHistoryTrackerNeighborEvent;
	/**
	* Represents a neighbor info.
	*
	*/
	typedef struct otHistoryTrackerNeighborInfo
	{
	otExtAddress mExtAddress; ///< Neighbor's Extended Address.
	uint16_t mRloc16; ///< Neighbor's RLOC16.
	int8_t mAverageRssi; ///< Average RSSI of rx frames from neighbor at the time of recording entry.
	uint8_t mEvent : 2; ///< Indicates the event (`OT_HISTORY_TRACKER_NEIGHBOR_EVENT_*` enumeration).
	bool mRxOnWhenIdle : 1; ///< Rx-on-when-idle.
	bool mFullThreadDevice : 1; ///< Full Thread Device.
	bool mFullNetworkData : 1; ///< Full Network Data.
	bool mIsChild : 1; ///< Indicates whether or not the neighbor is a child.
	} otHistoryTrackerNeighborInfo;

[lancersky2017]

Cool, that's what I wanted. Thanks.

[jwhui]

Note that Thread intentionally does not require any device to maintain full topology information for the entire Thread network, for scalability reasons. So obtaining any state from another node in the network will always incur additional Thread traffic.