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
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)
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)
Set the time synchronization period.
otNetworkTimeSetXtalThreshold(otInstance *aInstance, uint16_t aXTALThreshold)
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.