分布式空调控制系统 (Distributed Air Controller)

一个基于ESP32的分布式温度控制系统，通过TCP通信协调多个客户端设备，实现智能温度场管理。

📋 项目概述

本项目实现了一个分布式温度控制系统，包含：

ESP32主控服务器（带温度传感器和红外发射器）
多个TCP客户端设备
Web管理界面
智能温度控制算法

🎯 核心功能

WiFi热点管理 - 使用WiFiManager库创建热点 ND_ESP_TEST
TCP服务器 - 端口8848，处理JSON格式的温度数据交换
多客户端管理 - 支持多个设备同时连接和独立控制
智能温度控制 - 基于温度等级的自动调节算法
Web管理界面 - 美观的控制面板，支持参数设置和系统开关
本地传感器 - HTU21D温度湿度传感器
红外控制 - IR发射器用于控制空调设备

🏗️ 系统架构

整体架构图

┌─────────────────────────────────────────────────────────────┐
│                    ESP32 主控服务器                           │
├─────────────────────────────────────────────────────────────┤
│  应用层 (Application Layer)                                   │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │           ApplicationController                         │ │
│  │         (组合逻辑和业务协调)                              │ │
│  └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│  业务层 (Business Layer)                                     │
│  ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│  │ ClientManager│ SensorManager│ WebServerMgr│ Settings     │ │
│  │ (客户端管理)  │ (传感器管理)  │ (Web服务)   │ (配置管理)   │ │
│  └─────────────┴─────────────┴─────────────┴─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│  通信层 (Communication Layer)                                │
│  ┌─────────────────┬─────────────────┬─────────────────────┐ │
│  │ TCPServerManager│ MessageHandler  │ ProtocolPacketMaker │ │
│  │ (TCP连接管理)    │ (消息处理)      │ (协议包处理)         │ │
│  └─────────────────┴─────────────────┴─────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│  硬件层 (Hardware Layer)                                     │
│  ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│  │ WiFi模块    │ HTU21D      │ IR发射器     │ GPIO接口     │ │
│  │ (网络通信)   │ (温湿度)     │ (红外控制)   │ (硬件控制)   │ │
│  └─────────────┴─────────────┴─────────────┴─────────────┘ │
└─────────────────────────────────────────────────────────────┘
                               │
                ┌──────────────┼──────────────┐
                │              │              │
        ┌───────▼──────┐ ┌─────▼─────┐ ┌─────▼─────┐
        │ TCP客户端A    │ │ TCP客户端B │ │ TCP客户端C │
        │ (空调设备)    │ │ (风扇设备) │ │ (加热器)   │
        └─────────────┘ └───────────┘ └───────────┘

组件职责分离

应用层 (Application Layer)

ApplicationController - 组合逻辑和业务协调中心
- 处理Web界面触发的操作
- 协调各组件间的交互
- 管理客户端连接映射
- 实现智能温度控制算法

业务层 (Business Layer)

ClientManager - 客户端设备管理
SensorManager - 本地传感器数据管理
WebServerManager - Web界面服务
Settings - 系统配置和参数管理

通信层 (Communication Layer)

TCPServerManager - 纯粹的TCP连接和数据传输
MessageHandler - 消息序列化和反序列化
ProtocolPacketMaker - 协议包编码和解码

📁 目录结构

distributed-air-controller/
├── src/                          # 源代码目录
│   ├── main.cpp                  # 程序入口点
│   │
│   ├── 应用层/
│   │   ├── ApplicationController.h      # 应用逻辑控制器
│   │   └── ApplicationController.cpp
│   │
│   ├── 业务层/
│   │   ├── ClientManager.h             # 客户端管理
│   │   ├── ClientManager.cpp
│   │   ├── SensorManager.h             # 传感器管理
│   │   ├── SensorManager.cpp
│   │   ├── WebServerManager.h          # Web服务器管理
│   │   ├── WebServerManager.cpp
│   │   ├── Settings.h                  # 系统设置
│   │   └── Settings.cpp
│   │
│   ├── 通信层/
│   │   ├── TCPServerManager.h          # TCP服务器(解耦版)
│   │   ├── TCPServerManager.cpp
│   │   ├── MessageHandler.h            # 消息处理器
│   │   ├── MessageHandler.cpp
│   │   ├── MessageTypes.h              # 消息类型定义
│   │   ├── ProtocolPacketMaker.h       # 协议包制造器
│   │   └── ProtocolPacketMaker.cpp
│   │
├── data/                         # Web界面资源 ⚠️ 必须上传！
│   ├── index.html               # 主页面
│   └── app.js                   # 前端JavaScript
│
├── test/                        # 测试和示例
│   ├── README.md                # 测试说明
│   ├── tcp_server_usage_example.cpp    # TCP服务器使用示例
│   ├── protocol_packet_usage_example.cpp # 协议包使用示例
│   ├── message_examples.cpp            # 消息格式示例
│   └── test_client.py                  # Python测试客户端
│
├── docs/                        # 文档目录
│   ├── DEPLOYMENT_GUIDE.md      # 部署指南
│   ├── USAGE_GUIDE.md           # 使用指南
│   ├── PROJECT_SUMMARY.md       # 项目总结
│   ├── PROTOCOL_REFACTOR_SUMMARY.md # 协议重构说明
│   └── DELETE_OBSOLETE_FILES.md # 清理指南
│
├── platformio.ini               # PlatformIO配置
└── README.md                    # 项目说明(本文件)

