Clock Service's Clock Sync Interface
This clock sync interface is part of Legato's Clock Service for managing and syncing the clock time on a Legato device. It includes the APIs for acquiring the current clock time from a given time server, with or without setting it into the device's system clock.
Time Sources
A current clock time can be queried from a time source via different protocols. While the various types of sources are defined in le_clkSync_ClockSource, the currently supported time protocols are:
Both of these sources run on an IP network and would require the device to have an active data channel established via DCS ahead of time. Each time server of these source types is thus specified by its IP address or host name. For each of these source types, 2 servers max can be configured, i.e. 2 IP addresses or host names.
Time Sources
Each configured clock time source can be assigned a numeric priority within the range 0-9, with 9 as the highest priority and 0 the lowest and the default if not explicitly specified. In an execution of the system clock update via a call to le_clkSync_UpdateSystemTime, the source with the highest priority will first be attempted. And likewise down the prioritized list, each will be tried until a successful update is resulted.
Time Sources
These configurations are to be installed and maintained on Clock Service's config tree path clockTime:/source/. For each source, its priority and location configurations can be configured. The path for the former is clockTime:/source/<source>/priority. With TP or NTP as the source, its location configuration is the IP address or host name of its time server, and up to 2 can be configured. The paths used are clockTime:/source/<source>/config/1 and clockTime:/source/<source>/config/2. The following is an example:
clockTime:/
source/
ntp/
priority<int> == 7
config/
1<string> == pool.ntp.org
tp/
config/
1<string> == time-a.timefreq.bldrdoc.gov
2<string> == time.nist.gov
priority<int> == 9
- Note
- These clock time configurations can be installed and modified not only through the "config set" command on a device's console and Legato's le_cfg_Set APIs, but also AVC's write operation for Sierra Wireless' proprietary LWM2M object 33405 from a remote AirVantage server.
a Clock Time Update
- Warning
- It is a high risk system operation to update a device's system time, as there could be other time-sensitive activities running on the device. Also, it is an asynchronous operation that will take some time to try with different sources, complete acquiring the latest time, and installing it into the system clock. Thus, users have to use due diligence in calling the given API to trigger this execution. In many cases, it might even be necessary to schedule this execution to a maintenance time window within which all other activities are minimal, and to back off for a while by disallowing any new activities after it is triggered, and until the update is fully complete.
To execute a clock time update into a device's system clock, a client app can call le_clkSync_UpdateSystemTime. Upon such execution, a prioritized list of all the configured sources will be internally generated and then walked from the highest priority to the lowest in attempt to contact the source, acquire the current time, and install it into the system clock. Such attempt terminates upon either a success or the end of the list. The result of the last attempt with each source is archived, which is a per-source status and not a system-wide one.
Note that this execution is asychronous. When le_clkSync_UpdateSystemTime returns to its caller, only the triggering of the update is complete, and not the update itself. This API's input argument is an event handler of type le_clkSync_UpdateSystemTimeHandlerFunc_t provided by the caller which will be upon the completion of the update. This is the way for caller to learn back about such completion. The output argument of this callback function is the overall status of the update execution of type le_result_t.
For more granular details, the status of the update attempt using each source can be found via the API le_clkSync_GetUpdateSystemStatus, and this status code is defined in the enum le_clkSync_UpdateSystemStatus which is an exact correspondence to the status code defined in Sierra Wireless' proprietary LWM2M object 33405's resource 3.
Copyright (C) Sierra Wireless Inc.