Time Service

The Time Service is responsible for setting the time zone and maintaining the system time on the STB. The service does not have a TOI interface but uses information objects. If the clock of the STB drifts from the time received from the source, the service will slowly adjust the time to avoid sudden changes which may affect applications and platform services in an unexpected way.

Time Sources

Currently there are four available time sources:

• NTP and SNTP (simpler version of ntp) are widespread ways of distributing time over an Internet connection.
• Timecast is ARRIS' own way of distributing time through a multicasted connection. It is based on the Infocast server which sets up a special channel where the STB can listen for time messages.
• DVB is a way of parsing time through DVB TDT/TOT tables.

Time Source Configuration

The time_sources parameter of kreatv-option-timeman is used to specify a prioritized list (highest priority-first) of the time configuration sources. Supported sources are: NTP, SNTP, KreaTV Timecast and DVB. Possible values are ntp, sntp, timecast and dvb.

kreatv-option-timeman::time_sources=dvb;timecast

If time_sources is unset it will default to timecast.

Ntp Server Selection

Ntp server sources can be configured at build time by kreatv-option-timeman's parameter ntp_server_sources, which is a prioritized list of ntp server sources. Currently four available sources are supported: configurable, tr069, dhcp and server_discovery. See kreatv-option-timeman for details.

Example:

kreatv-option-timeman::ntp_server_sources=configurable;dhcp

In the example, ntp servers can be configured by the application (configurable), or by the dhcp option (option ntp-servers). The application configuration has higher priority.

If ntpdate is enabled by parameter ntpdate_enable=true, ntpdate will be used to synchronize time with ntp servers. Each ntp server will be queried in the priority order one by one until the time is synchronized. The retry logic is controlled by cfg.ntp.retry.interval and cfg.ntp.retry.attempts

The first successfully connected server will be polled using ntpdate. The interval between subsequent polls is randomly selected from the range defined by cfg.ntp.minpoll and cfg.ntp.maxpoll. On an unsuccessful poll, the time service retries and continues to traverse the servers list. When the end of the server list is reached, the time service waits for the poll timeout and continues to query the servers in the list from the beginning.

Time Zone Configuration

It is possible to configure the timezone type and default timezone in build time by adding "kreatv-option-timezone:[time zone type]=[time zone string]" in the build config file. Supported [time zone type] can be "tz_posix" or "tz_database" according to system ability. Read kreatv-option-timezone for your STB model to figure out if "tz_posix" or "tz_database" shall be used to set timezone.

DHCP time zone options are supported to change the timezone by updating the DHCP config file according to different time zone types. If configured time zone type is "tz_posix", DHCP option 100 (tz_posix string) takes effect by adding "option tz_posix [timezone value]" in the DHCP config file. If configured time zone type is "tz_database", DHCP options 101 (tz_database string) takes effect by adding "option tz_database [timezone value]" in the DHCP config file.

The timezone can also be changed at run-time by updating the cfg.locale.timezone information object with a string of the same format. If the information object has not been set by the user, the time zone set at build time can be read from the object.

Time Zone String Format

The followings are three examples:

kreatv-option-timezone::tz_posix="EST+5"
kreatv-option-timezone::tz_posix="CET-1CEST-2,M3.5.0/02:00:00,M10.5.0/03:00:00"
kreatv-option-timezone::tz_database=Europe/Berlin

Time zone string can be in one of three formats according to different time zone type.

"std offset"
"std offset[dst[offset][,start[/time],end[/time]]]"
characters

The first two formats are used to describe the time zone information directly. The POSIX.1 standard only specifies the details of the first two formats. Hence they should be used with time zone type: tz_posix. The first format is used when there is no DST (daylight savings time) for the country or region in question. The second format is used when a country or region has DST in place. The format for each part of a time zone string is as follows:

• std, dst: These two variables must be three or more characters long and must not contain a leading colon, embedded digits, commas, nor plus and minus signs. There is no space character separating the time zone name from the offset, so these restrictions are necessary to parse the specification correctly. If dst lacks a value then the daylight savings time offset is taken to be one hour by default.
• offset: Specifies the time value that must be added to the local time to get a UTC value. It has syntax like [+|-]hh[:mm[:ss]]. This is positive if the local time zone is west of the Prime Meridian and negative if it is east. The hour must be between 0 and 23, and the minute and seconds between 0 and 59.
• The last part is called a rule and has the form date[/time],date[/time]. There are three formats for describing time:
  • Jn: The Julian day where n is between 1 and 365 and the 29 of February is never counted.
  • n: Here n ranges between 0 and 365. February 29 is counted in leap years.
  • Mm.n.d: Probably the most common format. The d'th day (d: 0-6) of week n of month m of the year (n: 1-5, m: 1-12, where week 5 means "the last d day in month m" which may occur in either the fourth or the fifth week). Week 1 is the first week in which the d'th day occurs. Day zero is Sunday.

The last format is the most common format with the GNU C Library. It specifies a selection from a large database of time zone information for many regions of the world. It should be used with time zone type: tz_database. The database is maintained by a community of volunteers and put in the public domain.

• characters: Each operating system interprets this format differently; in the GNU C Library, characters is the name of a file which describes the time zone, like: America/New_York, Europe/London, Asia/Hong_Kong.

Time Zone String Examples

Examples best describe the formats.

EST+5. Eastern Time Zone, five hours behind UTC time.

WST-10. Western Time Zone, ten hours ahead of UTC.

EST+5EDT,M4.1.0/2,M10.5.0/2. Eastern Time Zone, five hours behind UTC time. The DST time is Eastern Daylight Time which is applicable from the first Sunday in April at 2 AM and ends on the last Sunday i in October at 2 AM.

Asia/Hong_Kong. Time Zone that Hong Kong uses, same as UTC+8

Time Service Behavior

The Time Service is alone responsible for the entire time keeping. No application or other platform service should change the clock by calling system time functions. The Time Service handles the following information objects.

• cfg.locale.timezone. By time zone data we mean both the offset from the UTC and the DST values for a given time zone. The Time Service will change time zone if this object is updated.
• var.time.valid. This object is set by the Time Service when a valid system time has been set. Applications can observe this to know when it is safe to trust the clock in the system. When the value is "TRUE", no sudden changes of the clock will occur, only slow adjustment to keep the time correct.