Tempo

Tempo is a time, calendar, sun, moon, and scheduling toolkit for ESP32.

Tempo helps you keep UTC-first time logic explicit in Arduino ESP32 projects while still providing timezone-aware local conversion, DST-aware calendar helpers, cached sun cycle data, moon phase data, and scheduled job execution.

Why use Tempo?

• UTC-first - DateTime stores absolute UTC time, while local conversion is explicit.
• DST-aware - POSIX timezone strings are used for local time and recurring schedules.
• ESP32-friendly - FreeRTOS service tasks, queue-based scheduling, and result-based errors.
• Sun and moon data - sunrise, sunset, solar noon, daylight checks, moon angle, and illumination.
• Production-minded - no explicit exception-based control flow, bindable callbacks, and C++20 with embedded constraints.

Install

PlatformIO

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino

lib_deps =
  https://github.com/ZekStack/tempo.git

build_flags =
  -std=gnu++20
build_unflags =
  -std=gnu++11

Arduino IDE

Tempo is not published to Arduino Library Manager yet.

Install it by downloading the repository ZIP or cloning it into your Arduino libraries folder.

Arduino/libraries/Tempo

Quick start

#include <Arduino.h>
#include <Tempo.h>

Tempo tempo;
TempoScheduler scheduler;

void setup() {
	Serial.begin(115200);

	TempoConfig config;
	config.timezone = "CET-1CEST,M3.5.0/2,M10.5.0/3";
	config.latitude = 47.4979f;
	config.longitude = 19.0402f;

	TempoResult result = tempo.init(config);
	if (!result) {
		Serial.println(result.message.c_str());
		return;
	}

	scheduler.init(tempo);
	scheduler.everyMinutes(10, "sync", []() {
		Serial.println("scheduled job");
	});
}

void loop() {
	delay(1000);
}

Important notes

Important

Recurring scheduler jobs wait for valid wall-clock time. Set minValidUnixSeconds for your product so jobs do not run against an unset clock.

• Tempo uses POSIX timezone strings for DST-aware local conversion. Local timezone operations are serialized because the C runtime timezone is process-global.
• Latitude and longitude are optional, but both must be configured together before using stored-location sun APIs.
• sunCycleToday() lazily calculates and caches the current local date. Date-taking daylight and sunrise/sunset match APIs calculate against the supplied date.
• One-shot UTC schedules remain exact; recurring schedules evaluate in local time.
• Scheduler control calls made from an inline scheduler callback return SchedulerError::Busy rather than waiting on the scheduler service task itself.

Examples

Example	Description
BasicClock	Initialize Tempo and print UTC/local time.
NtpAndCallbacks	Configure NTP and sync callbacks.
LocalTimeAndDst	UTC/local conversion and DST checks.
SunMoon	Cached sun cycle and moon phase calls.
SchedulerBasic	Simple interval and daily jobs.
SchedulerCronAndDays	Cron expressions and weekday masks.
SchedulerSunCycle	Sunrise/sunset scheduled jobs.
SchedulerExecutionModes	Inline, worker pool, and dedicated-task modes.

Start with:

examples/BasicClock

Documentation

Detailed documentation is available in the docs/ folder.

Document	Description
docs/getting-started.md	Setup and first time flow.
docs/configuration.md	Config options and defaults.
docs/api.md	Public types and methods.
docs/examples.md	Example guide.
docs/troubleshooting.md	Common issues.

API overview

DateTime utcNow = tempo.nowUtc();
LocalDateTime localNow = tempo.nowLocal();
DateTime utc = tempo.toUtc(localNow);

TempoSunCycle sun = tempo.sunCycleToday();
TempoMoonPhase moon = tempo.moonPhase();

SchedulerJobOptions options;
options.name = "job";
options.mode = SchedulerJobMode::WorkerPool;
scheduler.schedule(TempoSchedule::dailyAt(8, 30), options, []() {});

Compatibility

Item	Support
Framework	Arduino ESP32
Platform	espressif32
Language	C++20
Filesystem	none
PSRAM	Used for selected internal buffers when available
Dependencies	none
Exceptions	Not used for public error handling
Status	0.1.0 release candidate

License

MIT - see LICENSE.md.

ZekStack

Part of the ZekStack ESP32 library stack.