nodemcu-firmware/docs/modules/time.md

Time/NTP Module

Since	Origin / Contributor	Maintainer	Source
2018-11-25	Skirmantas Lauzikas	Skirmantas Lauzikas	time.c

This module offers facilities for converting between Unix time and calendar, setting/getting system time, locale and control of NTP client.

time.cal2epoch()

Converts calendar table to a timestamp in Unix epoch

Syntax

time.cal2epoch(calendar)

Parameters

• calendar Table containing calendar info.
  • year 1970 ~ 2038
  • mon month 1 ~ 12 in current year
  • day day 1 ~ 31 in current month
  • hour
  • min
  • sec

Returns

number of seconds since the Epoch

Example

calendar={}
calendar.year = 2018-11-20
calendar.mon = 11
calendar.day = 20
calendar.hour = 1
calendar.min = 40
calendar.sec = 50

timestamp = time.cal2epoch(calendar)
time.set(timestamp)

time.epoch2cal()

Converts timestamp in Unix epoch to calendar format

Syntax

time.epoch2cal(time)

Parameters

• time number of seconds since the Epoch

Returns

A table containing the fields:

• year 1970 ~ 2038
• mon month 1 ~ 12 in current year
• day day 1 ~ 31 in current month
• hour
• min
• sec
• yday day 1 ~ 366 in current year
• wday day 1 ~ 7 in current weak (Sunday is 1)
• dst day time adjustment:
  • 1 (DST in effect, i.e. daylight time)
  • 0 (DST not in effect, i.e. standard time)
  • -1 (Unknown DST status)

Example

--Gets current time calendar format, no locale adjustment
time = time.epoch2cal(time.get())
print(string.format("%04d-%02d-%02d %02d:%02d:%02d DST:%d", time["year"], time["mon"], time["day"], time["hour"], time["min"], time["sec"], time["dst"]))

time.get()

Returns current system time in the Unix epoch (seconds from midnight 1970/01/01).

Syntax

time.get()

Parameters

none

Returns

A two-value timestamp consisting of:

• sec seconds since the Unix epoch
• usec the microseconds part

Example

sec, usec = time.get()

See also

time.epch2cal()

time.getlocal()

Returns current system time adjusted for the locale in calendar format.

Syntax

time.getlocal()

Parameters

none

Returns

A table containing the fields:

• year 1970 ~ 2038
• mon month 1 ~ 12 in current year
• day day 1 ~ 31 in current month
• hour
• min
• sec
• yday day 1 ~ 366 in current year
• wday day 1 ~ 7 in current weak (Sunday is 1)
• dst day time adjustment:
  • 1 (DST in effect, i.e. daylight time)
  • 0 (DST not in effect, i.e. standard time)
  • -1 (Unknown DST status)

Example

localTime = time.getlocal()
print(string.format("%04d-%02d-%02d %02d:%02d:%02d DST:%d", localTime["year"], localTime["mon"], localTime["day"], localTime["hour"], localTime["min"], localTime["sec"], localTime["dst"]))

time.initntp()

Initializes and starts NTP client

Syntax

time.initntp([ntpAddr])

Parameters

• ntpAddr address of a NTP server, defaults to "pool.ntp.org" if none is specified

Returns

nil

Example

time.initntp("pool.ntp.org")

time.ntpenabled()

Checks if NTP client is enabled.

Syntax

time.ntpenabled()

Parameters

none

Returns

true if NTP client is enabled.

time.ntpstop()

Stops NTP client.

Syntax

time.ntpstop()

Parameters

none

Returns

nil

time.set()

Sets system time to a given timestamp in the Unix epoch (seconds from midnight 1970/01/01).

Syntax

time.set(time)

Parameters

• time number of seconds since the Epoch

Returns

nil

Example

--set time to 2018-11-20 01:40:50
time.set(1542678050)

See also

time.cal2epoc()

time.settimezone()

Sets correct format for Time Zone locale

Syntax

time.settimezone(timezone)

Parameters

• timezone a string representing timezone, can also include DST adjustment. For full syntax see TZ variable documentation.

Returns

nil

Example

--set timezone to Eastern Standard Time
time.settimezone("EST+5")