WeWeather - 微天气

一个基于 ESP8266 的智能天气显示设备，使用电子墨水屏显示实时天气、温湿度和时间信息。

📋 目录

• 项目简介
• 功能特性
• 硬件要求
• 软件依赖
• 快速开始
• 配置说明
• 项目结构
• 使用说明
• 开发指南
• 常见问题
• 贡献指南
• 许可证

🌟 项目简介

WeWeather（微天气）是一个低功耗的智能天气显示设备，采用 ESP8266 微控制器和 2.9 英寸电子墨水屏，能够显示：

• 📅 实时日期和时间
• 🌤️ 当地天气信息（温度、湿度、天气状况）
• 🌡️ 室内温湿度（通过 SHT40 传感器）
• 🔋 电池电量状态
• ⏰ RTC 实时时钟支持

该项目采用深度睡眠模式，实现超低功耗运行，适合电池供电的长期使用场景。

✨ 功能特性

核心功能

• 实时天气显示：通过高德地图 API 获取天气数据
• 室内环境监测：SHT40 传感器测量室内温湿度
• 精准时间同步：支持 NTP 网络时间同步和 BM8563 RTC 硬件时钟
• 低功耗设计：深度睡眠模式，定时唤醒更新
• 电池监控：实时显示电池电量百分比
• 数据缓存：天气数据本地缓存，减少网络请求

配置功能

• 双模式配置：
  • 🌐 Web 配置界面（AP 热点模式）
  • 💻 串口命令行配置
• 统一配置管理：WiFi、API、系统参数统一管理
• 配置持久化：配置保存到 EEPROM，断电不丢失

显示功能

• 电子墨水屏：2.9 英寸黑白屏，阳光下可读
• 自定义字体：七段数码管风格时间显示
• 天气图标：直观的天气符号显示
• 低功耗刷新：仅在数据更新时刷新屏幕

🔧 硬件要求

必需硬件

组件	型号/规格	说明
主控芯片	ESP8266 (NodeMCU)	WiFi 微控制器
显示屏	GDEY029T94	2.9 英寸电子墨水屏 (128×296)
RTC 时钟	BM8563	I2C 实时时钟模块
温湿度传感器	SHT40	I2C 高精度温湿度传感器
电源	3.7V 锂电池	推荐容量 ≥ 1000mAh

引脚连接

I2C 设备 (BM8563 & SHT40)

SDA -> GPIO-2  (D4)
SCL -> GPIO-12 (D6)

电子墨水屏 (SPI)

CS   -> D8  (GPIO-15)
DC   -> D2  (GPIO-4)
RST  -> D0  (GPIO-16)
BUSY -> D1  (GPIO-5)

配置模式触发

RXD -> GPIO-3  (拉低进入配置模式)

📦 软件依赖

开发环境

• PlatformIO - 推荐使用 VSCode + PlatformIO 插件
• Arduino Framework for ESP8266

库依赖

项目使用 PlatformIO 自动管理依赖，主要库包括：

[env:nodemcu]
platform = espressif8266
board = nodemcu
framework = arduino
lib_deps =
    bblanchon/ArduinoJson
    zinggjm/GxEPD2

内置库

• ESP8266WiFi - WiFi 连接管理
• ESP8266HTTPClient - HTTP 请求
• ESP8266WebServer - Web 配置服务器
• Wire - I2C 通信
• EEPROM - 配置存储

🚀 快速开始

1. 克隆项目

git clone https://github.com/yourusername/WeWeather.git
cd WeWeather

2. 配置文件

复制配置模板并修改：

cp config.h.example config.h

编辑 config.h 文件，配置以下参数：

// WiFi 配置
#define DEFAULT_WIFI_SSID "Your_WiFi_SSID"
#define DEFAULT_WIFI_PASSWORD "Your_WiFi_Password"

// 高德地图 API
#define DEFAULT_AMAP_API_KEY "your_amap_api_key_here"
#define DEFAULT_CITY_CODE "110108"  // 城市代码

// 可选：自定义 MAC 地址
#define DEFAULT_MAC_ADDRESS "AA:BB:CC:DD:EE:FF"
#define ENABLE_CUSTOM_MAC true

3. 编译上传

使用 PlatformIO 编译并上传：

# 编译
pio run

# 上传到设备
pio run --target upload

# 查看串口输出
pio device monitor

4. 首次运行

设备首次启动后会自动连接 WiFi 并同步时间，然后显示天气信息。

⚙️ 配置说明

进入配置模式

将 RXD 引脚（GPIO-3）拉低后启动设备即可进入配置模式。

操作步骤：

1. 将 RXD 引脚（GPIO-3）连接到 GND
2. 重启设备或上电
3. 设备检测到 RXD 被拉低，自动进入配置模式
4. 屏幕会显示配置信息（AP 名称和 IP 地址）

Web 配置界面

1. 设备进入配置模式后会创建名为 WeWeather 的 WiFi 热点
2. 连接该热点（无密码）
3. 浏览器访问 http://192.168.4.1
4. 在 Web 界面配置 WiFi 和 API 参数

串口配置

通过串口（波特率 74880）发送命令：

help                    - 显示帮助信息
show                    - 显示当前配置
set <key> <value>       - 设置并保存配置值
  可用的键: ssid, password, apikey, citycode, mac
clear                   - 清除所有配置
exit                    - 退出配置模式（重启系统）

命令示例：

set ssid MyWiFi
set password myPassword
set apikey your_amap_api_key
set citycode 110108
set mac AA:BB:CC:DD:EE:FF

获取高德地图 API Key

