开发文档

1. 项目概述

本项目旨在开发一个基于 ESP32 微控制器、0.96寸OLED显示屏、DFPlayer Mini 语音模块和 WS2812B RGB LED 灯带的智能天气预警系统。系统能够实时获取天气数据和老黄历信息，并在特定高峰时段（6:00-9:00, 12:00-15:00, 17:00-19:00）通过多色LED灯进行物理可见的异常天气预警，同时提供按键触发的语音播报功能。

2. 硬件清单

以下是完成本项目所需的硬件组件：

序号	组件名称	规格/型号	数量	备注
1	主控板	ESP32 DevKitC 或其他ESP32开发板	1	带有Wi-Fi功能
2	显示屏	0.96寸OLED显示屏	1	I2C接口 (SSD1306芯片)
3	语音模块	DFPlayer Mini	1	带有SD卡槽
4	扬声器	8Ω 1W 小喇叭	1	配合DFPlayer Mini使用
5	LED灯带	WS2812B RGB LED (NeoPixel)	9颗以上	用于多色预警灯
6	按键	轻触开关	1	用于语音播报触发
7	存储卡	MicroSD卡	1	用于存储语音文件 (MP3格式)
8	供电	5V 2A 电源适配器	1	ESP32和WS2812B供电
9	附件	杜邦线、面包板、1000μF电容 (可选，用于WS2812B供电稳定)	若干

3. 硬件接线说明

本项目中，我们使用了ESP32的特定GPIO引脚来连接各个模块。请严格按照下表进行接线。

模块	模块引脚	ESP32 GPIO引脚	备注
OLED (I2C)	VCC	3.3V/5V	供电
	GND	GND	接地
	SCL	GPIO 22	I2C时钟线
	SDA	GPIO 21	I2C数据线
DFPlayer Mini	VCC	5V	供电
	GND	GND	接地
	RX	GPIO 17 (ESP32的RX2)	DFPlayer的RX接ESP32的TX2
	TX	GPIO 16 (ESP32的TX2)	DFPlayer的TX接ESP32的RX2
	SPK_1/SPK_2	扬声器	直接连接8Ω 1W扬声器
WS2812B LED	VCC	5V	注意：需独立供电，ESP32的5V引脚电流不足
	GND	GND	接地
	DIN	GPIO 13	数据输入
语音按键	一端	GPIO 34	内部上拉，接GND触发
	另一端	GND	接地

重要提示：
WS2812B供电： 9颗WS2812B全亮时电流较大，强烈建议为WS2812B灯带单独提供5V电源，并确保其GND与ESP32的GND共地。
DFPlayer Mini： DFPlayer Mini的RX/TX引脚直接连接ESP32的硬件串口2 (GPIO16/17) 以确保通信稳定。

4. 开发环境搭建

本项目基于Arduino IDE或VS Code + PlatformIO进行开发。

4.1 安装ESP32开发板支持

打开Arduino IDE，进入 文件 -> 首选项。

在“附加开发板管理器网址”中添加以下链接：

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

进入 工具 -> 开发板 -> 开发板管理器，搜索 esp32 并安装最新版本。
在 工具 -> 开发板 中选择ESP32型号（如 ESP32 Dev Module）。

4.2 安装所需库文件

本项目需要以下库文件。在Arduino IDE中，进入 工具 -> 管理库，搜索并安装：

库名称	作用
`U8g2`	驱动OLED显示屏
`DFRobotDFPlayerMini`	驱动DFPlayer Mini语音模块
`Adafruit NeoPixel`	驱动WS2812B RGB LED灯带
`ArduinoJson`	解析API返回的JSON数据
`HTTPClient`	用于发起HTTP请求获取天气和老黄历数据
`NTPClient`	用于网络时间同步

5. API密钥获取与配置

本项目需要两个外部API服务：

5.1 和风天气 (QWeather)

用于获取实时和逐小时天气预报（包括温度和降水概率）。

访问和风天气开发服务官网注册账号。
在控制台创建项目，获取 Public ID 和 Key。
使用 GeoAPI 或在控制台查询所在城市的 Location ID。

将获取到的信息替换源代码 (weather_alert_system.ino) 中的占位符：

cpp

const char* QWEATHER_KEY = "YOUR_QWEATHER_KEY";
const char* QWEATHER_LOCATION = "YOUR_CITY_LOCATION_ID";

5.2 老黄历 API (以聚合数据为例)

用于获取每日宜忌信息。

