# envController
**Repository Path**: vanmintec/env-controller
## Basic Information
- **Project Name**: envController
- **Description**: 基于 **ESP32-S3** 的环境监控 / 远程控制网关，集数据采集、输出控制、联动告警、Web 管理于一体。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-09-06
## Categories & Tags
**Categories**: Uncategorized
**Tags**: ESP32, 动环系统, 数据监控, 远程控制, 物联网
## README
# EnvController 环境监控网关
基于 **ESP32-S3** 的环境监控 / 远程控制网关，集数据采集、输出控制、联动告警、Web 管理于一体。
## 1. 产品简介
```mermaid
flowchart LR
S[环境传感器
温湿度/电表/水浸/光敏...] --> D[EnvController 网关]
D --> W[Web 管理界面
浏览器访问]
D --> C[外部设备
继电器/电磁阀/灯光...]
D --> A[声光告警]
```
- 采集外部传感器数据（Modbus 总线 / 板载输入）
- 控制外部设备（输出通道）
- 联动规则自动控制 + 分级告警
- 历史数据本地存储，Web 界面全功能管理
- 可选接入**涂鸦云（TuyaLink 直连）**，云端查看/控制
- **以太网/串口/WiFi 数据链路均已下沉固件 C 模块**：RS485(DE/CRC)、W5500 以太网(esp_eth 全链路+初始化硬复位)、涂鸦 HMAC——关键时序不依赖 Python 估算，软复位后自动恢复
> **✨ 引脚可编辑，适配灵活**
> 以太网 SPI、串口（RS485）、I2C、板载输入（DI/ADC）、输出等**全部引脚**均可在工程模式按接线实际配置，无需改动硬件即可适配不同开发板与现场接线方案，是本产品的核心灵活性之一。
## 2. 硬件兼容性与支持的外设
- **兼容 ESP32-S3 N16R8 开发板**（16MB Flash / 8MB PSRAM）
- 已支持外设：
| 外设 | 用途 |
|------|------|
| W5500 以太网模块（SPI） | 有线网络接入（固件 C 模块 wizeth 驱动，初始化含硬件复位，软复位后自动恢复） |
| WiFi（板载） | 无线网络接入 |
| RS485 串口 | Modbus RTU 总线（接传感器/电表/PLC） |
| TCA9554 I2C 扩展输出 | 8 路数字输出（继电器/电磁阀等） |
| 板载 GPIO / ADC | 数字输入（水浸/门磁/烟感）+ 模拟量输入（光敏/电压/液位） |
| SD 卡（TF） | 历史数据本地存储 |
| RTC 实时时钟 | 时间记录 / 时间同步 |
## 3. 主要功能
| 功能 | 说明 |
|------|------|
| 数据采集 | Modbus 传感器 + 板载 DI/ADC 输入，实时采集 |
| 输出控制 | 板载输出 / Modbus 输出 / GPIO 输出，支持手动与自动 |
| 联动规则 | 条件满足自动执行输出动作（如温度高自动开空调） |
| 分级告警 | 4 级告警、布防时间段、声光输出、自动消除 |
| 历史数据 | 按天存储，Web 曲线查询 |
| SD 卡管理 | 文件查看 / 上传 / 下载 / 删除 |
| Web 管理 | 全部配置与监控通过浏览器完成，无需安装软件 |
| MQTT 接入 | 可选 MQTT 上云（自定义协议：周期 DATA + 指令 /cmd + 告警事件） |
| Home Assistant | `mqtt_mode=home_assistant` 单活模式：标准 **MQTT Discovery** 自动发现（数值/开关/选择/布防/告警事件等实体），平台侧零配置；删除通道自动清理残留实体 |
| 涂鸦云接入 | 可选 TuyaLink 直连（云端设备接入，配置密钥/区域后可上线下发） |
| **引脚可编辑** | 以太网/串口/I2C/输入/输出引脚均可在工程模式按需配置，适配不同硬件接线 |
## 4. 使用说明
### 4.1 连接与访问
设备支持**以太网**与 **WiFi** 两种接入方式。上电后，通过浏览器访问设备地址（IP 以实际获取为准，可在路由后台或使用搜索工具查看）。
**默认账号**：
| 账号 | 密码 | 角色 |
|------|------|------|
| `admin` | `admin` | 普通用户（日常管理） |
| `engineer` | `engineer` | 工程用户（引脚/串口/总线等工程配置） |
> 首次使用建议修改默认密码。
### 4.2 固件烧写（envctrl_flash.exe）
使用随包附带的烧写工具，无需安装 Python：
1. 运行 `envctrl_flash.exe`
2. 选择设备**串口号**（如 COM8）
3. 选择**固件文件**（`.bin`，由厂商提供）
4. 选择波特率（默认 115200，线材质量好可提速）
5. 点击**开始刷写**，等待完成（设备自动重启）
### 4.3 设备搜索（envctrl_finder.exe）
- 自动发现局域网内所有 EnvController 设备（显示名称/SN/IP/版本）
- 双击设备可修改 IP（需输入设备账号密码认证，修改后自动重启生效）
## 5. 发布内容
编译好的固件、工具与升级包在仓库 [release/](release/) 目录：
| 文件 | 说明 |
|------|------|
| `envctrl_finder.exe` | 设备搜索工具（发现设备 / 修改 IP） |
| `envctrl_flash.exe` | 固件烧写工具 |
| `envController-1.5.1-beta-20260906.bin` | 固件文件（配合烧写工具使用，ENVCTRL_S3 自编译固件） |
| `envController-*-update.tar` | 设备升级包（配合设备 Web 维护页使用） |
| `README.md` | 本说明文档 |
| `API.md` | HTTP 接口文档（对接开发用） |
| `MQTT.md` | MQTT 协议文档（对接开发用） |
## 6. 目录用途
| 目录 | 用途 |
|------|------|
| `flash/` | **板子运行的代码**：部署/刷写进设备的全部代码（`main.py` + 各服务 + `lib/` + `html/`） |
| `c_mods/` | **固件 C 扩展模块**（`rs485bus` / `tuyacrypto` / `wizeth`），经 `USER_C_MODULES` 编译进固件，Python 侧自动回退旧实现 |
| `tools/` | **用户向工具**：设备搜索（`envctrl_finder.py`）、固件刷写（`flash_fw.py` / `flash_fw_gui.py`） |
| `docs/` | **文档**：API / FEATURES / MQTT / 项目介绍（README 留在仓库根目录） |
| `release/` | **发布物**：固件 bin、升级包、工具 exe、文档与界面截图 |
## 7. 界面预览
| 页面 | 截图 |
|------|------|
| 主页（数据总览） |  |
| 仪表盘（大屏） |  |
| 设置 |  |
| 输入输出管理 |  |
| 联动规则 |  |
| 告警规则 |  |
## 8. 联系我们
- **邮箱**：30629873@qq.com
- **QQ**：30629873
- **Bug 报告 / 建议**：请发送邮件至上述邮箱，邮件中请附上设备 SN、固件版本与问题描述
- **承接系统移植，需提供测试板
## 9. 更新记录
### v1.5.1-beta（2026-09-06）
- **涂鸦 TuyaLink 体验完善**：DP 功能点内置中文名（带设备来源前缀，如 UPS 输入电压/电量仪电压/空调设定温度），设置页功能绑定卡片直接显示功能点中文名（标识符降级小字）；与涂鸦批量导入表 `product_dp_import.xlsx` 保持一致，另附 DP 多语言表
- **配置备份/恢复修复**：维护页"导入配置"选完文件无响应的问题修复（文件 input 内联触发）；导入前对文件结构（JSON/kind/目标段）前后端双重校验，空文件或错文件明确报错
- **重启后自动刷新**：升级、重启、恢复出厂、工程重置、导入后重启等所有重启场景，设备恢复上线后页面自动刷新，无需手动 F5
- **OTA 白名单纳入 tuya_link_service**：升级包现可覆盖涂鸦链路服务（此前含该服务的升级包会被拒绝）
- **烧写工具升级**：自动定位支持 `release/envController-*.bin`；exe 打包修复 esptool stub 缺失（`--collect-all esptool`）
- **发布产物**：`envController-1.5.1-beta-20260906.bin` / `-update.tar`（应用代码编译为 .mpy，源码保护）
### v1.5.0-beta（2026-09-02）
- 代码全面下沉固件 C 模块：RS485（DE/CRC）、W5500 以太网（esp_eth 全链路 + 初始化硬复位）、涂鸦 HMAC；软复位自动恢复，不再依赖 Python 时序估算
- **Home Assistant 接入完善**：MQTT Discovery 实体声明 flash 持久化，删除通道后自动发空 retain 清理残留实体（此前 HA 实体不随配置更新）
- 系统配置导出/导入（用户/工程分离，维护页操作）
- 页面重构与多页拆分（设置/维护/规则/告警各自独立）