# Network Time Synchronization

# Network Time Synchronization

This module includes functions that control network time synchronization service.

## Summary

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1gae2ef9060d564f4d373bbe53a631a5af0{ https://openthread.io/reference/group/api-network-time#group__api-network-time_1ggae2ef9060d564f4d373bbe53a631a5af0a8f2488812ea33555e046a5e1e6575522 = -1, https://openthread.io/reference/group/api-network-time#group__api-network-time_1ggae2ef9060d564f4d373bbe53a631a5af0aa72cbb95b5c69f04f91958fe7be76f46 = 0, https://openthread.io/reference/group/api-network-time#group__api-network-time_1ggae2ef9060d564f4d373bbe53a631a5af0a3104bf1bed5b35eaa9c820a951c29b8e = 1 }` | enumRepresents OpenThread time synchronization status. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1ga74c05dcc5737a4f51232f97b79c897a7` | typedef `enum https://openthread.io/reference/group/api-network-time#group__api-network-time_1gae2ef9060d564f4d373bbe53a631a5af0` Represents OpenThread time synchronization status. |
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1gad5ec417eb690200b6717dd593e221f24)(void *aCallbackContext)` | typedef `void(*` Pointer is called when a network time sync or status change occurs. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1gae354525bb35685b122644dea5b1b83de(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint64_t *aNetworkTime)` | `https://openthread.io/reference/group/api-network-time#group__api-network-time_1gae2ef9060d564f4d373bbe53a631a5af0` Get the Thread network time. |
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1gab7d5b4f32a91513ecde9ddfa39f4113d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Get the time synchronization period. |
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1ga906d642a8278cc00792856423bdd3935(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Get the time synchronization XTAL accuracy threshold for Router. |
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1gab61ef2558729a3ac59ea45ddd4872d18(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aTimeSyncPeriod)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Set the time synchronization period. |
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1ga431de6ae4845803a84b1e440d6e40d4c(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aXTALThreshold)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Set the time synchronization XTAL accuracy threshold for Router-Capable device. |
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1ga40ae37e6466a0d533d46b6cfbbde85bc(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-network-time#group__api-network-time_1gad5ec417eb690200b6717dd593e221f24 aCallbackFn, void *aCallbackContext)` | `void` Set a callback to be called when a network time sync or status change occurs. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/api-network-time#group__api-network-time_1ga8a4cabbc9b868491863df7e04b37fe99 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.

<br />

| 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.

<br />

| 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.

<br />

| 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.

<br />

| 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.

<br />

| 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.

<br />

| 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](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).