Date-Time¶
The date-time library maintains the current date-time information in UTC format.
The option CONFIG_DATE_TIME_UPDATE_INTERVAL_SECONDS determines the frequency with which the library updates the date-time information.
The information is fetched in the following prioritized order:
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 CONFIG_DATE_TIME_UPDATE_INTERVAL_SECONDS, the library does not fetch new date-time information. In this way, unnecessary update cycles are avoided.
If the aforementioned check fails, the library requests time from the onboard modem of nRF9160.
If the time information obtained from the onboard modem of nRF9160 is not valid, the library requests time from NTP servers.
If the NTP time request does not succeed, the library tries to request time information from several other NTP servers, before it fails.
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 GPS can be such an external source.
To get date-time information from the library, either call 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
The first date-time update cycle (after boot) does not occur until the time set by the CONFIG_DATE_TIME_UPDATE_INTERVAL_SECONDS has elapsed.
It is recommended to call the date_time_update_async() function after the device has connected to LTE, to get the initial date-time information.
Configuration¶
CONFIG_DATE_TIME_UPDATE_INTERVAL_SECONDS
Configure this option to control the frequency with which the library fetches the time information.
API documentation¶
include/date_time.hlib/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.
- Parameters
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.
-
enumerator
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.
- 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.
Warning
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, or already converted.
-
int
date_time_now(int64_t *unix_time_ms)¶ Get the current date time UTC.
Warning
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.
-
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.
-
void
date_time_register_handler(date_time_evt_handler_t evt_handler)¶ Register an event handler for Date time library events.
Warning
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.
-
int
date_time_clear(void)¶ Clear the current date time held by the library.
- Returns
0 If the operation was successful.
-
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.
-
enum date_time_evt_type
-
typedef void (*