首页 / knowledge/代码解析/midware/auxiliary

system_aux.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 能量结构的存储契约 4.2 三组全局时间量的分工 4.3 相位参数的取值约定 4.4 与 uCOS-II 的关系 5. 对外接口 6. 依赖关系 7. 备注与风险点

源文件路径：midware/auxiliary/system_aux.h 所属模块：midware/auxiliary（系统辅助任务：能量统计 + RTC + 设备功能位）代码行数：90

1. 文件职责

system_aux.h 是 EMS 主控辅助任务（task_system_aux，优先级 TASK_SYSTEM_AUX_PRIO=8，400ms 周期，见 UCOSII/uCOS-CONFIG/app_cfg.h:59、user/main.c:167）的对外契约头文件。它定义了整机能量的持久化结构 ENERGY_COUNT_INFO_T——这是全部电量统计（PV 发电、电池充放、电网取电/馈网、分相电量、油机电量）的落地载体，由 system_aux.c 在 RAM 中实时刷新，最终由 data/system_config/system_config.c 写入 Flash 的 ENERGY_INFO_PAGE(4076)。同时它导出了 g_t_energy_info、SYSTEM_DATETIME、g_t_sys_datetime 三个全局量，以及一组只读的 energy_read_* / get_realtime_* 访问器，供云端通信（net/ems.c）、Modbus/SunSpec、HMI 电量历史页面和断电续传存储（data/resume_data/flash/flash_data_store.c）读取。头文件本身不含任何逻辑，只做类型声明、内存布局约束和接口声明。

2. 关键数据结构与宏

名称	类型	说明
`DEBUG_SYSTEM_AUX`	宏	调试开关，`(0)` 关闭。置 1 才会编译 `system_aux.c` 中的 `printf_debug_info()` 打印与 `g_t_task_run_status.u32_task_system_aux_cnt` 计数
`TIME_BASE_YEAR`	宏	`(1900)`，`struct tm.tm_year` 的基准年
`NOW_BASE_YEAR`	宏	`(2000)`，本机 RTC 年份（0~99）换算成 `tm_year` 时使用：`tm_year = RTC_Years + NOW_BASE_YEAR - TIME_BASE_YEAR`（`system_aux.c:367`）
`ENERGY_COUNT_INFO_T`	结构体（`#pragma pack(1)` 紧凑排列）	整机能量统计持久化结构：`u16_head` 头 + 21 个 `u32` 电量累计项 + `u8_reserve[40]` + `u16_crc_code`，共 128 字节
`u16_head`	字段	页头，写入时置 `CONFIG_INFO_HEAD(0xAA55)`
`u32_storage_pv_input`	字段	储能机 PV 输入电量
`u32_storage_inv_output`	字段	储能机逆变输出电量
`u32_bat_charge` / `u32_bat_dischg`	字段	电池充电量 / 放电量（可由 BMS 直接同步，见 `u8_energy_sync_flag`）
`u32_grid_charge`	字段	电网给电池充电量（积分类，非电表读数）
`u32_pv_charge`	字段	PV 给电池充电量（由 `bat_charge - grid_charge` 推算，见 `system_aux.c:2130`）
`u32_grid_consumption` / `u32_grid_feedin`	字段	电网取电总电量 / 馈网总电量，来自 `GRID_METER` 的 `PHASE_T` 读数
`u32_pv_inverter_output`	字段	并网机 PV 发电量，来自 `PV_METER` 的 `PHASE_T` 读数
`u32_generator_energy_output`	字段	柴油机发电量
`u32_storage_inv_input`	字段	储能机逆变输入电量
`u32_storage_bat_charge` / `u32_storage_bat_dischg`	字段	储能机侧电池充电 / 放电电量（来自逆变器寄存器读数）
`u32_grid_a/b/c_phase_consumption`	字段	电网 A/B/C 相取电电量（分相统计）
`u32_grid_a/b/c_phase_feedin`	字段	电网 A/B/C 相馈网电量（分相统计）
`u32_bat_dischg_feedin_grid`	字段	电池放电馈入电网的电量（强制馈网场景）
`u32_generator_energy_charge`	字段	柴油机给电池充电量。注意：对应的统计函数在 `.c` 中被 `#if 0` 掉，当前恒为 0
`u8_reserve[40]`	字段	保留区，凑满 128 字节（`ASSERT_FLASH_SECTOR_SIZE` 4096 能被整除）
`u16_crc_code`	字段	Modbus CRC16，由 `GetCrcCode_Modbus()` 在写 Flash 前计算
`STATIC_ASSERT(...)`	编译期断言宏	定义于 `midware/debug/debug.h:16`，此处用于断言 `ASSERT_FLASH_SECTOR_SIZE % sizeof(ENERGY_COUNT_INFO_T) == 0`，即 4096 % 128 == 0，保证一页 Flash 正好放 32 份结构体
`ASSERT_FLASH_SECTOR_SIZE`	宏	等价于 `FLASH_SECTOR_SIZE`（`hardware/flash/flash.h:27`，4*1024 字节）
`g_t_energy_info`	全局变量（`extern`）	`ENERGY_COUNT_INFO_T` 实体，定义在 `system_aux.c:35`
`SYSTEM_DATETIME`	全局变量（`extern`）	`struct RTC_DateTime`（`hardware/pcf8563/pcf8563.h:236`），6 字节 BCD 拆解后的当前时间，供全工程直接读年/月/日/时/分/秒
`g_t_sys_datetime`	全局变量（`extern`）	`_PCF8563_DateTime_Typedef`（`pcf8563.h:222`），原始 RTC 读出结构，含 `RTC_WeekDays`

