Network Time Synchronization

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

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]aInstanceThe OpenThread instance structure.
[in,out]aNetworkTimeThe Thread network time in microseconds.
Returns
The time synchronization status.

◆ otNetworkTimeGetSyncPeriod()

uint16_t otNetworkTimeGetSyncPeriod ( otInstance aInstance)

Get the time synchronization period.

Parameters
[in]aInstanceThe 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]aInstanceThe 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]aInstanceThe OpenThread instance structure.
[in]aTimeSyncPeriodThe time synchronization period, in seconds.
Return values
OT_ERROR_NONESuccessfully set the time sync period.
OT_ERROR_INVALID_STATEThread 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]aInstanceThe OpenThread instance structure.
[in]aXTALThresholdThe XTAL accuracy threshold for Router, in PPM.
Return values
OT_ERROR_NONESuccessfully set the time sync period.
OT_ERROR_INVALID_STATEThread 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]aInstanceThe OpenThread instance structure.
[in]aCallbackFnThe callback function to be called
[in]aCallbackContextThe context to be passed to the callback function upon invocation