Home Contents | # Handling date and time | Lua | Application Notes

## ABSTRACT

Introduction to UTC based date and time handling.

## INTRODUCTION

This application note explains how to run the built-in real time clock on Coordinated Universal Time (UTC). UTC is the global standard of time.

Running the internal hardware clock on UTC has the advantage that no daylight saving time handling is necessary while software works with date and time values. This means that there never are any discontinuities in the date/time values, the time never "jumps around".

Only when presenting the time to the user it is converted to local time, including any daylight saving adjustment necessary. This conversion is fully automatic.

For that purpose, the Core4 system contains a zoneinfo database with information about local timezones. To keep final firmware sizes small, only the most common timezones are included in a default firmware build. The application designer can always add more timezones.

## USAGE

### Reading the hardware clock and converting it to the user's local time

local utc = clock.getDateTime() local localtime = utc:toLocal()

The variable localtime now contains the current time, ready to be displayed to the user.

### Setting the hardware clock from a local time that was entered by the user

Assuming we have the current date/time available in the variables year, month, day, hour, minute and second, this code will set the hardware clock to the corresponding UTC value.

local localtime = clock.newDateTime(year, month, day, hour, minute, second) local utc = localtime:toUTC() clock.setDateTime(utc)

## TIMEZONES

To make automatic conversion work, the system must know the local timezone. The timezone is speficied as a name. Examples are "Europe/Berlin", "US/Eastern" or "Brazil/Acre". Each of these names points to a file in the directory /etc/zoneinfo. Setting the timezone to "Europe/Berlin" would in fact make the system read the file /etc/zoneinfo/Europe/Berlin.

### Changing the timezone

local tz = "Europe/Berlin" clock.tzset(tz) kconfig.setValue("c4t_gen_timezone", tz)

The call to clock.tzset() changes the current timezone, while the call to kconfig.setValue() will save it to nonvolatile storage.

### Available timezones

By default, the system includes the following timezones. More timezone files can be downloaded from ftp://elsie.nci.nih.gov/pub/, the public domain timezone database.

Brazil/West Brazil/Acre Brazil/East Brazil/DeNoronha | Canada/Eastern Canada/Central Canada/Yukon Canada/Mountain Canada/Pacific Canada/Newfoundland Canada/Saskatchewan Canada/Atlantic Canada/East-Saskatchewan | Europe/Vienna Europe/Rome Europe/Zurich Europe/Berlin Europe/Amsterdam | Mexico/BajaNorte Mexico/BajaSur Mexico/General | US/Samoa US/East-Indiana US/Aleutian US/Hawaii US/Arizona US/Central US/Mountain US/Indiana-Starke US/Alaska US/Pacific US/Michigan US/Eastern

## REFERENCES

Wikipedia on UTC
The timezone database homepage
Current timezone database files
Wikipedia on the timezone database