Date-Time

The date-time library retrieves the date-time information and stores it as Zephyr time and modem time.

Overview

Date-time information update can be triggered to this library by the following means:

• Periodic date-time updates with the frequency determined by the option CONFIG_DATE_TIME_UPDATE_INTERVAL_SECONDS.

• By the client using the date_time_update_async() function.

• External date-time source from which the date-time information is set to this library with the date_time_set() function.

• Automatic update when connecting to LTE network if the option CONFIG_DATE_TIME_AUTO_UPDATE is set.

• Notification about date-time information coming from the modem through AT%XTIME notification.

When this library retrieves the date-time information, it is fetched in the following prioritized order:

1. The library checks if the current date-time information is valid and relatively new. If the date-time information currently set in the library was obtained sometime during the interval set by the CONFIG_DATE_TIME_TOO_OLD_SECONDS option, the library does not fetch new date-time information. In this way, unnecessary update cycles are avoided.

2. If the check fails and the CONFIG_DATE_TIME_MODEM option is set, the library requests time from the nRF91 Series modem.

3. If the time information obtained from the nRF91 Series modem is not valid and the CONFIG_DATE_TIME_NTP option is set, the library requests time from an NTP server.

4. If the NTP time request does not succeed, the library tries to request time information from a different NTP server, before it fails.

The current date-time information is stored as Zephyr time when it has been retrieved and hence, applications can also get the time using the POSIX function clock_gettime. It is also stored as modem time if the modem does not have valid time.

Implementation

The date_time_set() function can be used to obtain the current date-time information from external sources independent of the internal date-time update routine. Time from GNSS can be such an external source.

The option CONFIG_DATE_TIME_AUTO_UPDATE determines whether date-time update is triggered automatically when the LTE network becomes available. Libraries that require date-time information can just enable this library to get updated time information. Applications do not need to do anything to trigger time update when they start because this library handles it automatically.

Retrieving date-time information using the POSIX function clock_gettime is encouraged when feasible. You can obtain the information also from the library by calling either the date_time_uptime_to_unix_time_ms() function or the date_time_now() function. See the API documentation for more information on these functions.

Note

It is recommended to set the CONFIG_DATE_TIME_AUTO_UPDATE option to trigger a time update when the device has connected to LTE. If an application has time-dependent operations immediately after connecting to the LTE network, it should wait for a confirmation indicating that time has been updated. If the CONFIG_DATE_TIME_AUTO_UPDATE option is not set, the first date-time update cycle (after boot) does not occur until the time set by the CONFIG_DATE_TIME_UPDATE_INTERVAL_SECONDS option has elapsed.

Configuration

Configure the following Kconfig options to enable this library and its main functionalities:

• CONFIG_DATE_TIME - Enables this library.

• CONFIG_DATE_TIME_MODEM - Enables use of modem time.

• CONFIG_DATE_TIME_NTP - Enables use of NTP (Network Time Protocol) time.

• CONFIG_DATE_TIME_AUTO_UPDATE - Trigger date-time update automatically when LTE is connected.

Configure the following options to fine-tune the behavior of the library:

• CONFIG_DATE_TIME_UPDATE_INTERVAL_SECONDS - Control the frequency with which the library fetches the time information.

• CONFIG_DATE_TIME_TOO_OLD_SECONDS - Control the time when date-time update is applied if previous update was done earlier.

• CONFIG_DATE_TIME_NTP_QUERY_TIME_SECONDS - Timeout for a single NTP query.

• CONFIG_DATE_TIME_THREAD_STACK_SIZE - Configure the stack size of the date-time update thread.

Samples using the library

The following nRF Connect SDK samples and applications use this library:

• Asset Tracker v2

• Serial LTE modem

• Cellular: Location

• Cellular: GNSS

• Cellular: Modem Shell

• Cellular: LwM2M Client

Limitations

The date-time library can only have one application registered at a time. If there is already an application handler registered, another registration will override the existing handler. Also, using the date_time_update_async() function will override the existing handler.

Dependencies

• Modem library integration layer

• LTE link control

• Simple Network Time Protocol Library

API documentation

Header file: include/date_time.h

Source files: lib/date_time/src/

group date_time

Library that maintains the current date time UTC which can be fetched in order to timestamp data.

Typedefs

typedef void (*date_time_evt_handler_t)(const struct date_time_evt *evt)

