1. 项目概览 Mains Aegis 是面向外置电源的 mini PC、工控设备的后备式 UPS。它提供额定 120W 的可调输出，支持 12V–21V 输出范围、USB-C PD 充放电、联网管理和主机控制，并使用四节可拆卸的 21700 锂电池储能。
这个项目关注的是一台供电设备从电源链路到用户界面的完整实现。软件、固件、硬件、电池结构、外壳和相关文档共同组成项目，开源内容覆盖电源控制、嵌入式运行时、前端交互和机械设计。
1.1 系统范围 Mains Aegis 的实现范围包括电源设备的装配、输出配置、电池组、外壳和接口布局，也包括 ESP32-S3 固件、电源管理状态机、设备控制台和硬件监测链路。
输入资格、电池授权、充电状态、温度告警和输出门控经过统一的控制链路，最终在屏幕、Web 控制台和串口日志中呈现。
1.2 整机组成 从硬件构成看，Mains Aegis 包含主板、前面板、电池组和外壳：主板承载 BMS、充电、主输出和监测电路，前面板提供显示、触摸、按键和 USB 前端，外壳容纳电池、电子部件与操作接口。软件部分以 ESP32-S3 固件为核心，负责把这些硬件模块组织成统一的启动、自检和运行状态。
这种分层也对应了项目的开源边界：电源板和电池系统可以单独研究，控制台和固件也有各自的运行与开发内容，组合起来则形成完整的 UPS 运行体验。
2. 硬件架构 2.1 硬件组成与电源链路 电源链路以 4S1P 电池包为基础。独立的 USB-C PD PHY 负责协议协商，BQ25792 负责输入路径选择与充电管理，BQ40Z50-R2 负责电量计量和电池保护；两路 TPS55288 并联后生成主输出。INA3221 负责输入和输出电压、电流监测，TMP112A 负责温度监测，ESP32-S3 则读取这些状态并决定系统是否可以继续运行。
硬件架构按输入与充电管理、电池、主输出、接口和控制监测分层；USB-C 与 DC IN 在 BQ25792 的输入管理处汇合，UPS OUT 是唯一的对外输出接口。 USB-C 的 PD 协商由独立 PHY 完成，USB-C 与 DC IN 进入 BQ25792 的输入与充电管理路径，电池由 BMS 管理。 外部输入与电池稳压输出经过各自的理想二极管路径，汇入唯一的 UPS OUT。 这些器件并不是彼此独立的功能块。BMS 是否允许放电、输入是否满足条件、充电器是否完成配置、输出级是否准备就绪，都会影响最终的输出资格。系统会把这些条件汇总到自检、运行状态和输出门控中。
3. 软件架构与运行 3.1 固件、控制台与前面板 设备启动后先进入 SELF CHECK。固件按固定顺序确认同步、监测、前面板、BMS、充电器和两路 TPS55288 的状态，再决定是否允许进入 Dashboard。这个过程既是用户看到的启动界面，也是硬件 bring-up 时定位问题的第一处证据。
前面板、Web 控制台和串口日志读取同一组运行状态。界面使用 BYPASS、STANDBY、ASSIST 和 BACKUP 表达输入、电池与输出的关系，也保留 Battery、Charge 和 Dischg 等观察入口，让操作者能够区分输入在线但没有实际输出、TPS 正在辅助供电以及电池正在承担负载。
触摸、按键和 USB 输入都会经过固件状态机。输入切换、温度告警或电池不可用时，界面显示对应状态，真正的输出状态仍由固件的资格判断和门控结果决定。
ESP32-S3 固件从驱动层读取硬件状态，在状态与控制层完成自检、充电、输出准入和保护，再向前面板、Web 控制台、USB CDC 和诊断日志提供统一状态。 3.2 保护状态与输出准入 硬件保护和软件状态共同决定设备是否继续出力。INA3221 监视 UPS VIN 以及两路 TPS55288 输出，并通过 PV、Warning 和 Critical 信号参与欠压、预警和过流处理；TMP112A 的两路热告警汇总到 THERM_KILL_N，作为禁止继续出力的硬条件。固件再把这些信号映射到自检、Dashboard、串口日志和输出门控。
INA3221、TMP112A、BMS 和 TPS55288 的状态共同参与输出准入判断。 自检门控会区分“上游没有授权”和“输出级本身故障”。例如 BQ40Z50 缺失或放电未授权时，TPS55288 会保持 HOLD；热停机、TPS 故障和保护锁存则进入更严格的禁止输出路径，直到条件恢复或执行显式恢复操作。电池和高功率电路的装配、测试与改造边界记录在项目文档中。
3.3 启动自检与验证 硬件调试从输入资格、BMS 通讯和充电器状态开始，再逐步放行两路 TPS55288。每一级都会在自检快照、串口日志和 Dashboard 中留下结果，便于定位同步、监测、授权或输出级故障。
固件按固定顺序确认同步、传感器、前面板、BMS、充电器和 TPS55288，再进入运行状态、HOLD 或禁止输出。 4. 机械结构与开源范围 4.1 外壳与机械设计 外壳把可拆卸电池、主板、前面板和接口组织成一台可操作的设备。结构中包含 21700 电池的放置空间、主板固定位置、触摸屏和按键开口、USB-C 与输出接口开孔，以及高功率器件周围的空间和散热路径。
外壳相关文件与装配资料属于项目的开源范围，现有结构适用于 3D 打印或其他加工方式，也为外观和安装方案的修改保留空间。
4.2 开源范围与复现方式 Mains Aegis 的开源内容覆盖软件、固件、硬件设计、外壳和项目文档。项目资料同时支持整机复现、局部硬件制作、控制台运行，以及电源和嵌入式实现研究。
项目的复现资料以硬件版本、电池配置、输入输出条件、启动自检和验证记录为主要上下文。BMS 状态、充电器状态、温度、输入输出测量值和串口日志共同构成设备调试信息。
前面板机械图 主板 PCB 前面板 PCB 主板原理图 前面板原理图 ↗
4.3 项目状态与参与方式 Mains Aegis 目前仍处于持续验证和迭代阶段。已经完成的设计、样机实测结果和待验证事项会分别记录，避免把规划中的能力误写成已经交付的功能。
项目的贡献方向包括硬件、固件、前端、机械设计和测试。现有工作覆盖电源控制、验证记录、外壳方案、控制台和文档；问题记录通常关联硬件版本、测试条件、相关状态和日志。
