JkkSchedule

JkkSchedule is a lightweight schedule library for ESP32 and ESP-IDF projects.

It is packaged as a reusable ESP-IDF component and can be published through the ESP Component Registry.

It supports:

• day-of-week schedules
• date schedules
• relative interval schedules
• sunrise/sunset based schedules with per-device geo position
• persistent storage in NVS
• single shared master timer for efficient runtime behavior

Project Status

This library is production-oriented and extracted as a standalone component from a larger private project.

Inspiration and Rewrite Note

JkkSchedule was inspired by the original Espressif schedule component. This implementation is not a drop-in copy. It has been heavily refactored and corrected, including calendar handling fixes, sunrise/sunset behavior fixes, and a redesigned timer orchestration strategy.

License

Apache License 2.0. See LICENSE.

Requirements

• ESP-IDF 5.5, 6.0 (tested target range)
• FreeRTOS (provided by ESP-IDF)
• NVS (nvs_flash component)

Installation (ESP-IDF Component)

From the ESP Component Registry:

dependencies:
    MacWyznawca/JkkSchedule: "^1.0.0"

Or with the CLI:

idf.py add-dependency "MacWyznawca/JkkSchedule^1.0.0"

Manual options:

Copy this repository as a component:

• components/JkkSchedule

Or add it as a git submodule inside your project components directory.

In your project source:

#include "JkkSchedule.h"

Quick Start

jkk_schedules_handle_t *sched = jkk_schedule_init(
    NULL,
    "sched0",
    5212345,   // latitude * 100000
    2101234    // longitude * 100000
);

if (sched) {
    jkk_schedule_get_all(sched);
    jkk_schedule_run_all(sched, false);
}

Basic Usage Pattern

1. Create manager with jkk_schedule_init(...)
2. Load NVS with jkk_schedule_get_all(...)
3. Register callbacks (jkk_schedule_callback_all(...) or per schedule)
4. Create or edit schedules
5. Start runtime with jkk_schedule_run_all(...)

API Notes

• Coordinates are passed as int32_t in E5 format.
• Sunrise/sunset modes use coordinates from manager handle.
• If coordinates are invalid, sunrise/sunset scheduling falls back to fixed hour/minute behavior.

Sunrise/Sunset with Time Boundary

The SUNRISE and SUNSET schedule types support an optional time boundary. It is activated by setting valid hours (0–23) and minutes (0–59) fields in the trigger configuration. When both fields are out of range (default), the schedule fires purely at the astronomical time.

Selection rule:

Type	Behaviour with boundary	Effect
SUNRISE	min(sunrise, hours:minutes)	No later than the given time
SUNSET	max(sunset, hours:minutes)	No earlier than the given time

Example — winter evenings: To prevent home lighting from switching to warm-white mode too early in winter (when sunset can be as early as 15:30), set type SUNSET with boundary 18:00. The schedule fires at 18:00 in winter and at sunset in summer (when sunset is after 18:00):

jkk_schedule_config_t cfg = {
    .name = "evening_warm_white",
    .trigger = {
        .type    = JKK_SCHEDULE_TYPE_DAYS_OF_WEEK_SUNSET,
        .hours   = 18,   // no earlier than 18:00
        .minutes = 0,
        .day.repeat_days = JKK_SCHEDULE_DAY_EVERYDAY,
    },
    .trigger_cb = evening_cb,
};

Analogously for SUNRISE — hours:minutes acts as an upper limit (e.g. "wake-up no later than 07:30, even if sunrise is later in winter").

If the geographic coordinates are not set or are invalid, the library uses only the fixed time — hours:minutes then behaves as a standard time-of-day trigger.

Examples

See:

• examples/esp-idf/basic
• examples/esp-idf/sun_events
• examples/arduino/basic_not_tested

Arduino Compatibility

The library is designed for ESP-IDF components.

An experimental Arduino example is included in:

• examples/arduino/basic_not_tested

Status:

• not tested
• provided as a starting point only

It can be used from Arduino only under these conditions:

• target platform is ESP32 (Arduino-ESP32)
• project is built with ESP-IDF integration (for example Arduino as ESP-IDF component)
• nvs_flash is initialized before schedule loading
• standard C time functions are available and SNTP/timezone are configured for sunrise/sunset accuracy

For plain Arduino Library Manager style usage (without ESP-IDF component model), adaptation is required because this code depends on:

• esp_err.h
• FreeRTOS timers
• ESP-IDF NVS API

The repository now also provides:

• library.properties
• src/JkkSchedule.h forwarding header for Arduino-style include discovery

Repository Layout

• include/JkkSchedule.h - public API
• src/JkkSchedule.c - scheduler core
• src/JkkScheduleNvs.c - NVS persistence layer
• src/JkkScheduleInternal.h - internal declarations
• examples/ - reference integration projects

Acknowledgements

• Espressif Systems for publishing the original schedule concept.
• Contributors and users validating behavior on real devices.