esp-rainmaker/components/esp_daylight

ESP Daylight Component

A standalone C library for calculating sunrise and sunset times using NOAA Solar Calculator equations. This component provides accurate solar calculations for any location and date, designed for integration with ESP-IDF projects.

Features

• Accurate NOAA calculations: Uses proven NOAA Solar Calculator equations
• Global coverage: Works for any location worldwide (handles polar regions)
• Lightweight: Minimal memory footprint and dependencies
• ESP-IDF ready: Designed for embedded systems
• Time zone agnostic: Returns UTC timestamps for easy conversion

API Reference

Core Functions

bool esp_daylight_calc_sunrise_sunset_utc(int year, int month, int day,
                                          double latitude, double longitude,
                                          time_t *sunrise_utc, time_t *sunset_utc);

Calculate sunrise and sunset times for a specific date and location.

Parameters:

• year: Year (e.g., 2024)
• month: Month (1-12)
• day: Day of month (1-31)
• latitude: Latitude in decimal degrees (-90 to +90, positive North)
• longitude: Longitude in decimal degrees (-180 to +180, positive East)
• sunrise_utc: Output sunrise time as UTC timestamp
• sunset_utc: Output sunset time as UTC timestamp

Returns: true on success, false if sun doesn't rise/set (polar regions)

Helper Functions

time_t esp_daylight_apply_offset(time_t base_time, int offset_minutes);

Apply time offset to a base timestamp.

bool esp_daylight_get_sunrise_today(const esp_daylight_location_t *location, time_t *sunrise_utc);
bool esp_daylight_get_sunset_today(const esp_daylight_location_t *location, time_t *sunset_utc);

Get sunrise/sunset for current date at given location.

Usage Example

#include "esp_daylight.h"

void calculate_solar_times(void) {
    time_t sunrise_utc, sunset_utc;

    // Calculate for Pune, India on August 29, 2025
    bool ok = esp_daylight_calc_sunrise_sunset_utc(
        2025, 8, 29,           // Date
        18.5204, 73.8567,      // Pune coordinates
        &sunrise_utc, &sunset_utc
    );

    if (ok) {
        // Apply offset: 30 minutes before sunset
        time_t light_on_time = esp_daylight_apply_offset(sunset_utc, -30);

        struct tm *tm_info = gmtime(&light_on_time);
        printf("Turn on light at: %02d:%02d:%02d UTC\n",
               tm_info->tm_hour, tm_info->tm_min, tm_info->tm_sec);
    } else {
        printf("No sunrise/sunset for this location and date\n");
    }
}

Location Coordinates

Popular Cities

City	Latitude	Longitude
New York	40.7128	-74.0060
London	51.5074	-0.1278
Pune	18.5204	73.8567
Shanghai	31.2304	121.4737
Sydney	-33.8688	151.2093

Coordinate Format

• Latitude: -90 to +90 degrees (positive = North, negative = South)
• Longitude: -180 to +180 degrees (positive = East, negative = West)

Integration with ESP Schedule

This component integrates seamlessly with ESP Schedule for solar-based scheduling:

esp_schedule_config_t schedule_config = {
    .name = "sunset_light",
    .trigger.type = ESP_SCHEDULE_TYPE_SUNSET,
    .trigger.solar.latitude = 18.5204,
    .trigger.solar.longitude = 73.8567,
    .trigger.solar.offset_minutes = -30,  // 30 min before sunset
    .trigger.solar.repeat_days = ESP_SCHEDULE_DAY_EVERYDAY,
    .trigger_cb = light_control_callback,
};

Algorithm Details

The component implements the NOAA Solar Calculator algorithm with:

• Zenith angle: 90.833° (accounts for atmospheric refraction)
• Precision: Typically accurate to within 1-2 minutes
• Edge cases: Handles polar day/night conditions gracefully

Dependencies

• ESP-IDF (esp_common)
• Standard C math library (-lm)

Component Structure

esp_daylight/
├── CMakeLists.txt
├── include/
│   └── esp_daylight.h
├── src/
│   └── esp_daylight.c
└── README.md