# Lunar

**Repository Path**: NetADs/lunar

## Basic Information

- **Project Name**: Lunar
- **Description**: 农历及干支四柱的计算。
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lunar Calendar Library for ESP-IDF

Chinese Lunar Calendar Conversion Library for ESP-IDF.

## Features

- Solar to lunar calendar conversion (1900-2099)
- Ganzhi four-pillar calculation (year, month, day, hour)
- Chinese zodiac calculation
- Leap month support
- Data version management and runtime updates
- Data integrity verification

## Quick Start

### Install

Add to your project's `idf_component.yml`:

```yaml
dependencies:
  lunar:
    git: https://gitee.com/NetADs/lunar.git
```

Or as a submodule:

```bash
git submodule add https://gitee.com/NetADs/lunar.git components/lunar
```

### Usage

```c
#include "lunar.h"

int main(void)
{
    lunar_info_t info;
    int ret = solar_to_lunar(2026, 2, 17, 12, &info);
    if (ret == 0) {
        printf("年柱: %s  月柱: %s  日柱: %s  时柱: %s\n",
               info.year_gz, info.month_gz, info.day_gz, info.hour_gz);
        printf("生肖: %s\n", info.zodiac);
        printf("农历: %s年%d月%d日 %s\n",
               info.year_gz, info.month, info.day,
               info.is_leap ? "(闰月)" : "");
    }
    return 0;
}
```

### Validate a Known Date

```c
#include "lunar.h"

lunar_info_t info;
solar_to_lunar(2026, 2, 17, 10, &info);
assert(info.year   == 2026);
assert(info.month  == 1);
assert(info.day    == 1);
assert(!info.is_leap);
assert(strcmp(info.year_gz, "丙午") == 0);
assert(strcmp(info.zodiac,  "马") == 0);
```

### Import Custom Data

```c
#include "lunar_sync.h"

lunar_year_data_t custom[] = {
    {2100, 20, 0, 0x04bd8},
};
lunar_sync_import_data(custom, 1, 2100);
```

### Verify Data Integrity

```c
#include "lunar_data.h"

lunar_data_verify_result_t res = lunar_data_verify_checksum(2026);
if (res.is_valid) {
    printf("Data OK\n");
}
```

## API Reference

### Core (lunar.h)

| Function | Description |
|----------|-------------|
| `solar_to_lunar(year, month, day, hour, out)` | Convert solar date to lunar date with four pillars |

### Sync (lunar_sync.h)

| Function | Description |
|----------|-------------|
| `lunar_sync_get_status(status)` | Get current sync status |
| `lunar_sync_reload_internal()` | Reload built-in data |
| `lunar_sync_import_data(data, count, year_from)` | Import external year data |
| `lunar_sync_print_info()` | Print sync status |

### Data (lunar_data.h)

| Function | Description |
|----------|-------------|
| `lunar_data_get_version()` | Get data version info |
| `lunar_data_check_year_range(year)` | Check if year is supported |
| `lunar_data_verify_checksum(year)` | Verify data integrity for a year |
| `lunar_data_verify_range(start, end, years, count)` | Batch verify year range |
| `lunar_data_reset(from, count)` | Reset data to defaults |
| `lunar_data_print_info()` | Print version info |
| `lunar_data_get_quality_report(total, verified, date)` | Get quality score (0-100) |

## Data Sources

Built-in data is derived from the Purple Mountain Observatory, Chinese Academy of Sciences.
Coverage: 1900-2099 (200 years).

## Target Platforms

- ESP32 / ESP32-S2 / ESP32-S3 / ESP32-C3 / ESP32-C6

## Requirements

- ESP-IDF >= 4.0

## License

MIT