# 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-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lunar Calendar Library for ESP-IDF

中国农历转换库 - 支持 ESP-IDF 框架

## 项目结构

```
lunar/
├── examples/           # 示例程序
├── include/           # 头文件
├── src/               # 源文件
├── docs/              # 文档
├── tools/             # 数据导入工具
├── CMakeLists.txt     # 组件构建配置
├── Kconfig            # 配置选项
├── idf_component.yml  # 组件描述文件
└── README.md          # 组件文档
```

## 快速开始

### 1. 作为独立项目运行示例

```bash
git clone https://gitee.com/NetADs/lunar.git
cd lunar
. $IDF_PATH/export.sh
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
```

### 2. 作为组件集成到其他项目

#### 方式 A：Git URL 依赖（推荐）

在其他项目的 `idf_component.yml` 中添加：

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

Component Manager 会自动下载到 `managed_components/` 目录。

#### 方式 B：Git Submodule

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

#### 方式 C：本地复制

```bash
git clone https://gitee.com/NetADs/lunar.git
cp -r lunar your_project/components/
```

## 使用方法

```c
#include "lunar.h"

lunar_info_t lunar;
int ret = solar_to_lunar(2026, 2, 17, 12, 0, &lunar);
if (ret == 0) {
    ESP_LOGI("LUNAR", "农历：%s年%s月%s", 
             lunar.year_gz, lunar.month_gz, lunar.day_gz);
    ESP_LOGI("LUNAR", "生肖：%s", lunar.zodiac);
}
```

## 功能特性

- ✅ 公历转农历（1900-2100 年）
- ✅ 干支四柱计算（年、月、日、时）
- ✅ 生肖计算
- ✅ 闰月支持
- ✅ 数据版本管理

## 支持平台

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

```bash
idf.py set-target esp32s3
idf.py build
```

## 文档

- [数据质量说明](docs/DATA_QUALITY.md)
- [HKO 数据更新指南](docs/HKO_AUTO_UPDATE.md)
- [HKO 数据使用指南](docs/HKO_DATA_GUIDE.md)

## 项目信息

- **仓库地址**：https://gitee.com/NetADs/lunar
- **组件版本**：1.0.0
- **ESP-IDF 要求**：>= 4.0
- **作者**：netad_work <netad_work@sina.com>
- **数据来源**：中国科学院紫金山天文台
- **许可证**：MIT