This API provides definitions for reading and setting the "user" timebase of the RTC.

The modem manages a real time clock (battery backed clock VCOIN) which keeps time when the power is removed from the legato module (provided that a clock battery is provided). This clock is used by the modem to maintain several time bases which are variously derived from cellular networks or from GPS. Applications should not directly change the value of the real time clock as it may have undesirable effects on modem function. However, a user time base is provided which is synchronized with the RTC so an arbitrary time stored here will increment on a millisecond basis and can be retrieved later even after power down provided that a battery (VCOIN) is provided to keep the RTC running.

The RTC counts milliseconds since the GPS Epoch which is Jan 6, 1980, and increments on each count so that each second in GPS time has a unique number. This is different from Unix time which starts Jan 1, 1970 and has a fixed number of seconds per day so for days that have an extra second in them (leap second) Unix uses the same second twice. This means that over the years an ever increasing number of leap seconds have to be accounted for when converting time between these domains. Leap seconds are introduced periodically because the earths rotation is not constant and is slowing over time such that astronomically measured time and clock time would drift apart but for these adjustments. Unfortunately it also means that Unix time, GPS time and clock time are all drifting apart as well. Fortunately the rate of drift is low with only 26 leap seconds having been added since leap seconds were introduced in 1972. Unfortunately, due to the vagaries of planetary dynamics, it is impossible to predict in which years leap seconds will be added as that calculation must be done retroactively based on observation.

For practical purposes it is not necessary to convert the time you wish to maintain into real GPS time and it will suffice to use Unix epoch time. The amount of drift caused by leap seconds over a year is orders of less than the inherent drift in the RTC and we can expect that most users won't notice a second here or there and that under normal conditions the time will be corrected from an external source such as network time or GPS. If you are synchronising with cellular network time only, then this facility is already provided by the time-service daemon which will update the system time (the time you get when calling le_clk_GetAbsoluteTime() or using linux 'date' command) automatically, but if you are setting the system time yourself from a saved user time value you should probably disable the time service by commenting out the TIME_SERVICES="qcom_time" line in /etc/time_service.conf to prevent the system time from being updated if the modem receives a new time from a cellular network.

Note also that the time stored in the user timebase is incremented on a millisecond basis and unix time is incremented by the second so when storing unix time in the user time base it must be multiplied by 1000 and, conversely, must be divided by 1000 when retrieved.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.