首页 / knowledge/代码解析/midware/inverter/alphaess
alphaess_upgrade.h
本页目录1. 文件职责2. 关键数据结构与宏3. 函数清单4. 核心逻辑解析4.1 协议帧长度契约4.2 双重版本号约定（枚举 vs 返回类型）4.3 升级完成时刻的消费者4.4 与 uCOS-II 任务/信号量的关系4.5 关键全局变量读写5. 对外接口6. 依赖关系7. 备注与风险点
源文件路径：
midware/inverter/alphaess/alphaess_upgrade.h所属模块：midware/inverter/alphaess（AlphaESS 逆变器通信协议 — 固件升级） 代码行数：75
1. 文件职责
本文件是 alphaess_upgrade.c 的对外接口头文件，定义 AlphaESS 逆变器串口固件升级协议所需的命令字宏、状态枚举、升级上下文结构体，以及 7 个导出函数原型。它只做声明与类型定义，不含任何实现代码，被 alphaess_upgrade.c 自身包含，也通过 midware/inverter/inverter.c、alphaess_comm_usart.c 间接参与升级进度查询。它同时被 #include "includes.h" 拉入工程公共依赖链，属于"升级子模块的窄接口层"。头文件中的 ALPHAESS_UPGRADE_TABLE_T 只在前向声明层面暴露类型，实际实例 s_alphaess_upgrade_tab 是 .c 内的 static 变量，外部只能通过 alphaess_read_upgrade_* 系列函数访问。
2. 关键数据结构与宏
| 名称 | 类型(结构体/枚举/宏/联合体) | 说明 |
|---|---|---|
__ALPHAESS_UPGRADE_H__ | 宏（卫哨） | 防重复包含宏，alphaess_upgrade.h:9-10 |
ALPHAESS_UPGRADE_DEBUG | 宏 | 取值 0，编译期开关；置 1 后 alphaess_upgrade.c 中所有 printf 调试分支生效（alphaess_upgrade.h:16） |
EMS_INV_SHAKE_HANDS | 宏 | 0x301，"EMS→INV 握手"命令字；本模块未使用，实际由 kelong CAN 升级使用（alphaess_upgrade.h:19） |
EMS_INV_SEND_UPGRADE_FILE | 宏 | 0x302，发送升级文件命令字；本模块未使用（alphaess_upgrade.h:20） |
EMS_INV_CHECK_UPGRADE_FILE | 宏 | 0x303，校验升级文件命令字；本模块未使用（alphaess_upgrade.h:21） |
EMS_INV_CHECK_UPGRADE_SATTE | 宏 | 0x304，查询升级状态命令字；本模块未使用（alphaess_upgrade.h:22） |
UPGRADE_DATA_MAX_LEN | 宏 | 224，单帧最大有效载荷字节数，直接决定数据帧缓冲区 u8_upgrade_data_buf[232] 与启动帧 112 字节布局（alphaess_upgrade.h:24） |
INV_EMS_ACK | 宏 | 0x401，逆变器应答命令字；本模块未使用（alphaess_upgrade.h:27） |
ALPHAESS_UPGRADE_OBJECT_E | 枚举 | 升级对象：ALPHAESS_NONE(0) 空闲 / ALPHAESS_MASTER(1) 升 CPU1 / ALPHAESS_SLAVE(2) 升 CPU2（alphaess_upgrade.h:30-35） |
ALPHAESS_UPGRADE_SATE_E | 枚举 | 升级流程状态：ALPHA_UPGRADE_START(启动帧 0x41) / ALPHA_SEND_UPGRADE_FILE(数据帧 0x42) / ALPHA_UPGRADE_END(结束帧 0x43) / ALPHA_UPGRADE_FAULT(失败)（alphaess_upgrade.h:37-45）。枚举中两处被注释掉的历史状态：ALPHA_QUERY_NUMBER_ROWS、ALPHA_CHECK_UPGRADE_FILE |
ALPHAESS_UPGRADE_TABLE_T | 结构体 | 升级上下文表（alphaess_upgrade.h:47-63），字段见下表 |
ALPHAESS_UPGRADE_TABLE_T 字段逐项：
| 字段 | 类型 | 说明 |
|---|---|---|
u32_cpu1_file_len | u32 | CPU1 固件文件长度，取自 SDRAM 描述头前 4 字节（大端） |
u32_cpu2_file_len | u32 | CPU2 固件文件长度，取自描述头偏移 54 处 4 字节 |
u16_send_cpu1_file_num | u16 | CPU1 总帧数（描述头，大端） |
u16_send_cpu2_file_num | u16 | CPU2 总帧数（描述头，大端） |
u16_file_send_cnt | u16 | 当前待发帧号，写入数据帧第 3–4 字节（大端） |
u8_cpu1_upgrade_addr | u8* | CPU1 镜像基址，运行时指向 g_u8_fw_sdram1 |
u8_cpu2_upgrade_addr | u8* | CPU2 镜像基址，运行时指向 g_u8_fw_sdram2 |
u8_upgrade_object | u8 | 当前升级对象，取 ALPHAESS_UPGRADE_OBJECT_E 值 |
u8_upgrade_start_buf[112] | u8[] | 0x41 启动帧发送缓冲，组帧后恰好 112 字节用满 |
u8_upgrade_data_buf[232] | u8[] | 0x42 数据帧发送缓冲，6 字节头 + 224 载荷 + 2 字节 CRC |
u8_upgrade_end_buf[7] | u8[] | 0x43 结束帧发送缓冲，03 43 45 4E 44 CRC |
u32_upgrade_cpu1_file_offset | u32 | CPU1 已传偏移，初值 128（跳过描述头），每帧步进 224 |
u32_upgrade_cpu2_file_offset | u32 | CPU2 已传偏移，初值 0 |
u32_upgrade_finish_tick | u32 | 升级成功时刻的 OSTimeGet()，供通信丢连阈值补偿使用 |
3. 函数清单
本文件只含函数声明（原型），实现均在 alphaess_upgrade.c；下表列出全部原型及其实现位置。
| 函数名 | 作用域 | 说明 |
|---|---|---|
alphaess_upgrade_handle | 全局（声明） | 升级主状态机，实现于 alphaess_upgrade.c:245 |
alphaess_read_upgrade_flag_master | 全局（声明） | 读 CPU1 升级标志，实现于 alphaess_upgrade.c:619 |
alphaess_read_upgrade_percent_master | 全局（声明） | 读 CPU1 升级百分比，实现于 alphaess_upgrade.c:630 |
alphaess_read_upgrade_flag_slave | 全局（声明） | 读 CPU2 升级标志，实现于 alphaess_upgrade.c:648 |
alphaess_read_upgrade_percent_slave | 全局（声明） | 读 CPU2 升级百分比，实现于 alphaess_upgrade.c:659 |
alphaess_get_upgrade_finish_tick | 全局（声明） | 读升级完成时刻 tick，实现于 alphaess_upgrade.c:688 |
alphaess_read_upgrade_file_offset | 全局（声明） | 读累计已传输字节数，实现于 alphaess_upgrade.c:677 |
函数声明区位于 alphaess_upgrade.h:66-72。
4. 核心逻辑解析
本文件为纯声明文件，无状态机与算法。以下说明其定义的协议契约与内存布局约定，这些约定由 alphaess_upgrade.c 执行。
4.1 协议帧长度契约
三个发送缓冲区的大小并非随手取整，而是与协议帧长度严格对应：
- 启动帧：
2(地址+命令) + 4(CPU1长度) + 16(CPU1 MD5) + 2(CPU1帧数) + 32(CPU1版本) + 4(CPU2长度) + 16(CPU2 MD5) + 2(CPU2帧数) + 32(CPU2版本) + 2(CRC) = 112，等于u8_upgrade_start_buf[112]，零余量。 - 数据帧：
1(地址) + 1(命令) + 1(CPU号) + 2(帧号) + 1(字节数) + UPGRADE_DATA_MAX_LEN(224) + 2(CRC) = 232，等于u8_upgrade_data_buf[232]。 - 结束帧：
1 + 1 + 3("End") + 2(CRC) = 7，等于u8_upgrade_end_buf[7]。
因此 UPGRADE_DATA_MAX_LEN（224）是新帧头/帧尾字段增删时的唯一调节点，改它必须同步改 u8_upgrade_data_buf 的数组长度。
4.2 双重版本号约定（枚举 vs 返回类型）
ALPHAESS_UPGRADE_SATE_E同时承担"协议命令字"语义：枚举值顺序（0..3）与 0x41/0x42/0x43 命令字一一对应关系仅存在于注释中（alphaess_upgrade.h:39-44），代码中实际使用枚举名而非数值，协议命令字硬编码在.c的组帧语句里（如alphaess_upgrade.c:129的0x41）。二者没有取模或映射运算关联，修改枚举顺序不会影响协议，反之亦然。ALPHAESS_UPGRADE_OBJECT_E的初值ALPHAESS_NONE = 0是.c中memset清零后处于"空闲"语义的隐含依赖——alphaess_read_upgrade_percent_*依赖u8_upgrade_object != ALPHAESS_MASTER/SLAVE来规避除零（见alphaess_upgrade.c:632、661）。- 头文件中
u8_upgrade_object声明为u8而非ALPHAESS_UPGRADE_OBJECT_E，是类型弱化的历史写法。
4.3 升级完成时刻的消费者
u32_upgrade_finish_tick 由 alphaess_get_upgrade_finish_tick() 导出，唯一消费者在 alphaess_comm_usart.c:5450：
if(abs(alphaess_get_upgrade_finish_tick()-OSTimeGet()) < 120* 1000)
l_u32_ugrade_finish_tick = 90 *1000;即升级完成后 120 秒内把"逆变器通信丢失"判定阈值额外放宽 90 秒（原本 30 秒），这是本头文件唯一影响实时调度的字段。
4.4 与 uCOS-II 任务/信号量的关系
本头文件不声明任何任务、信号量、邮箱或回调类型；升级流程完全由 alphaess_comm_usart.c:5441 的通信任务同步调用 alphaess_upgrade_handle() 驱动，OSTimeGet() 作为唯一时间基准。导出函数均非可重入（共享 s_alphaess_upgrade_tab），目前只有通信任务一个调用者，故无锁保护。
4.5 关键全局变量读写
本文件本身不定义变量，仅通过 #include "includes.h" 依赖工程公共类型（u8/u16/u32/TRUE/FALSE）。它定义的 ALPHAESS_UPGRADE_TABLE_T 的唯一实例在 .c 中为 static，外部无法直接读写。
5. 对外接口
本文件导出（所有内容均为外部可见）：
- 宏：
ALPHAESS_UPGRADE_DEBUG、EMS_INV_SHAKE_HANDS、EMS_INV_SEND_UPGRADE_FILE、EMS_INV_CHECK_UPGRADE_FILE、EMS_INV_CHECK_UPGRADE_SATTE、UPGRADE_DATA_MAX_LEN、INV_EMS_ACK - 类型：
ALPHAESS_UPGRADE_OBJECT_E、ALPHAESS_UPGRADE_SATE_E、ALPHAESS_UPGRADE_TABLE_T - 函数原型：
alphaess_upgrade_handle、alphaess_read_upgrade_flag_master、alphaess_read_upgrade_percent_master、alphaess_read_upgrade_flag_slave、alphaess_read_upgrade_percent_slave、alphaess_get_upgrade_finish_tick、alphaess_read_upgrade_file_offset
实际调用方：
| 导出符号 | 调用方 |
|---|---|
alphaess_upgrade_handle() | midware/inverter/alphaess/alphaess_comm_usart.c:5441 |
alphaess_read_upgrade_flag_master() | midware/inverter/inverter.c:3820 |
alphaess_read_upgrade_percent_master() | midware/inverter/inverter.c:3855 |
alphaess_read_upgrade_flag_slave() | midware/inverter/inverter.c:3890 |
alphaess_read_upgrade_percent_slave() | midware/inverter/inverter.c:3925 |
alphaess_read_upgrade_file_offset() | midware/inverter/inverter.c:3947 |
alphaess_get_upgrade_finish_tick() | midware/inverter/alphaess/alphaess_comm_usart.c:5450 |
本文件引入的外部依赖：仅 includes.h（alphaess_upgrade.h:13），由它间接提供 u8/u16/u32、TRUE/FALSE 等基础类型；不含任何函数调用。
6. 依赖关系
- 依赖：
includes.h（工程公共聚合头，提供基础类型定义）。 - 被依赖：
midware/inverter/alphaess/alphaess_upgrade.c（唯一实现者）- 经由
alphaess_upgrade.c间接被midware/inverter/alphaess/alphaess_comm_usart.c、midware/inverter/inverter.c使用
7. 备注与风险点
EMS_INV_SHAKE_HANDS/EMS_INV_SEND_UPGRADE_FILE/EMS_INV_CHECK_UPGRADE_FILE/EMS_INV_CHECK_UPGRADE_SATTE/INV_EMS_ACK五个宏在本模块内完全未使用：经全工程检索，它们只出现在midware/inverter/kelong/kelong_upgrade.h:16-22与其.c的 CAN 帧组装中（kelong_upgrade.c:133/159/188/232/258/285/311）。本头文件应是复制 kelong 版本后改造而来，属版本遗留死宏。ALPHAESS_UPGRADE_SATE_E用状态枚举表达协议命令字：枚举值 0..3 与命令字 0x41/0x42/0x43 的对应仅靠注释维系（alphaess_upgrade.h:39-44），实际组帧硬编码0x41/0x42/0x43（alphaess_upgrade.c:129/196/226），两处不同步时会静默跑错分支。u8_upgrade_start_buf[112]无余量：协议若追加字段必须先改数组长度，头文件与.c的组帧序列长度没有编译期断言保护。u8_upgrade_object声明为u8：丢失枚举类型信息，赋值ALPHAESS_MASTER/SLAVE依赖隐式转换；同时memset清零后值为 0，与ALPHAESS_NONE语义一致是隐含约定，由alphaess_read_upgrade_percent_*的除零防护间接依赖。- 导出函数无重入保护：7 个原型都读同一份
static上下文，头文件未标注任何线程约束；当前仅通信任务通过alphaess_upgrade_handle写、inverter.c读，属跨任务共享而无锁（读百分比时可能读到部分更新的 offset），只是精度上可容忍。 ALPHAESS_UPGRADE_DEBUG用#if而非#ifdef包裹：.c中写作#if (ALPHAESS_UPGRADE_DEBUG == 1)，若该宏未定义会直接编译报错；这是刻意的强约束，但意味着不能通过-D未定义来关闭调试。ALPHA_QUERY_NUMBER_ROWS、ALPHA_CHECK_UPGRADE_FILE两个枚举成员被注释保留（alphaess_upgrade.h:40/42），提示协议早期曾有条数查询与文件校验帧，现已废弃；若逆变器新版本 DSP 重新启用需注意枚举值缺口（当前 0,1,2,3 连续，注释不影响编号）。