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 Represents OpenThread time synchronization status.

Typedefs
`otNetworkTimeStatus`	typedef `enum otNetworkTimeStatus` Represents OpenThread time synchronization status.
`otNetworkTimeSyncCallbackFn)(void *aCallbackContext)`	typedef `void(*` 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.

Macros
`OT_TIME_SYNC_INVALID_SEQ 0`	zero is considered as invalid time synchronization sequence.

Enumerations

otNetworkTimeStatus

 otNetworkTimeStatus

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

Represents OpenThread time synchronization status.

otNetworkTimeSyncCallbackFn

void(* otNetworkTimeSyncCallbackFn)(void *aCallbackContext)

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.

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.

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.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.