3. 函数清单

本文件只有声明，无函数体。

函数名	作用域	说明
`task_system_aux(void *p_arg)`	全局（声明）	辅助任务主循环，实体在 `system_aux.c:2056`
`enenrgy_count_handle(void)`	全局（声明）	把 RAM 中的分钟级能量累计刷进 `g_t_energy_info` 并落 Flash（注意函数名拼写为 `enenrgy`，少一个 `r`）
`energy_read_storage_pv_input(void)`	全局（声明）	读储能机 PV 输入电量
`energy_read_storage_inv_input(void)`	全局（声明）	读储能机逆变输入电量
`energy_read_storage_inv_output(void)`	全局（声明）	读储能机逆变输出电量
`energy_read_storage_bat_charge(void)`	全局（声明）	读储能机电池充电电量
`energy_read_storage_bat_dischg(void)`	全局（声明）	读储能机电池放电电量
`energy_read_bat_chgrge(void)`	全局（声明）	读电池充电量
`energy_read_bat_dischg(void)`	全局（声明）	读电池放电量
`energy_read_grid_chgrge(void)`	全局（声明）	读电网给电池充电量
`energy_read_bat_dischg_feedin_grid(void)`	全局（声明）	读电池馈网电量
`energy_read_pv_chgrge(void)`	全局（声明）	读 PV 给电池充电量
`energy_read_grid_consumption(u8 phase)`	全局（声明）	按相位（`PHASE_A/B/C/T`）读电网取电电量
`energy_read_grid_feedin(u8 phase)`	全局（声明）	按相位读电网馈网电量
`energy_read_pv_inverter_output(void)`	全局（声明）	读并网机 PV 发电量
`energy_read_gc_output(void)`	全局（声明）	读柴油机发电量
`energy_read_gc_charge(void)`	全局（声明）	读柴油机给电池充电量
`get_realtime_bat_chg(void)`	全局（声明）	读电池充电量「实时值」（含未落盘的分钟余量）
`get_realtime_bat_dischg(void)`	全局（声明）	读电池放电量「实时值」
`get_realtime_bat_chg_from_grid(void)`	全局（声明）	读电网给电池充电量「实时值」
`get_realtime_bat_dischg_feedin_grid(void)`	全局（声明）	读电池馈网电量「实时值」
`get_average_power_of_gridmeter(u8 phase)`	全局（声明）	读电网电表 1 分钟滑动平均有功功率（带符号）
`get_rtc_tick(void)`	全局（声明）	返回 RTC 换算出的 `time_t` 秒级时间戳
`set_system_function_enable(u8 u8_page, u8 u8_index, u8 u8_value)`	全局（声明）	按位改写 `g_t_system_base_info.u_system_function1.u64_all` 并投递 Flash 保存作业

头文件中未声明 parallel_system_function_handle()、device_function_init_parallel_change()、para_device_function_init() 等 .c 内部函数，那些属于文件私有实现。

4. 核心逻辑解析

本节内容全部体现在 system_aux.c，头文件只提供类型与接口，因此只说明接口契约层面的关键点。

4.1 能量结构的存储契约

ENERGY_COUNT_INFO_T 被 #pragma pack(1) 强制为无填充的 128 字节布局，并配 STATIC_ASSERT 在编译期锁定 4096 / 128 == 32 的整除关系。这意味着：

结构体字段的增删会直接改变 Flash 记录的长度和 ENERGY_INFO_PAGE 的排布，属于跨版本强耦合的持久化格式；一旦增删字段，旧固件写下的数据在 CRC 校验和字段语义上都不再兼容。
u8_reserve[40] 是后续扩展的预留空间，新增 u32 统计项（最多 10 个）可以不动总长度。

4.2 三组全局时间量的分工

g_t_sys_datetime：原始结构（含星期），在 rtc_refresh()（system_aux.c:341）中由 PCF8563_Get_DateTime_Other() 整体赋值。
SYSTEM_DATETIME：只挑出 6 个字段（年/月/日/时/分/秒）逐个赋值，是工程中使用最广的时间量（data/fault_warn_log、data/net_event_log、logic/generator.c、logic/logic.c、hmi、midware/evc 等都直接读它）。
s_time_rtc_tick：system_aux.c 内部 static，通过 get_rtc_tick() 暴露为 time_t，用于需要「可比较时间戳」的场景（logic/logic.c、net/ems.c、net/server.c、data/resume_data/flash/flash_data_store.c）。

4.3 相位参数的取值约定

energy_read_grid_consumption()、energy_read_grid_feedin()、get_average_power_of_gridmeter() 的 phase 参数直接复用 midware/meter/meter.h:172 的 METER_PHASE_E：PHASE_A=0、PHASE_B=1、PHASE_C=2、PHASE_T=3（电表总值）。PHASE_T 映射到总量字段，其余映射到分相字段，非法值统一返回 0。

4.4 与 uCOS-II 的关系

头文件不涉及信号量/邮箱。task_system_aux 是 user/main.c:167 用 OSTaskCreateExt() 静态创建的周期任务，任务栈为 TASK_AUXILIARY_STK（TASK_AUXILIARY_STK_SIZE=512，见 app_cfg.h:86），任务内 OSTimeDlyHMSM(0,0,0,400) 做 400ms 周期节拍，OS_TICKS_PER_SEC = 1000（UCOSII/uCOS-CONFIG/os_cfg.h:51），因此代码中所有 OSTimeGet() 差值都按毫秒解读。

5. 对外接口

本文件导出（声明 + extern）

全局变量：g_t_energy_info、SYSTEM_DATETIME、g_t_sys_datetime
函数：task_system_aux、enenrgy_count_handle，以及 20 个 energy_read_* / get_realtime_* / get_average_power_of_gridmeter / get_rtc_tick / set_system_function_enable 访问器

本文件依赖（include 的外部头）

includes.h（uCOS-II + 基础类型 u8/u16/u32/s32）
pcf8563.h（_PCF8563_DateTime_Typedef、struct RTC_DateTime，同时被拿来做 extern 声明）
<time.h>（time_t）
debug.h（STATIC_ASSERT / ASSERT_FLASH_SECTOR_SIZE）

6. 依赖关系

依赖

UCOSII/uCOS-CONFIG/includes.h、hardware/pcf8563/pcf8563.h、midware/debug/debug.h、C 标准库 <time.h>。
STATIC_ASSERT 链条间接依赖 hardware/flash/flash.h 的 FLASH_SECTOR_SIZE。

被依赖（grep -rl "system_aux.h" 命中，超过 20 个文件，节选）

数据层：data/data.c、data/system_config/system_config.c、data/fault_warn_log/fault_warn_log.c、data/net_event_log/net_event_log.c、data/resume_data/flash/flash_data_store.c
逻辑层：logic/logic.c、logic/generator.c
网络层：net/ems.c、net/server.c
HMI：hmi/ui/ui_main.c、hmi/ui/ui_history_grid_consumption.c、hmi/ui/ui_history_pv_yield.c、hmi/ui/ui_history_bat_chg_energy_from_grid.c、hmi/ui/ui_history_bat_chg_energy_from_pv.c、hmi/ui/ui_history_local_yield.c、hmi/ui/ui_history_yield.c、hmi/ui/ui_setting_user_sys_date.c、hmi/key.h
中间件：midware/bms/alpha/battery_comm.c、midware/bms/bms.c、midware/evc/evc.c、midware/evc/evc_ii.c、midware/inverter/set/set_comm_usart_s5.c、midware/interface/modbus/modbus.c、midware/interface/modbus/sunspec_business.c
全部这些文件的共同用途：读电量累计值、读系统时间、或（system_config.c）驱动 enenrgy_count_handle()。

7. 备注与风险点

函数名拼写错误固化进接口：enenrgy_count_handle()（system_aux.h:64）少一个 r，已被 data/system_config/system_config.c:3063 调用。改名会波及调用方，属于既定兼容包袱，不建议在本次解析中动。
持久化格式强耦合：ENERGY_COUNT_INFO_T 的 128 字节布局与 ENERGY_INFO_PAGE(4076) 的 Flash 记录格式绑定，且 STATIC_ASSERT（system_aux.h:52）会在改动布局时编译失败——这是有意的保护，但也说明任何字段增删都需同步评估升级兼容性。
u32_generator_energy_charge 是死字段：声明并导出（energy_read_gc_charge()），但唯一的统计函数在 .c 中被 #if 0 屏蔽，该字段在 Flash 中恒为 0，云端/Modbus 读到的是无效数据。
u8_reserve[40] 未初始化隔离：结构体在有 memset 的路径（system_config.c:641）下为 0，但若将来局部构造结构体直接落盘，保留区的垃圾值会进入 CRC 覆盖范围，需要注意。
#pragma pack() 未显式带参数：结束时用无参 #pragma pack()（system_aux.h:54）恢复默认，依赖编译器默认对齐；若此头文件被包含进别处已改变对齐设置的上下文，可能产生非预期布局（当前工程无此情况）。
g_t_sys_datetime 与 SYSTEM_DATETIME 冗余：两套时间结构并存且同时被外部读取（logic/logic.c、midware/bms/bms.c 读 g_t_sys_datetime；其余多数读 SYSTEM_DATETIME），二者只在 rtc_refresh() 中同一时刻刷新，一致性依赖该函数的单点写入，无锁保护。