1. 访问 高德开放平台
2. 注册并创建应用
3. 获取 Web 服务 API Key
4. 查询城市代码：高德城市编码表

📁 项目结构

WeWeather/
├── src/
│   └── main.cpp                    # 主程序入口
├── lib/                            # 自定义库
│   ├── BatteryMonitor/            # 电池监控
│   ├── BM8563/                    # RTC 时钟驱动
│   ├── ConfigManager/             # 配置管理
│   ├── Fonts/                     # 自定义字体
│   ├── GDEY029T94/                # 电子墨水屏驱动
│   ├── LogManager/                # 日志管理
│   ├── SerialConfigManager/       # 串口配置
│   ├── SHT40/                     # 温湿度传感器
│   ├── TimeManager/               # 时间管理
│   ├── UnifiedConfigManager/      # 统一配置管理
│   ├── WeatherManager/            # 天气数据管理
│   ├── WebConfigManager/          # Web 配置服务
│   └── WiFiManager/               # WiFi 连接管理
├── include/                        # 头文件目录
├── test/                          # 测试文件
├── platformio.ini                 # PlatformIO 配置
├── config.h.example               # 配置文件模板
├── requirements.md                # 需求文档
└── README.md                      # 本文件

核心模块说明

模块	功能	文档
BatteryMonitor	电池电压和电量监测	README
BM8563	RTC 实时时钟驱动	README
GDEY029T94	电子墨水屏显示驱动	README
SHT40	温湿度传感器驱动	README
TimeManager	时间同步和管理	README
WeatherManager	天气数据获取和缓存	README
WiFiManager	WiFi 连接管理	README
UnifiedConfigManager	统一配置管理	README

📖 使用说明

正常运行模式

设备正常运行时的工作流程：

1. 唤醒：从深度睡眠中唤醒（RTC 定时器触发）
2. 初始化：初始化传感器、显示屏、RTC
3. 数据更新：
   • 检查天气数据是否过期（默认 30 分钟）
   • 如需更新：连接 WiFi → 同步 NTP 时间 → 获取天气数据
   • 如不需要：使用缓存数据
4. 传感器读取：读取 SHT40 温湿度和电池电量
5. 显示更新：在电子墨水屏上显示所有信息
6. 睡眠：进入深度睡眠（默认 60 秒）

功耗优化

• 深度睡眠：设备大部分时间处于深度睡眠状态（功耗 < 1mA）
• 快速唤醒：唤醒后快速完成任务并重新睡眠
• 数据缓存：减少 WiFi 连接次数，降低功耗
• 电子墨水屏：仅在更新时消耗电量，显示时零功耗

电池续航

以 1000mAh 电池为例：

• 深度睡眠功耗：~0.5mA
• 唤醒更新功耗：~80mA（持续 5-10 秒）
• 预计续航：约 30-60 天（取决于更新频率）

🛠️ 开发指南

添加新功能

1. 在 lib/ 目录下创建新模块
2. 编写模块代码和 README 文档
3. 在 src/main.cpp 中集成模块
4. 更新配置文件（如需要）

调试技巧

1. 串口日志：使用 LogManager 输出调试信息

   LOG_INFO("Debug message");
   LOG_ERROR("Error message");

2. 禁用深度睡眠：临时注释 goToDeepSleep() 调用

3. 查看配置：串口发送 show 命令

自定义显示

修改 GDEY029T94 库中的显示布局：

// 在 GDEY029T94.cpp 中自定义显示内容
void GDEY029T94::showTimeDisplay(...) {
    // 自定义显示逻辑
}

添加新字体

1. 使用 truetype2gfx 转换字体
2. 将生成的 .h 文件放入 lib/Fonts/
3. 在代码中引用新字体

❓ 常见问题

Q: 设备无法连接 WiFi？

A: 检查以下几点：

• WiFi SSID 和密码是否正确
• 路由器是否支持 2.4GHz（ESP8266 不支持 5GHz）
• 信号强度是否足够
• 尝试重置配置：串口发送 clear

Q: 天气数据不更新？

A: 可能原因：

• 高德地图 API Key 无效或超出配额
• 城市代码错误
• 网络连接问题
• 检查串口日志获取详细错误信息

Q: 时间显示不准确？

A: 解决方法：

• 确保 WiFi 连接成功，NTP 时间同步需要网络
• 检查 RTC 电池是否正常
• 手动同步时间：重启设备并连接 WiFi

Q: 电子墨水屏显示异常？

A: 尝试：

• 检查 SPI 引脚连接是否正确
• 重启设备
• 检查电源电压是否稳定（建议 ≥ 3.3V）

Q: 如何延长电池续航？

A: 优化建议：

• 增加深度睡眠时间（修改 config.h 中的 DEEP_SLEEP_SECONDS）
• 增加天气更新间隔（修改 WEATHER_UPDATE_INTERVAL）
• 使用更大容量的电池

Q: 如何退出配置模式？

A: 有两种方式退出配置模式：

• 方式一：串口发送 exit 命令，设备将自动重启
• 方式二：断开 RXD 引脚的拉低连接，然后手动重启设备

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

贡献流程

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

代码规范

• 使用清晰的变量和函数命名
• 添加必要的注释（中文或英文）
• 遵循现有代码风格
• 为新功能编写 README 文档

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

• PlatformIO - 优秀的嵌入式开发平台
• Arduino - Arduino 框架
• 高德地图 - 天气数据 API
• GxEPD2 - 电子墨水屏驱动库

📞 联系方式

• 项目主页：GitHub Repository
• 问题反馈：Issues

---

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！

Made with ❤️ by WeWeather Team