🔧 硬件配置

GPIO引脚分配

// HTU21D 温湿度传感器
#define SDA_PIN 20    // I2C数据线
#define SCL_PIN 21    // I2C时钟线

// IR红外发射器  
#define IR_TX_PIN 4   // 红外发射引脚

网络配置

// WiFi热点设置
const char* AP_SSID = "ND_ESP_TEST";
const char* AP_PASSWORD = "1234567890";

// 服务端口
const int TCP_PORT = 8848;        // TCP服务器端口
const int WEB_PORT = 80;          // Web服务器端口

📡 通信协议

JSON消息格式

客户端上报温度

{
    "messageType": "report",
    "sourceMAC": "00-11-22-33-44-55",
    "temperature": 25.5,
    "humidity": 60.0,
    "timestamp": 1625123456
}

服务器控制命令

{
    "messageType": "command", 
    "sourceMAC": "SERVER",
    "targetMAC": "00-11-22-33-44-55",
    "command": "set_temperature",
    "value": 24.0,
    "timestamp": 1625123456
}

心跳检测

{
    "messageType": "heartbeat",
    "sourceMAC": "00-11-22-33-44-55", 
    "status": "online",
    "timestamp": 1625123456
}

协议包结构

┌─────────────┬─────────────┬─────────────┬─────────────┐
│ Header(4B)  │ Length(4B)  │ JSON Data   │ Checksum(4B)│
├─────────────┼─────────────┼─────────────┼─────────────┤
│ 0xAABBCCDD  │ Data Length │ JSON String │ CRC32       │
└─────────────┴─────────────┴─────────────┴─────────────┘

🌐 Web管理界面

功能特性

现代化界面 - 响应式设计，支持桌面和移动端
实时数据 - 温度数据实时显示和更新
参数设置 - 4个温度等级的配置界面
系统控制 - 系统开关，启用/禁用自动控制
客户端监控 - 显示所有连接的客户端状态

访问方式

连接WiFi热点 ND_ESP_TEST (密码: 1234567890)
浏览器访问 http://192.168.4.1

🔄 数据流程

1. 客户端连接流程

客户端连接 → TCP握手 → 发送心跳(包含MAC) → 建立身份映射 → 加入管理列表

2. 温度控制流程

客户端上报温度 → 更新客户端状态 → 温度算法分析 → 生成控制命令 → 发送给对应客户端

3. Web操作流程

Web界面操作 → ApplicationController处理 → 更新Settings → 立即发送命令给所有客户端

🎛️ 多客户端管理

客户端识别机制

// 三层身份识别
1. TCP连接ID: "192.168.1.100:1625123456"  // IP+时间戳
2. 设备MAC地址: "AA-BB-CC-DD-EE-FF"       // 唯一设备标识  
3. 双向映射: connectionId ↔ MAC           // 动态关联

控制能力

个别控制 - 向指定MAC地址设备发送命令
群发控制 - 向所有或部分设备发送命令
广播控制 - 向所有连接设备广播消息
智能分组 - 根据温度/类型等条件分组控制

🧠 智能控制算法

温度等级系统

// 4个温度等级配置
float temperatureLevels[4] = {20.0, 22.0, 24.0, 26.0};

// 控制逻辑
if (currentTemp > level[3]) {
    targetTemp = level[2];  // 降温到等级3
} else if (currentTemp < level[0]) {
    targetTemp = level[1];  // 升温到等级2
}

自动调节策略

温度偏差检测 - 超过1°C触发调节
分级控制 - 根据温度等级智能选择目标温度
定时检查 - 每10秒执行一次温度控制算法
心跳监控 - 每30秒检查客户端在线状态

🚀 快速开始

1. 环境准备

# 安装PlatformIO
pip install platformio

# 克隆项目
git clone <repository-url>
cd distributed-air-controller

2. 硬件连接

ESP32 开发板:
├── HTU21D传感器
│   ├── VCC → 3.3V
│   ├── GND → GND  
│   ├── SDA → GPIO21
│   └── SCL → GPIO22
└── IR发射器
    ├── VCC → 3.3V
    ├── GND → GND
    └── DAT → GPIO4

3. 编译上传 ⚠️ 重要：需要上传两部分

