Records the history of different events, for example RX and TX messages or network info changes.

Classes
struct	otHistoryTrackerIterator
	This type represents an iterator to iterate through a history list.

struct	otHistoryTrackerNetworkInfo
	This structure represents Thread network info.

struct	otHistoryTrackerUnicastAddressInfo
	This structure represent a unicast IPv6 address info.

struct	otHistoryTrackerMulticastAddressInfo
	This structure represent an IPv6 multicast address info.

struct	otHistoryTrackerMessageInfo
	This structure represents a RX/TX IPv6 message info.

struct	otHistoryTrackerNeighborInfo
	This structure represents a neighbor info.

struct	otHistoryTrackerOnMeshPrefixInfo
	This structure represent a Network Data on mesh prefix info.

struct	otHistoryTrackerExternalRouteInfo
	This structure represent a Network Data extern route info.

Macros
#define	OT_HISTORY_TRACKER_MAX_AGE (49 * 24 * 60 * 60 * 1000u)
	This constant specifies the maximum age of entries which is 49 days (in msec).

#define	OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE 21
	Recommended size for string representation of an entry age.

Typedefs
typedef struct otHistoryTrackerIterator	otHistoryTrackerIterator
	This type represents an iterator to iterate through a history list.

typedef struct otHistoryTrackerNetworkInfo	otHistoryTrackerNetworkInfo
	This structure represents Thread network info.

typedef struct otHistoryTrackerUnicastAddressInfo	otHistoryTrackerUnicastAddressInfo
	This structure represent a unicast IPv6 address info.

typedef struct otHistoryTrackerMulticastAddressInfo	otHistoryTrackerMulticastAddressInfo
	This structure represent an IPv6 multicast address info.

typedef struct otHistoryTrackerMessageInfo	otHistoryTrackerMessageInfo
	This structure represents a RX/TX IPv6 message info.

typedef struct otHistoryTrackerNeighborInfo	otHistoryTrackerNeighborInfo
	This structure represents a neighbor info.

typedef struct otHistoryTrackerOnMeshPrefixInfo	otHistoryTrackerOnMeshPrefixInfo
	This structure represent a Network Data on mesh prefix info.

typedef struct otHistoryTrackerExternalRouteInfo	otHistoryTrackerExternalRouteInfo
	This structure represent a Network Data extern route info.

Enumerations
enum	otHistoryTrackerAddressEvent { OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED = 0, OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED = 1 }
	This enumeration defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added or removed).

enum	{ OT_HISTORY_TRACKER_MSG_PRIORITY_LOW = OT_MESSAGE_PRIORITY_LOW, OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL = OT_MESSAGE_PRIORITY_NORMAL, OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH = OT_MESSAGE_PRIORITY_HIGH, OT_HISTORY_TRACKER_MSG_PRIORITY_NET = OT_MESSAGE_PRIORITY_HIGH + 1 }
	Constants representing message priority used in `otHistoryTrackerMessageInfo` struct.

enum	otHistoryTrackerNeighborEvent { OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED = 0, OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED = 1, OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED = 2, OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING = 3 }
	This enumeration defines the events in a neighbor info (i.e.

enum	otHistoryTrackerNetDataEvent { OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED = 0, OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED = 1 }
	This enumeration defines the events for a Network Data entry (i.e., whether an entry is added or removed).

Functions
void	otHistoryTrackerInitIterator (otHistoryTrackerIterator *aIterator)
	This function initializes an `otHistoryTrackerIterator`.

const otHistoryTrackerNetworkInfo *	otHistoryTrackerIterateNetInfoHistory (otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)
	This function iterates over the entries in the network info history list.

const otHistoryTrackerUnicastAddressInfo *	otHistoryTrackerIterateUnicastAddressHistory (otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)
	This function iterates over the entries in the unicast address history list.

const otHistoryTrackerMulticastAddressInfo *	otHistoryTrackerIterateMulticastAddressHistory (otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)
	This function iterates over the entries in the multicast address history list.

const otHistoryTrackerMessageInfo *	otHistoryTrackerIterateRxHistory (otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)
	This function iterates over the entries in the RX message history list.

const otHistoryTrackerMessageInfo *	otHistoryTrackerIterateTxHistory (otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)
	This function iterates over the entries in the TX message history list.

const otHistoryTrackerNeighborInfo *	otHistoryTrackerIterateNeighborHistory (otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)
	This function iterates over the entries in the neighbor history list.

const otHistoryTrackerOnMeshPrefixInfo *	otHistoryTrackerIterateOnMeshPrefixHistory (otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)
	This function iterates over the entries in the Network Data on mesh prefix entry history list.

const otHistoryTrackerExternalRouteInfo *	otHistoryTrackerIterateExternalRouteHistory (otInstance aInstance, otHistoryTrackerIterator aIterator, uint32_t *aEntryAge)
	This function iterates over the entries in the Network Data external route entry history list.

void	otHistoryTrackerEntryAgeToString (uint32_t aEntryAge, char *aBuffer, uint16_t aSize)
	This function converts a given entry age to a human-readable string.

Detailed Description

Records the history of different events, for example RX and TX messages or network info changes.

All tracked entries are timestamped.

The functions in this module are available when OPENTHREAD_CONFIG_HISTOR_TRACKER_ENABLE is enabled.

Macro Definition Documentation

◆ OT_HISTORY_TRACKER_MAX_AGE

#define OT_HISTORY_TRACKER_MAX_AGE (49 * 24 * 60 * 60 * 1000u)

This constant specifies the maximum age of entries which is 49 days (in msec).

Entries older than the max age will give this value as their age.

Typedef Documentation

◆ otHistoryTrackerIterator

typedef struct otHistoryTrackerIterator otHistoryTrackerIterator

This type represents an iterator to iterate through a history list.

The fields in this type are opaque (intended for use by OpenThread core) and therefore should not be accessed/used by caller.

Before using an iterator, it MUST be initialized using otHistoryTrackerInitIterator(),

◆ otHistoryTrackerMessageInfo

typedef struct otHistoryTrackerMessageInfo otHistoryTrackerMessageInfo

This structure represents a RX/TX IPv6 message info.

Some of the fields in this struct are applicable to a RX message or a TX message only, e.g., mAveRxRss is the average RSS of all fragment frames that form a received message and is only applicable for a RX message.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Constants representing message priority used in otHistoryTrackerMessageInfo struct.

Enumerator
OT_HISTORY_TRACKER_MSG_PRIORITY_LOW	Low priority level.
OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL	Normal priority level.
OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH	High priority level.
OT_HISTORY_TRACKER_MSG_PRIORITY_NET	Network Control priority level.

◆ otHistoryTrackerAddressEvent

enum otHistoryTrackerAddressEvent

This enumeration defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added or removed).

