Network Time Synchronization

This module includes functions that control network time synchronization service.

Summary

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

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

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

Enumerations

otNetworkTimeStatus

 otNetworkTimeStatus

This enumeration represents OpenThread time synchronization status.

Properties
`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.
`OT_NETWORK_TIME_UNSYNCHRONIZED`	The device hasn't attached to a network.

Typedefs

otNetworkTimeStatus

enum otNetworkTimeStatus otNetworkTimeStatus

This enumeration represents OpenThread time synchronization status.

otNetworkTimeSyncCallbackFn

void(* otNetworkTimeSyncCallbackFn)(void *aCallbackContext)

This function pointer is called when a network time sync or status change occurs.

Functions

otNetworkTimeGet

otNetworkTimeStatus otNetworkTimeGet(
  otInstance *aInstance,
  uint64_t *aNetworkTime
)

Get the Thread network time.

Details

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.

Details

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.

Details

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.

Details

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.

Details

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.

Details

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

Macros

OT_TIME_SYNC_INVALID_SEQ

 OT_TIME_SYNC_INVALID_SEQ 0

zero is considered as invalid time synchronization sequence.