import time
The time module provides wall-clock time for timestamps, logging, scheduled actions, telemetry, and offline devices. Unlike system.millis(), which measures time since boot, time represents actual UTC calendar time. ESP32 devices do not automatically know the current date and time after power up. Synchronize over Wi-Fi with NTP, set the clock manually, or load it from a DS3231 hardware RTC.
Quick example
import time
import wifi
wifi.connect(env.WIFI_SSID, env.WIFI_PASS)
def clock_ready():
print(time.now())
print(time.epoch())
time.on_sync(clock_ready)
wifi.on_connect(lambda: time.sync())
rtc = time.rtc(type="ds3231", sda=8, scl=9)
if rtc.is_valid():
rtc.load()
print(time.now())
importtime
Real-world time, date, NTP synchronization, and DS3231 RTC support.
The time module provides wall-clock time for timestamps, logging, scheduled actions, telemetry, and offline devices. Unlike system.millis(), which measures time since boot, time represents actual UTC calendar time. ESP32 devices do not automatically know the current date and time after power up. Synchronize over Wi-Fi with NTP, set the clock manually, or load it from a DS3231 hardware RTC.
time.sync() -> bool
time.sync() -> boolSynchronize the system clock using NTP.
The device must already have network connectivity. Use wifi.on_connect() when synchronization should start after Wi-Fi receives an IP address.
bool bool True when SNTP was started. Use on_sync() to run code after the clock is actually synchronized.
time.on_sync(callback: callback) -> bool
time.on_sync(callback: callback) -> boolRegister a callback that runs after successful clock synchronization.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
callback |
callback |
positional or keyword | Yes | Function called after NTP synchronization or another clock sync event completes. |
bool bool True when the callback was registered.
time.is_synced() -> bool
time.is_synced() -> boolReturn whether the system has valid real-world time.
bool bool True when the clock was synchronized or explicitly set.
time.now() -> str
time.now() -> strReturn the current UTC date and time as an ISO 8601 string.
str str UTC timestamp in YYYY-MM-DDTHH:MM:SSZ form.
time.epoch() -> int
time.epoch() -> intReturn the current Unix timestamp.
int int Seconds since 1970-01-01T00:00:00Z.
time.datetime() -> dict
time.datetime() -> dictReturn the current UTC date and time as a dictionary.
dict dict with year, month, day, hour, minute, second, and weekday fields.
time.date() -> str
time.date() -> strReturn the current UTC date.
str str Date in YYYY-MM-DD form.
time.clock() -> str
time.clock() -> strReturn the current UTC time of day.
str str Time in HH:MM:SS form.
time.set(timestamp: int) -> bool
time.set(timestamp: int) -> boolSet the system clock manually.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
timestamp |
int |
positional or keyword | Yes | Unix timestamp in seconds. |
bool bool True when the system clock was set.
time.timezone(offset_minutes: int) -> bool
time.timezone(offset_minutes: int) -> boolSet the local UTC offset in minutes.
The internal clock remains UTC. This offset only affects local().
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
offset_minutes |
int |
positional or keyword | Yes | Fixed offset from UTC in minutes. For UTC-4 use -240. For UTC+5:30 use 330. |
bool bool True when the local offset was stored.
time.local() -> str
time.local() -> strReturn local time using the configured fixed UTC offset.
Fixed offsets do not automatically handle daylight-saving-time transitions. Prefer UTC for telemetry, storage, and machine-to-machine messages.
str str Local ISO 8601 timestamp such as 2026-08-25T17:12:18+05:30.
time.rtc(type: str, sda: int, scl: int, port: int = None, address: int = None, frequency: int = None) -> time_rtc
time.rtc(type: str, sda: int, scl: int, port: int = None, address: int = None, frequency: int = None) -> time_rtcCreate a DS3231 hardware RTC object.
A real-time clock lets a device retain date and time while the ESP32 is powered off. The DS3231 connects over I2C and uses a backup battery.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
type |
str |
positional or keyword | Yes | RTC device type. Use "ds3231". |
sda |
int |
positional or keyword | Yes | I2C SDA GPIO connected to the RTC module. |
scl |
int |
positional or keyword | Yes | I2C SCL GPIO connected to the RTC module. |
port |
int |
positional or keyword | No | Optional I2C controller number. Defaults to 0. |
address |
int |
positional or keyword | No | Optional I2C address. Defaults to 0x68. |
frequency |
int |
positional or keyword | No | Optional I2C bus frequency in Hz. Defaults to 100000. |
time_rtc time_rtc object.
time.rtc().now() -> str
time.rtc().now() -> strRead current UTC time directly from the RTC as an ISO 8601 string.
time.rtc().epoch() -> int
time.rtc().epoch() -> intRead RTC time as a Unix timestamp.
time.rtc().set(timestamp) -> bool
time.rtc().set(timestamp) -> boolSet the RTC from a Unix timestamp.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
timestamp |
int |
positional or keyword | Yes | Required value. |
time.rtc().load() -> bool
time.rtc().load() -> boolLoad RTC time into the system clock.
time.rtc().is_valid() -> bool
time.rtc().is_valid() -> boolReturn True when the RTC contains valid time.
time.rtc().info() -> dict
time.rtc().info() -> dictReturn RTC type, I2C pins, address, frequency, and validity.
time.rtc().close() -> bool
time.rtc().close() -> boolRelease the RTC I2C resources.