Enumerator
OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED	Address is added.
OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED	Address is removed.

◆ otHistoryTrackerNeighborEvent

enum otHistoryTrackerNeighborEvent

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

Enumerator
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED	Neighbor is added.
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED	Neighbor is removed.
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED	Neighbor changed (e.g., device mode flags changed).
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING	Neighbor is being restored (applicable to child only).

◆ otHistoryTrackerNetDataEvent

enum otHistoryTrackerNetDataEvent

This enumeration defines the events for a Network Data entry (i.e., whether an entry is added or removed).

Enumerator
OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED	Network data entry is added.
OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED	Network data entry is removed.

Function Documentation

◆ otHistoryTrackerEntryAgeToString()

void otHistoryTrackerEntryAgeToString	(	uint32_t	`aEntryAge,`
		char *	`aBuffer,`
		uint16_t	`aSize`
	)

This function converts a given entry age to a human-readable string.

The entry age string follows the format "<hh>:<mm>:<ss>.<mmmm>" for hours, minutes, seconds and millisecond (if shorter than one day) or "<dd> days <hh>:<mm>:<ss>.<mmmm>" (if longer than one 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.

Parameters

[in]	`aEntryAge`	The entry age (duration in msec).
[out]	`aBuffer`	A pointer to a char array to output the string (MUST NOT be NULL).
[in]	`aSize`	The size of `aBuffer`. Recommended to use `OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE`.

◆ otHistoryTrackerInitIterator()

void otHistoryTrackerInitIterator ( otHistoryTrackerIterator * aIterator )

This function initializes an otHistoryTrackerIterator.

An iterator MUST be initialized before it is used.

An iterator can be initialized again to start from the beginning of the list.

When iterating over entries in a list, to ensure the entry ages are consistent, the age is given relative to the time the iterator was initialized, i.e., the entry age is provided as the duration (in milliseconds) from the event (when entry was recorded) to the iterator initialization time.

Parameters

[in] aIterator A pointer to the iterator to initialize (MUST NOT be NULL).

◆ otHistoryTrackerIterateExternalRouteHistory()

const otHistoryTrackerExternalRouteInfo* otHistoryTrackerIterateExternalRouteHistory	(	otInstance *	`aInstance,`
		otHistoryTrackerIterator *	`aIterator,`
		uint32_t *	`aEntryAge`
	)

This function iterates over the entries in the Network Data external route entry history list.

Parameters

[in]	`aInstance`	A pointer to the OpenThread instance.
[in,out]	`aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
[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 `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns: The otHistoryTrackerExternalRouteInfo entry or NULL if no more entries in the list.

◆ otHistoryTrackerIterateMulticastAddressHistory()

const otHistoryTrackerMulticastAddressInfo* otHistoryTrackerIterateMulticastAddressHistory	(	otInstance *	`aInstance,`
		otHistoryTrackerIterator *	`aIterator,`
		uint32_t *	`aEntryAge`
	)

This function iterates over the entries in the multicast address history list.

Parameters

[in]	`aInstance`	A pointer to the OpenThread instance.
[in,out]	`aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
[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 `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns: A pointer to otHistoryTrackerMulticastAddressInfo entry or NULL if no more entries in the list.

◆ otHistoryTrackerIterateNeighborHistory()

const otHistoryTrackerNeighborInfo* otHistoryTrackerIterateNeighborHistory	(	otInstance *	`aInstance,`
		otHistoryTrackerIterator *	`aIterator,`
		uint32_t *	`aEntryAge`
	)

This function iterates over the entries in the neighbor history list.

Parameters

[in]	`aInstance`	A pointer to the OpenThread instance.
[in,out]	`aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
[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 `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns: The otHistoryTrackerNeighborInfo entry or NULL if no more entries in the list.

◆ otHistoryTrackerIterateNetInfoHistory()

const otHistoryTrackerNetworkInfo* otHistoryTrackerIterateNetInfoHistory	(	otInstance *	`aInstance,`
		otHistoryTrackerIterator *	`aIterator,`
		uint32_t *	`aEntryAge`
	)

This function iterates over the entries in the network info history list.

Parameters

[in]	`aInstance`	A pointer to the OpenThread instance.
[in,out]	`aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
[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 `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns: A pointer to otHistoryTrackerNetworkInfo entry or NULL if no more entries in the list.

◆ otHistoryTrackerIterateOnMeshPrefixHistory()

const otHistoryTrackerOnMeshPrefixInfo* otHistoryTrackerIterateOnMeshPrefixHistory	(	otInstance *	`aInstance,`
		otHistoryTrackerIterator *	`aIterator,`
		uint32_t *	`aEntryAge`
	)

This function iterates over the entries in the Network Data on mesh prefix entry history list.

Parameters

[in]	`aInstance`	A pointer to the OpenThread instance.
[in,out]	`aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
[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 `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns: The otHistoryTrackerOnMeshPrefixInfo entry or NULL if no more entries in the list.

◆ otHistoryTrackerIterateRxHistory()

const otHistoryTrackerMessageInfo* otHistoryTrackerIterateRxHistory	(	otInstance *	`aInstance,`
		otHistoryTrackerIterator *	`aIterator,`
		uint32_t *	`aEntryAge`
	)

This function iterates over the entries in the RX message history list.

Parameters

[in]	`aInstance`	A pointer to the OpenThread instance.
[in,out]	`aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
[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 `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns: The otHistoryTrackerMessageInfo entry or NULL if no more entries in the list.

◆ otHistoryTrackerIterateTxHistory()

const otHistoryTrackerMessageInfo* otHistoryTrackerIterateTxHistory	(	otInstance *	`aInstance,`
		otHistoryTrackerIterator *	`aIterator,`
		uint32_t *	`aEntryAge`
	)

This function iterates over the entries in the TX message history list.

Parameters

[in]	`aInstance`	A pointer to the OpenThread instance.
[in,out]	`aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
[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 `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns: The otHistoryTrackerMessageInfo entry or NULL if no more entries in the list.

◆ otHistoryTrackerIterateUnicastAddressHistory()

const otHistoryTrackerUnicastAddressInfo* otHistoryTrackerIterateUnicastAddressHistory	(	otInstance *	`aInstance,`
		otHistoryTrackerIterator *	`aIterator,`
		uint32_t *	`aEntryAge`
	)

This function iterates over the entries in the unicast address history list.

Parameters

[in]	`aInstance`	A pointer to the OpenThread instance.
[in,out]	`aIterator`	A pointer to an iterator. MUST be initialized or the behavior is undefined.
[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 `aIterator` initialization time. It is set to `OT_HISTORY_TRACKER_MAX_AGE` for entries older than max age.

Returns: A pointer to otHistoryTrackerUnicastAddressInfo entry or NULL if no more entries in the list.

History TrackerAPI > Add-Ons

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OT_HISTORY_TRACKER_MAX_AGE

Typedef Documentation

◆ otHistoryTrackerIterator

◆ otHistoryTrackerMessageInfo

Enumeration Type Documentation

◆ anonymous enum

◆ otHistoryTrackerAddressEvent

◆ otHistoryTrackerNeighborEvent

◆ otHistoryTrackerNetDataEvent

Function Documentation

◆ otHistoryTrackerEntryAgeToString()

◆ otHistoryTrackerInitIterator()

◆ otHistoryTrackerIterateExternalRouteHistory()

◆ otHistoryTrackerIterateMulticastAddressHistory()

◆ otHistoryTrackerIterateNeighborHistory()

◆ otHistoryTrackerIterateNetInfoHistory()

◆ otHistoryTrackerIterateOnMeshPrefixHistory()

◆ otHistoryTrackerIterateRxHistory()

◆ otHistoryTrackerIterateTxHistory()

◆ otHistoryTrackerIterateUnicastAddressHistory()

History Tracker
API > Add-Ons