Skip to main content


Returns the current date and time


Device + Agent


Name Type Description
timestamp Integer An optional date and time expressed as seconds elapsed since midnight, 1 Jan 1970




This function returns the current date and time in the form of a table; its slots provide the following data:

Key Description Value Range
sec Seconds after the minute 0-59
min Minutes after the hour 0-59
hour Hours since midnight 0-23
day Day of the month 1-31
month Month 0-11; January = 0
year The year
wday Day of the week 0-6; Sunday = 0
yday Day of the year 0-365; 1 January = 0
time Unix timestamp in whole seconds
usec Additional Unix timestamp microsecond count

The time key provides the current date and time in Unix timestamp form. It yields a value in whole seconds. If you require microsecond granularity, read the usec key — this gives the microsecond count between each second recorded by time. The usec key is available only when date() is called from within agent code; it is non-functional on the device, where it will always return 0.

Optionally, an integer representing a period seconds elapsed since 00:00:00, 1 January 1970 may be passed to date() as a parameter to be formatted and returned as a table by the function. This integer format is generated by the function time(). Note unless the value passed into date() lies in the range 946,684,800 (January 1, 2000) to 4,102,444,799 (December 31, 2099), date() will return a table with values set to zero.

The imp implementation of date() will format the returned table to UTC time. Standard Squirrel provides an optional second parameter, a string constant which specifies the format of the information generated by date(). However, this is non-functional on the imp, so is not described here.

Module-specific Notes


On the imp005, date() is only correct after connecting to the server.

Example Code

The following code comes from a digital clock app to get the current time and use it to calculate whether we are in AM or PM — should the user want to see a 12-hour format rather than a 24-hour clock — and to apply an offset if the user wants to display the time in another country.