Time

NTP-synchronized timestamps that keep your device's clock consistent with server time — even if the device clock drifts. All telemetry and event readings are automatically timestamped using this module.

Overview

On initialization, the SDK syncs with an NTP server (time.google.com) and calculates an offset between the device clock and the real time. This offset is applied whenever you call now() and whenever the SDK timestamps telemetry or event payloads. The offset is refreshed automatically every 3 hours.

API

now()

JavaScript

device.time.now()

Returns the current NTP-corrected Unix timestamp in milliseconds

Python

device.time.now()

Returns the current NTP-corrected Unix timestamp in milliseconds

C++

device->time.now() → int64_t

device->time.now_seconds() → int64_t

now() returns milliseconds since Unix epoch. now_seconds() returns seconds.

Does not require an active connection — uses the cached offset from the last sync.

toDate()

JavaScript

device.time.toDate(timestamp)

Parameter	Type	Description
timestamp	number	Unix timestamp in milliseconds

Returns a Date object

Python

device.time.to_date(timestamp)

Parameter	Type	Description
timestamp	number	Unix timestamp in milliseconds

Returns a datetime object

C++

Not provided — use standard C time functions:

int64_t ms = device->time.now();
time_t seconds = (time_t)(ms / 1000);
struct tm timeinfo;
localtime_r(&seconds, &timeinfo);

toTimestamp()

JavaScript

device.time.toTimestamp(date)

Parameter	Type	Description
date	Date	A Date object

Returns Unix timestamp in milliseconds

Python

device.time.to_timestamp(dt)

Parameter	Type	Description
dt	datetime	A datetime object

Returns Unix timestamp in milliseconds

C++

Not provided — use now() directly or standard C time functions.

setTimezone()

JavaScript

device.time.setTimezone(tz)

Parameter	Type	Description
tz	string	IANA timezone string (e.g., "America/New_York", "Europe/London", "Asia/Tokyo")

Python

device.time.set_timezone(tz)

Parameter	Type	Description
tz	string	IANA timezone string (e.g., "America/New_York", "Europe/London", "Asia/Tokyo")

C++

Not provided — use the POSIX timezone API:

setenv("TZ", "EST5EDT,M3.2.0,M11.1.0", 1);
tzset();

Get Synchronized Time

JavaScript

const timestamp = device.time.now();
console.log("Current time (ms):", timestamp);

Python

timestamp = device.time.now()
print("Current time (ms):", timestamp)

C++

int64_t timestamp = device->time.now();
ESP_LOGI("app", "Current time (ms): %lld", timestamp);

int64_t seconds = device->time.now_seconds();
ESP_LOGI("app", "Current time (s): %lld", seconds);

Convert Between Formats

JavaScript

// timestamp to Date
const timestamp = device.time.now();
const date = device.time.toDate(timestamp);
console.log(date.toISOString());

// Date back to timestamp
const ts = device.time.toTimestamp(new Date());
console.log(ts);

Python

from datetime import datetime

# timestamp to datetime
timestamp = device.time.now()
dt = device.time.to_date(timestamp)
print(dt.isoformat())

# datetime back to timestamp
ts = device.time.to_timestamp(datetime.now())
print(ts)

C++

// timestamp to struct tm
int64_t ms = device->time.now();
time_t seconds = (time_t)(ms / 1000);
struct tm timeinfo;
localtime_r(&seconds, &timeinfo);

char buf[64];
strftime(buf, sizeof(buf), "%Y-%m-%dT%H:%M:%S", &timeinfo);
ESP_LOGI("app", "%s", buf);

Set Timezone

JavaScript

device.time.setTimezone("America/New_York");

Python

device.time.set_timezone("America/New_York")

C++

// POSIX TZ format — see ESP-IDF docs for full syntax
setenv("TZ", "EST5EDT,M3.2.0,M11.1.0", 1);
tzset();

Uses IANA timezone identifiers. Common examples:

Timezone	Identifier
US Eastern	America/New_York
US Pacific	America/Los_Angeles
UK	Europe/London
Central Europe	Europe/Berlin
India	Asia/Kolkata
Japan	Asia/Tokyo
Australia Eastern	Australia/Sydney

Auto-Resync

The offset is refreshed automatically every 3 hours while the device is connected. If the NTP sync fails silently (e.g., network issue), the SDK keeps using the previous offset — now() never breaks.