代码规范 SuperCap文档

User_Code/module/periph/power_meters/cone_BEM/bem.md

@@ -0,0 +1,171 @@
+# 创一工作室 自研芯衡功率计 数据解算及TOHS实现 （未完成）
+
+# Bidirectional Energy Monitor
+
+**项目名称：** 芯衡 (Bidirectional Energy Monitor)
+
+**版本：**  2025.11.24 v1.0
+
+**作者：** TuxMonkey
+
+## 目录
+
+- [1. 项目概述](#1-项目概述)
+- [2. 系统架构](#2-系统架构)
+- [3. 程序接口实现](#3-程序接口实现)
+- [4. 用法](#4-用法)
+- [5. 功率控制策略](#5-功率控制策略)
+- [6. 故障诊断](#6-故障诊断)
+
+## 1. 项目概述
+
+**芯衡 (BEM)** 是一款专为机器人竞赛设计的**实时功率监控与预警系统**。
+
+在比赛中，官方的电源管理模块对功率输出有严格限制，超功率会导致整车强制断电，从而直接导致比赛失败。本项目的核心目标，正是通过*
+*高精度、实时监测**机器人的总功耗，为控制系统提供**毫秒级的功率数据**和**超功率预警**，使机器人在发挥最大性能的同时，绝对避免因超功率而被罚下。
+
+### 1.1 核心功能
+
+- **实时双向监测**：精确测量XT30接口的电压、电流，并计算瞬时功率。
+- **累计能耗统计**：记录单场比赛或单次运行的总耗电量。
+- **功率超限预警**：当功率接近官方限制阈值时，发出软件或硬件警告。
+- **实时功率反馈**：通过串口或CAN总线，将实时功率数据发送给主控，为**功率控制算法**提供数据基础。
+
+### 1.2 硬件平台
+
+- **主控制器**：STM32F105，负责数据计算、逻辑判断与通信。
+- **功率监测芯片**：INA226，专用于双向电流/功率监测的高精度芯片，通过I2C通信。
+- **显示单元**：OLED显示屏，用于本地实时数据显示。
+- **通信接口**：串口 (UART) 或 CAN总线，用于与机器人主控交互。
+
+## 2. 系统架构
+
+```
++-------------------+      I2C       +-------------------+      UART/CAN     +-------------------+
+|   INA226          |<-------------->|   STM32F105       |<----------------->|   机器人主控      |
+|  (功率测量)       |                |  (数据处理与控制) |                   |   (决策与执行)    |
++-------------------+                +-------------------+                   +-------------------+
+         ^                                    |
+         |                                    | OLED
+         +------------------------------------+
+                  (测量XT30电源输入)
+```
+
+## 3. 程序接口实现
+
+### 3.1 INA226 驱动层
+
+主控已经做好了 了解更多请参照硬件文档
+
+### 3.2 数据处理与通信层
+
+```c
+/**
+  * @brief  功率计主任务 (应在FreeRTOS或主循环中调用)
+  * @note   负责周期性读取数据、检查预警、发送数据包
+  */
+void BEM_MainTask(void);
+
+/**
+  * @brief  获取当前功率数据包
+  * @param  *data: 指向数据包结构体的指针
+  */
+void BEM_GetDataPacket(bem_data_packet_t *data);
+
+/**
+  * @brief  通过串口发送数据包 (用于调试或上位机)
+  */
+void BEM_UART_SendData(void);
+
+/**
+  * @brief  通过CAN总线发送数据包 (用于与主控通信)
+  */
+void BEM_CAN_SendData(void);
+```
+
+### 3.3 数据结构定义
+
+```c
+typedef struct {
+    float bus_voltage_v;    // 总线电压 (V)
+    float current_a;        // 电流 (A)
+    float power_w;          // 瞬时功率 (W)
+    float energy_wh;        // 累计能耗 (Wh)
+    uint8_t alert_flag;     // 预警标志位
+    uint32_t timestamp_ms;  // 时间戳
+} bem_data_packet_t;
+```
+
+## 4. 用法
+
+*(此处描述如何使用这个功率计，从硬件连接到软件操作)*
+
+### 4.1 硬件连接
+
+1. 将功率计的XT30输入接口连接至机器人电池。
+2. 将功率计的XT30输出接口连接至机器人电源分配板。
+3. 连接STM32的串口或CAN接口至机器人主控。
+4. (可选) 连接OLED显示屏以进行本地监控。
+
+### 4.2 软件初始化
+
+在主程序初始化阶段调用以下函数：
+
+```c
+// 设置功率预警阈值为官方限值的90%，例如180W
+BEM_SetPowerAlertThreshold(180.0f);
+```
+
+### 4.3 主循环集成
+
+在主循环或独立任务中运行：
+
+```c
+while (1) {
+    BEM_MainTask(); // 执行数据读取、检查和发送
+    osDelay(10); // 根据需求调整周期，例如10ms
+}
+```
+
+## 5. 功率控制策略
+
+*(此处是文档的核心，详细说明如何利用BEM的数据避免超功率)*
+
+### 5.1 预警级别设置
+
+我们设置两级预警：
+
+- **软预警 (~80%-90% 限功率)**：当功率达到此阈值，`BEM_CheckAlertFlag()` 返回 `true`。主控程序应收到信号，并开始采取*
+  *温和的降功率措施**，如：
+    - 限制非核心机构的功率输出。
+    - 降低移动底盘的最大速度。
+    - 暂停某些预加载动作。
+- **硬预警 (~95% 限功率)**：触发硬件报警，主控必须采取**强制措施**，如：
+    - 立即停止所有非必要动作。
+    - 进入“安全模式”，仅维持最基本功能。
+
+### 5.2 主控端决策逻辑示例
+
+```c
+// 机器人主控程序中的逻辑
+bem_data_packet_t power_data;
+BEM_GetDataPacket(&power_data);
+
+if (power_data.alert_flag) {
+    // 触发预警，执行降功率策略
+    Robot_EnterPowerSavingMode();
+}
+if (power_data.power_w > HARD_LIMIT_W) {
+    // 紧急情况！立即停止所有电机
+    Robot_EmergencyStop();
+}
+```
+
+## 6. 故障诊断
+
+- **问题**：读取到的数据始终为0。
+    - **检查**：I2C线路连接是否正确，INA226地址配置是否正确。
+- **问题**：功率计算值明显不准。
+    - **检查**：分流电阻值在程序中配置是否正确，INA226的校准寄存器配置。
+- **问题**：无法接收到CAN总线数据。
+    - **检查**：CAN终端电阻是否连接，波特率设置是否匹配。

User_Code/module/periph/power_meters/cone_BEM/cone_bem.c

@@ -2,4 +2,4 @@
 // Created by ASUS on 2025/11/17.
 //
 
-#include "cone_powermeter.h"
+#include "cone_bem.h"