访问聚合数据官网或 Free-API 注册账号。
申请老黄历API服务，获取 AppKey。
将获取到的信息替换源代码中的占位符：
cpp
```
const char* ALMANAC_KEY = "YOUR_ALMANAC_KEY";
```

6. DFPlayer Mini 语音文件准备

DFPlayer Mini 通过播放SD卡中特定路径和名称的MP3文件来实现语音播报。

准备一张MicroSD卡，格式化为FAT32格式。
在SD卡根目录下创建名为 mp3 的文件夹。
将语音文件命名为 0001.mp3, 0002.mp3, 0003.mp3 等，并存入 mp3 文件夹。

本项目中，我们预设了以下语音文件内容：

文件名	对应预警级别	建议播报内容
`0001.mp3`	低温预警 (Level 1)	“请注意，有低温预警，请多穿衣物。”
`0002.mp3`	降雨预警 (Level 2)	“请注意，有降雨预警，请携带雨具。”
`0003.mp3`	双重预警 (Level 3)	“请注意，有低温和降雨双重预警，请做好防范。”
`0004.mp3`	无预警/老黄历播报	“当前无异常天气预警。”
`0005.mp3`	闹钟铃声	(自定义闹钟铃声)

7. 源代码配置与烧录

打开 weather_alert_system.ino 源代码文件。

修改 Wi-Fi 配置：

cpp

const char* ssid = "Wi-Fi名称";
const char* password = "Wi-Fi密码";

修改 API 密钥和 Location ID (参考 5. API密钥获取与配置)。
将ESP32开发板连接到电脑。
在Arduino IDE中，点击上传按钮，将代码烧录到ESP32中。

8. 核心功能实现逻辑

8.1 异常天气预警 (LED)

系统通过 WS2812B LED 实现物理可见的预警，共使用9颗LED，分为3组，每组3颗，对应3个高峰时段：

时段编号	时间范围	LED位置 (索引)	预警颜色定义
1	6:00 - 9:00	0, 1, 2	蓝色 (低温), 黄色 (降雨), 红色 (双重)
2	12:00 - 15:00	3, 4, 5	蓝色 (低温), 黄色 (降雨), 红色 (双重)
3	17:00 - 19:00	6, 7, 8	蓝色 (低温), 黄色 (降雨), 红色 (双重)

预警逻辑：

低温预警： 当预报温度低于 TEMP_LOW_THRESHOLD (默认为5°C) 时触发。
降雨预警： 当预报降水概率 (pop) 高于 RAIN_PROB_THRESHOLD (默认为50%) 时触发。
在当前时段内，如果触发预警，对应的3颗LED将亮起相应的颜色。

8.2 语音播报

用户按下 GPIO 34 连接的按键后，系统将根据当前时间点的天气预警级别，播放对应的语音文件（0001.mp3 - 0003.mp3）。如果当前无预警，则播放无预警提示（0004.mp3）。

8.3 OLED显示

OLED显示屏用于展示核心信息：

顶部： 实时时间 (NTP同步)。
左侧： 当前天气（温度、降水概率、天气描述）。
右侧： 老黄历信息（今日宜、忌）。
底部： 当前是否处于预警时段的提示。

8.4 参数可设置性

在源代码中，可以轻松修改以下参数以自定义预警逻辑：

cpp

// 预警阈值设置
const int TEMP_LOW_THRESHOLD = 5; // 低温预警阈值 (°C)
const int RAIN_PROB_THRESHOLD = 50; // 降雨概率预警阈值 (%)

// 闹钟设置 (在 checkAlarm() 函数中)
const int ALARM_HOUR = 7;
const int ALARM_MINUTE = 0;

9. 总结

本系统结合了物联网、嵌入式编程和多媒体交互技术，实现了对异常天气的智能监控和多感官预警。通过模块化的设计，可以根据需求进一步扩展功能，例如增加贪睡按键、通过Web界面设置闹钟和预警阈值等。

开发文档 ​

1. 项目概述 ​

2. 硬件清单 ​

3. 硬件接线说明 ​

4. 开发环境搭建 ​

4.1 安装ESP32开发板支持 ​

4.2 安装所需库文件 ​

5. API密钥获取与配置 ​

5.1 和风天气 (QWeather) ​

5.2 老黄历 API (以聚合数据为例) ​

6. DFPlayer Mini 语音文件准备 ​

7. 源代码配置与烧录 ​

8. 核心功能实现逻辑 ​

8.1 异常天气预警 (LED) ​

8.2 语音播报 ​

8.3 OLED显示 ​

8.4 参数可设置性 ​

9. 总结 ​