Date time library asynchronous event handler.

Param evt:

[in] The event and any associated parameters.

Enums

enum date_time_evt_type

Date time notification event types used to signal the application.

Values:

enumerator DATE_TIME_OBTAINED_MODEM

Date time library has obtained valid time from the modem.

enumerator DATE_TIME_OBTAINED_NTP

Date time library has obtained valid time from NTP servers.

enumerator DATE_TIME_OBTAINED_EXT

Date time library has obtained valid time from external source.

enumerator DATE_TIME_NOT_OBTAINED

Date time library does not have valid time.

Functions

int date_time_set(const struct tm *new_date_time)

Set the current date time.

Note

See http://www.cplusplus.com/reference/ctime/tm/ for accepted input format. Members wday and yday have no impact on the date time UTC and are thus does not need to be set.

Parameters:

• new_date_time – [in] Pointer to a tm structure.

Returns:

0 If the operation was successful.

Returns:

-EINVAL If a member of the passing variable new_date_time does not adhere to the tm structure format, or pointer is passed in as NULL.

int date_time_uptime_to_unix_time_ms(int64_t *uptime)

Get the date time UTC when the passing variable uptime was set. This function requires that k_uptime_get() has been called on the passing variable uptime prior to the function call. In that case the uptime will not be too large or negative.

Note

If the function fails, the passed in variable retains its old value.

Parameters:

• uptime – [inout] Pointer to a previously set uptime.

Returns:

0 If the operation was successful.

Returns:

-ENODATA If the library does not have a valid date time UTC.

Returns:

-EINVAL If the passed in pointer is NULL, dereferenced value is too large, already converted or if uptime is negative.

int date_time_now(int64_t *unix_time_ms)

Get the current date time UTC.

Note

If the function fails, the passed in variable retains its old value.

Parameters:

• unix_time_ms – [out] Pointer to a variable to store the current date time UTC.

Returns:

0 If the operation was successful.

Returns:

-ENODATA If the library does not have a valid date time UTC.

Returns:

-EINVAL If the passed in pointer is NULL.

int date_time_now_local(int64_t *local_time_ms)

Get the current date time in local time.

Note

If the function fails, the passed in variable retains its old value.

Parameters:

• local_time_ms – [out] Pointer to a variable to store the current date time.

Returns:

0 If the operation was successful.

Returns:

-ENODATA If the library does not have a valid date time.

Returns:

-EAGAIN If the library has the date time, but not a valid timezone.

Returns:

-EINVAL If the passed in pointer is NULL.

bool date_time_is_valid(void)

Convenience function that checks if the library has obtained an initial valid date time.

Note

If this function returns false there is no point of subsequent calls to other functions in this API that depend on the validity of the internal date time. We know that they would fail beforehand.

Returns:

true The library has obtained an initial date time.

Returns:

false The library has not obtained an initial date time.

bool date_time_is_valid_local(void)

Check if the library has obtained an initial valid date time and timezone.

Note

If this function returns false there is no point of subsequent calls to date_time_now_local().

Returns:

true The library has obtained a local date time.

Returns:

false The library has not obtained a local date time.

void date_time_register_handler(date_time_evt_handler_t evt_handler)

Register an event handler for Date time library events.

Note

The library only allows for one event handler to be registered at a time. A passed in event handler in this function will overwrite the previously set event handler.

Parameters:

• evt_handler – Event handler. Handler is de-registered if parameter is NULL.

int date_time_update_async(date_time_evt_handler_t evt_handler)

Asynchronous update of internal date time UTC. This function initiates a date time update regardless of the internal update interval. If an event handler is provided it will be updated with library events, accordingly.

Parameters:

• evt_handler – Event handler. If the passed in pointer is NULL the previous registered event handler is not de-registered. This means that library events will still be received in the previously registered event handler.

Returns:

0 If the operation was successful.

void date_time_clear(void)

Clear the current date time held by the library.

int date_time_timestamp_clear(int64_t *unix_timestamp)

Clear a timestamp in UNIX time ms.

Parameters:

• unix_timestamp – [inout] Pointer to a unix timestamp.

Returns:

0 If the operation was successful.

Returns:

-EINVAL If the passed in pointer is NULL.

struct date_time_evt

#include <date_time.h>

Struct with data received from the Date time library.

Public Members

enum date_time_evt_type type

Type of event.