基于 ESP32-C3 的智能爬宠饲养箱昼夜温控系统
SunBox 是一个为爬宠 / 动物饲养箱设计的嵌入式温控固件。它通过 AHT20 传感器实时读取温湿度,按昼夜时间表自动控制加热灯与 UVB 灯,并暴露一套完整的 HTTP API,让你可以在手机或电脑上查询状态、调整配置、手动操控——无需打开箱盖。
| 特性 | 说明 |
|---|---|
| 🌗 昼夜双模式 | 按时间段自动切换白天 / 夜间模式,各模式有独立的温度阈值 |
| 🎭 角色驱动温控 | 每个继电器在每个模式下可配置为 常闭 / 常亮 / 加温,灵活适配不同物种 |
| 🌡️ 滞回控制 | 加温采用滞回区间(min/max),避免继电器频繁抖动,延长寿命 |
| 🔌 总开关 + 手动覆盖 | 一键全断电锁定;手动切继电器进入 60 秒覆盖期,到期自动恢复温控 |
| 📡 远程引脚映射 | 继电器引脚可经 API 在线配置并持久化,无需重新烧录固件 |
| 🛡️ 安全默认 | 传感器故障 / 温度不可用时加热自动关闭;NTP 未同步默认白天模式 |
| 📊 完整状态查询 | 一次 /api/status 拿到温度、湿度、继电器状态、配置、引脚映射 |
| 组件 | 型号 / 规格 |
|---|---|
| 主控 | ESP32-C3(原生 USB,Arduino 兼容) |
| 温湿度传感器 | AHT20(I2C,3.3V) |
| 继电器模块 | 4 路低电平有效继电器板 |
| 加热灯 | 白炽 / 陶瓷加热灯(经继电器 1) |
| UVB 灯 | 爬宠专用 UVB 灯(经继电器 3) |
| 功能 | GPIO | 说明 |
|---|---|---|
| AHT20 SDA | IO1 | I2C 数据线(固定) |
| AHT20 SCL | IO0 | I2C 时钟线(固定) |
| 继电器 1 · 白天加热 | IO3 | 可经 /api/pins 配置 |
| 继电器 2 · 夜间加热 | IO4 | 可经 /api/pins 配置 |
| 继电器 3 · UVB 灯 | IO5 | 可经 /api/pins 配置 |
| 继电器 4 · 预留 | IO7 | 可经 /api/pins 配置 |
⚠️ ESP32-C3 引脚提示:继电器引脚仅允许{2,3,4,5,6,7,8,9,10},已自动排除 I2C(0/1)、SPI flash(11-17)、USB(18/19)、UART(20/21)。
# 用 arduino-cli 编译烧录(或直接用 Arduino IDE)
arduino-cli compile --fqbn esp32:esp32:esp32c3 SunBox.ino
arduino-cli upload -p COM3 --fqbn esp32:esp32:esp32c3 SunBox.ino烧录前必做:
- 安装依赖库:
arduino-cli lib install "Adafruit AHTX0" - 修改
SunBox.ino顶部的 WiFi 凭据:const char* WIFI_SSID = "你的WiFi名"; const char* WIFI_PASSWORD = "你的WiFi密码";
- 启用 USB CDC(ESP32-C3 原生 USB 板必须):
- Arduino IDE:
Tools → USB CDC On Boot → Enabled - 否则串口监视器收不到任何输出
- Arduino IDE:
- 串口监视器波特率:115200
烧录后,串口会输出设备获取到的 IP:
WiFi connected.
IP address: 192.168.31.125
HTTP API server started.
curl http://192.168.31.125/api/status{
"mode": "day",
"temperatureC": 30.42,
"humidity": 61.15,
"wifiConnected": true,
"sensorReady": true,
"powerEnabled": true,
"relays": { "dayHeat": false, "nightHeat": false, "uvb": true, "relay4": false },
"rules": { "dayStart": "08:00", "nightStart": "20:00", "dayMinTemp": 30.0, "dayMaxTemp": 32.0, "..." : "..." }
}| 方法 | 端点 | 作用 |
|---|---|---|
GET |
/api/status |
查询完整运行状态(温度、继电器、配置) |
GET |
/api/rules |
查询昼夜规则(时间 / 温度阈值 / 角色) |
POST |
/api/rules |
更新昼夜规则 |
POST |
/api/config/reset |
重置规则为出厂默认 |
GET |
/api/pins |
查询继电器引脚映射 |
POST |
/api/pins |
配置继电器引脚映射(持久化) |
POST |
/api/power |
总开关(on/off,关时全断并锁定) |
POST |
/api/relays |
手动切换单个继电器(60 秒覆盖期) |
每个继电器在每个模式下有三种可选角色:
| 角色 | 值 | 行为 |
|---|---|---|
off |
0 |
常闭 |
on |
1 |
常亮 |
heat |
2 |
加温:低于 minTemp 开,高于 maxTemp 关,区间内保持(滞回) |
默认配置(可直接用,或按物种需求自定义):
graph LR
subgraph 白天模式 08:00-20:00
DH1[白天加热 heat] --- NH1[夜间加热 OFF] --- UV1[UVB ON] --- RS1[预留 OFF]
end
subgraph 夜间模式 20:00-08:00
DH2[白天加热 OFF] --- NH2[夜间加热 heat] --- UV2[UVB OFF] --- RS2[预留 OFF]
end
完整 API 契约(字段、校验、示例)见 API.md。
# 假设设备 IP 为 192.168.31.125
# 配置:白天 7:00 开始,夜间 19:00 开始,白天加热到 28-31℃
curl -X POST http://192.168.31.125/api/rules \
-H "Content-Type: application/json" \
-d '{"dayStart":"07:00","nightStart":"19:00","dayMinTemp":28,"dayMaxTemp":31,"dayHeatRole":2,"dayNightHeatRole":0,"dayUvbRole":1,"dayReservedRole":0,"nightMinTemp":24,"nightMaxTemp":27,"nightHeatRole":0,"nightNightHeatRole":2,"nightUvbRole":0,"nightReservedRole":0}'
# 紧急断电(所有继电器立即断开并锁定)
curl -X POST http://192.168.31.125/api/power -H "Content-Type: application/json" -d '{"on":false}'
# 手动临时打开 UVB(60 秒后自动回到温控)
curl -X POST http://192.168.31.125/api/relays -H "Content-Type: application/json" -d '{"relay":"uvb","on":true}'flowchart TD
S[AHT20 传感器] -->|温湿度| R[采样调度 1s]
N[NTP 时间] -->|昼夜判定| M[模式 day/night]
M --> C[controlTemperature]
R --> C
P{powerEnabled?} -->|否| OFF[全断并锁定]
P -->|是| O{手动覆盖期?}
O -->|是| MAN[手动值]
O -->|否| C
C -->|按角色+温度| RL1[继电器1 白天加热]
C --> RL2[继电器2 夜间加热]
C --> RL3[继电器3 UVB]
C --> RL4[继电器4 预留]
API[HTTP API :80] -.读取/配置.-> C
API -.状态.-> ST[/api/status]
控制优先级(高 → 低):
- 🔴 总开关关 → 所有继电器断开并锁定
- 🟡 手动覆盖期 → 使用手动设定的状态
- 🟢 自动模式规则 → 按角色 + 温度阈值自动控制
SunBox/
├── SunBox.ino # 固件主程序(单文件,分区清晰)
├── API.md # HTTP API 完整契约文档
├── AGENTS.md # AI 编码助手指南与架构约定
└── README.md # 本文档
- 平台:ESP32-C3(Arduino 框架)
- 语言:C++(Arduino 风格)
- 传感器库:
Adafruit AHTX0 - 网络:
WiFi/WebServer/Preferences(ESP32 内置) - 时间同步:NTP(
pool.ntp.org+ntp.aliyun.com,GMT+8) - JSON:自实现轻量解析(无 ArduinoJson 依赖)
本项目仅供个人 / 学习使用。
给爬宠一个舒适的家 🦎🐍🐢