Step 1: 编译固件

# 编译项目
pio run

Step 2: 上传固件到ESP32

# 上传程序代码到ESP32
pio run --target upload

Step 3: 上传文件系统 🔴 必须执行！

# 上传Web界面文件到ESP32文件系统 (SPIFFS)
pio run --target uploadfs

⚠️ 重要提醒:

文件系统上传是 必须的，否则Web界面无法正常工作

data/ 目录中的 index.html 和 app.js 必须上传到ESP32的SPIFFS文件系统

如果遗漏此步骤，访问 http://192.168.4.1 会显示404错误

4. 验证上传成功

检查两个上传步骤是否都成功：

✅ 固件上传成功标志:

Writing at 0x00010000... (100%)
Wrote 992301 bytes
Hash of data verified.
Hard resetting via RTS pin...

✅ 文件系统上传成功标志:

SPIFFS Upload Complete!
Uploading 2 files...
index.html (X bytes)
app.js (Y bytes)

5. 系统启动验证

ESP32启动后创建热点 ND_ESP_TEST
手机/电脑连接热点(密码: 1234567890)
浏览器访问 http://192.168.4.1 应该看到Web管理界面
TCP服务器在8848端口等待客户端连接
串口监视器显示系统启动信息

📚 开发指南

添加新的消息类型

在 MessageTypes.h 定义新消息结构
在 MessageHandler.cpp 添加序列化/反序列化方法
在 ApplicationController.cpp 添加处理逻辑

扩展控制算法

修改 ApplicationController::performTemperatureControl()
添加新的控制策略和判断条件
更新Web界面相关参数设置

自定义Web界面

修改 data/index.html 页面结构
更新 data/app.js 前端逻辑
在 WebServerManager.cpp 添加新的API端点
记得重新上传文件系统: pio run --target uploadfs

🔧 测试工具

Python测试客户端

# 运行测试客户端
python test_client.py

# 支持多客户端同时测试
# 输入要创建的客户端数量: 3

协议包测试

# 编译测试程序
pio run -e test

# 查看测试结果
pio test

📖 文档链接

部署指南 - 详细的部署步骤
使用指南 - 功能使用说明
协议重构说明 - 架构演进记录
项目总结 - 开发总结和经验

🤝 贡献指南

Fork 项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

💡 常见问题

Q: 客户端连接不上TCP服务器？

A: 确认客户端已连接到 ND_ESP_TEST 热点，服务器IP为 192.168.4.1:8848

Q: Web界面无法访问或显示404错误？

A: 最常见原因是忘记上传文件系统！ 请执行：

pio run --target uploadfs

确保 data/ 目录中的HTML和JS文件已上传到ESP32的SPIFFS文件系统。

Q: 温度控制不生效？

A: 确认Web界面中系统开关已开启，且客户端正常发送温度数据

Q: 多客户端冲突？

A: 每个客户端必须有唯一的MAC地址，系统会自动区分和管理

Q: 如何重新上传Web界面文件？

A: 修改 data/ 目录中的文件后，必须重新执行文件系统上传：

pio run --target uploadfs

项目状态: ✅ 稳定版本
最后更新: 2025年6月
开发者: @tumine

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.vscode		.vscode
data		data
include		include
lib		lib
src		src
test		test
.gitignore		.gitignore
README.md		README.md
USAGE_GUIDE.md		USAGE_GUIDE.md
platformio.ini		platformio.ini
test_client.py		test_client.py

Folders and files

Latest commit

History

Repository files navigation

分布式空调控制系统 (Distributed Air Controller)

📋 项目概述

🎯 核心功能

🏗️ 系统架构

整体架构图

组件职责分离

应用层 (Application Layer)

业务层 (Business Layer)

通信层 (Communication Layer)

📁 目录结构

🔧 硬件配置

GPIO引脚分配

网络配置

📡 通信协议

JSON消息格式

客户端上报温度

服务器控制命令

心跳检测

协议包结构

🌐 Web管理界面

功能特性

访问方式

🔄 数据流程

1. 客户端连接流程

2. 温度控制流程

3. Web操作流程

🎛️ 多客户端管理

客户端识别机制

控制能力

🧠 智能控制算法

温度等级系统

自动调节策略

🚀 快速开始

1. 环境准备

2. 硬件连接

3. 编译上传 ⚠️ 重要：需要上传两部分

4. 验证上传成功

5. 系统启动验证

📚 开发指南

添加新的消息类型

扩展控制算法

自定义Web界面

🔧 测试工具

Python测试客户端

协议包测试

📖 文档链接

🤝 贡献指南

📄 许可证

💡 常见问题

Q: 客户端连接不上TCP服务器？

Q: Web界面无法访问或显示404错误？

Q: 温度控制不生效？

Q: 多客户端冲突？

Q: 如何重新上传Web界面文件？

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages