Network Time Synchronization
API > Add-Ons

This module includes functions that control network time synchronization service.

Macros

#define OT_TIME_SYNC_INVALID_SEQ 0
zero is considered as invalid time synchronization sequence.

Typedefs

typedef enum otNetworkTimeStatus otNetworkTimeStatus
This enumeration represents OpenThread time synchronization status.
typedef void(* otNetworkTimeSyncCallbackFn ) (void *aCallbackContext)
This function pointer is called when a network time sync or status change occurs.

Enumerations

enum otNetworkTimeStatus {
OT_NETWORK_TIME_UNSYNCHRONIZED = -1,
OT_NETWORK_TIME_RESYNC_NEEDED = 0,
OT_NETWORK_TIME_SYNCHRONIZED = 1
}
This enumeration represents OpenThread time synchronization status.

Functions

otNetworkTimeStatus otNetworkTimeGet ( otInstance *aInstance, uint64_t *aNetworkTime)
Get the Thread network time.
otError otNetworkTimeSetSyncPeriod ( otInstance *aInstance, uint16_t aTimeSyncPeriod)
Set the time synchronization period.
uint16_t otNetworkTimeGetSyncPeriod ( otInstance *aInstance)
Get the time synchronization period.
otError otNetworkTimeSetXtalThreshold ( otInstance *aInstance, uint16_t aXTALThreshold)
Set the time synchronization XTAL accuracy threshold for Router-Capable device.
uint16_t otNetworkTimeGetXtalThreshold ( otInstance *aInstance)
Get the time synchronization XTAL accuracy threshold for Router.
void otNetworkTimeSyncSetCallback ( otInstance *aInstance, otNetworkTimeSyncCallbackFn aCallbackFn, void *aCallbackContext)
Set a callback to be called when a network time sync or status change occurs.

Detailed Description

This module includes functions that control network time synchronization service.

Enumeration Type Documentation

◆ otNetworkTimeStatus

enum otNetworkTimeStatus

This enumeration represents OpenThread time synchronization status.

Enumerator
OT_NETWORK_TIME_UNSYNCHRONIZED

The device hasn't attached to a network.

OT_NETWORK_TIME_RESYNC_NEEDED

The device hasn’t received time sync for more than two periods time.

OT_NETWORK_TIME_SYNCHRONIZED

The device network time is synchronized.

Function Documentation

◆ otNetworkTimeGet()

otNetworkTimeStatus otNetworkTimeGet ( otInstance * aInstance,
uint64_t * aNetworkTime
)

Get the Thread network time.

Parameters
[in] aInstance The OpenThread instance structure.
[in,out] aNetworkTime The Thread network time in microseconds.
Returns
The time synchronization status.

◆ otNetworkTimeGetSyncPeriod()

uint16_t otNetworkTimeGetSyncPeriod ( otInstance * aInstance )

Get the time synchronization period.

Parameters
[in] aInstance The OpenThread instance structure.
Returns
The time synchronization period.

◆ otNetworkTimeGetXtalThreshold()

uint16_t otNetworkTimeGetXtalThreshold ( otInstance * aInstance )

Get the time synchronization XTAL accuracy threshold for Router.

Parameters
[in] aInstance The OpenThread instance structure.
Returns
The XTAL accuracy threshold for Router, in PPM.

◆ otNetworkTimeSetSyncPeriod()

otError otNetworkTimeSetSyncPeriod ( otInstance * aInstance,
uint16_t aTimeSyncPeriod
)

Set the time synchronization period.

This function can only be called while Thread protocols are disabled.

Parameters
[in] aInstance The OpenThread instance structure.
[in] aTimeSyncPeriod The time synchronization period, in seconds.
Return values
OT_ERROR_NONE Successfully set the time sync period.
OT_ERROR_INVALID_STATE Thread protocols are enabled.

◆ otNetworkTimeSetXtalThreshold()

otError otNetworkTimeSetXtalThreshold ( otInstance * aInstance,
uint16_t aXTALThreshold
)

Set the time synchronization XTAL accuracy threshold for Router-Capable device.

This function can only be called while Thread protocols are disabled.

Parameters
[in] aInstance The OpenThread instance structure.
[in] aXTALThreshold The XTAL accuracy threshold for Router, in PPM.
Return values
OT_ERROR_NONE Successfully set the time sync period.
OT_ERROR_INVALID_STATE Thread protocols are enabled.

◆ otNetworkTimeSyncSetCallback()

void otNetworkTimeSyncSetCallback ( otInstance * aInstance,
otNetworkTimeSyncCallbackFn aCallbackFn,
void * aCallbackContext
)

Set a callback to be called when a network time sync or status change occurs.

This callback shall be called only when the network time offset jumps by OPENTHREAD_CONFIG_TIME_SYNC_JUMP_NOTIF_MIN_US or when the status changes.

Parameters
[in] aInstance The OpenThread instance structure.
[in] aCallbackFn The callback function to be called
[in] aCallbackContext The context to be passed to the callback function upon invocation