首页 / knowledge/代码解析/net
server.h
本页目录1. 文件职责2. 关键数据结构与宏2.1 宏常量（JSON 字段名 / 命令字 / 掩码 / 版本）2.2 枚举2.3 结构体2.4 导出的全局变量3. 函数清单4. 核心逻辑解析4.1 固件远程升级的"三段式"字段约定4.2 版本号生成的条件编译链4.3 升级状态字段的宽度约束5. 对外接口6. 依赖关系7. 备注与风险点
源文件路径：
net/server.h所属模块：网络应用层（net） 代码行数：300
1. 文件职责
server.h 是云端 EMS 服务器通信模块 server.c 的对外契约头文件。它集中定义了与"云端下发指令 / 固件升级"相关的全部字段名宏（JSON key）、命令字宏（Command 字段取值）、文件掩码宏（UpdateFileMask）、固件版本号与版本类型宏，以及升级状态相关的枚举与结构体。
在数据流中它处于"云端 TCP 报文 → server.c 解析 → 全局配置/升级状态"这一段的类型定义层：net/ems.c、net/*_download.c、HMI 界面等文件通过本头文件获取升级状态的读写接口（get_updt_status_current()、get_current_point_file_mask() 等），从而决定后续的下载、落盘与重启流程。
头文件本身不含任何可执行代码，仅提供宏、类型与函数原型声明，并将 4 个放在 SDRAM 固定地址的大缓冲区（固件缓存）以 extern 形式导出。
2. 关键数据结构与宏
2.1 宏常量（JSON 字段名 / 命令字 / 掩码 / 版本）
| 名称 | 类型 | 说明 |
|---|---|---|
FIELD_NAME_SPECIAL_CMD | 宏 | "Command"，特殊指令报文的命令名字段 |
FIELD_NAME_SPECIAL_CMD_ID | 宏 | "CmdIndex"，指令流水号，响应时原样回填 |
FIELD_NAME_SPECIAL_CMD_PARA1/2/3 | 宏 | "Parameter1"/"Parameter2"/"Parameter3"，指令参数 |
FIELD_NAME_SPECIAL_CMD_REMARK | 宏 | "Description"，备注字段；EMS 升级时被复用为 MD5 存放处（server.c:2449） |
SPECIAL_CMD_RESTART_STR | 宏 | "Restart"，复位 EMS |
SPECIAL_CMD_UPDATE_STR | 宏 | "Update"，程序更新总入口 |
SPECIAL_CMD_SETCONFIG_STR | 宏 | "SetConfig"，请求云端下发配置 |
SPECIAL_CMD_RESUME_STR | 宏 | "Resume"，断点数据续传 |
SPECIAL_CMD_REMOTE_STR | 宏 | "RemoteControl"，远程控制（ForcedCharge/ForcedWork/CloseMOS） |
SPECIAL_CMD_UPLOAD_LOG_STR | 宏 | "UploadLog"，日志上传（当前 server.c 未使用） |
SPECIAL_CMD_SYNCTIME_STR | 宏 | "SyncTime"，时间同步（Unix 秒 + 时区偏移） |
SPECIAL_CMD_DISPATCH_STR | 宏 | "Dispatch"，远程调度 |
SPECIAL_CMD_EXTRA_STR | 宏 | "Extra"，扩展指令（按 index 二级分发） |
SPECIAL_CMD_POWER_FACTOR_STR | 宏 | "PowerFactor"，功率因数 / 无功设置 |
SPECIAL_CMD_EVC_Charge_EN_STR | 宏 | "EVChargeEN"，充电桩启停 |
SPECIAL_CMD_DEBUG_RUN_INFO_STR | 宏 | "DebugRunInfo"，调试运行数据上报开关 |
SPECIAL_CMD_SYS_SHUT_DOWN_STR | 宏 | "SYSShutDownEN"，一键停机 |
SPECIAL_CMD_SET_CHARGE_STR | 宏 | "SetChargeEN"，指令充电 |
SPECIAL_CMD_SETSAFETYCONFIG_STR | 宏 | "UploadSafetyConfig"，安规配置查询/设置 |
SPECIAL_CMD_ENERGY_DATA_EN_STR | 宏 | "SendEnergyDataEN"，实时能量数据上传开关 |
SPECIAL_CMD_ICDCUPDATET_STR | 宏 | "ICDCUpdate"，单域名修改 |
SPECIAL_CMD_EXPANDICDCUPDATET_STR | 宏 | "ExpandICDCUpdate"，双域名（主备）修改 |
SPECIAL_CMD_G100_REBOOT_STR | 宏 | "G100Reboot"，英国 G100 重启 |
SPECIAL_CMD_SYS_SELF_TEST_STR | 宏 | "SYSSelfTest"，系统自检使能 |
SPECIAL_CMD_SET_BMS_WORK_TIME_STR | 宏 | "SetBMSActivationTime"，电池激活时间 |
SPECIAL_CMD_SOC_CALIBRATION_EN_STR | 宏 | "SetSOCCalibrationg"，SOC 立即校准 |
SPECIAL_CMD_BAT_LOG_STR | 宏 | "GetBatLog"，电池日志（server.c 中该分支被 #if 0 屏蔽） |
SPECIAL_CMD_SMART_CONTROL_STR | 宏 | "SmartDispatch"，智能化控制 |
SPECIAL_CMD_UPLOAD_INTERVAL_STR | 宏 | "UploadInterval"，报文上传间隔 |
SPECIAL_CMD_SET_BAT_BRAND_STR | 宏 | "SetBatBrand"，云端修改电芯品牌 |
SPECIAL_CMD_MID_METER_ENABLE_STR | 宏 | "MidMeterEnable"，MID 电表使能（server.c 走 deal_get_config_data 而非特殊指令） |
SPECIAL_CMD_UPDATE_EMS | 宏 | "EMS"，升级目标：EMS 自身 |
SPECIAL_CMD_UPDATE_EMS_APP2 | 宏 | "EMS_APP2"，第二份 EMS 固件（头文件中定义，server.c 未使用） |
SPECIAL_CMD_UPDATE_BMS | 宏 | "BMS" |
SPECIAL_CMD_UPDATE_INV | 宏 | "INV"，逆变器 APP（同时覆盖 INV1/INV2） |
SPECIAL_CMD_UPDATE_INV_ARM | 宏 | "INV_ARM"，逆变器 ARM（INV3） |
SPECIAL_CMD_UPDATE_BB | 宏 | "Backup_Box"，备电盒（走 Meter 通道） |
SPECIAL_CMD_UPDATE_METER | 宏 | "Meter" |
SPECIAL_CMD_UPDATE_EVC | 宏 | "EVCHARGER" |
SPECIAL_CMD_UPDATE_AFCI | 宏 | "AFCI" |
SPECIAL_CMD_UPDATE_MARK | 宏 | "uploads/app_update/"，URL 前缀，用于从参数串中定位版本号片段 |
MAX_SIZE_Special_CMD_Update_Str | 宏 | (16)，升级命令字符串最大长度 |
FIELD_NAME_FILE_MASK | 宏 | "UpdateFileMask" |
FIELD_NAME_FILE_MD5 | 宏 | "FileMD5Code" |
FIELD_NAME_FILE_Offset | 宏 | "FileOffset" |
FIELD_NAME_FILE_Length | 宏 | "FileLen" |
FIELD_NAME_FILE_Type | 宏 | "FWType"，目标设备的厂商型号标识 |
FIELD_NAME_FILE_DATA | 宏 | "FileData"，HEX 编码的固件分片（每包 ≤1024 字节 → 2048 个 HEX 字符） |
FIELD_NAME_Soft_Version / FIELD_NAME_Hard_Version | 宏 | "SoftVer" / "HardVer" |
FIELD_CURR_VER_NEED | 宏 | "CurrVersion" |
FIELD_NAME_UPDT_Reversed | 宏 | "UpdtReversed"（注意拼写，server.c 未使用） |
FIELD_NAME_UPDT_FileName | 宏 | "FileName" |
FILE_MASK_DEFAULT | 宏 | "00000000" |
FILE_MASK_EMS | 宏 | "00000001" |
FILE_MASK_BMS | 宏 | "00000002" |
FILE_MASK_INV1 / INV2 / INV3 | 宏 | "00000004" / "00000008" / "00000400" |
FILE_MASK_BB | 宏 | "00000020"，Backup Box |
FILE_MASK_EVC | 宏 | "00000800" |
FILE_MASK_METER | 宏 | "00001000" |
FILE_MASK_AFCI | 宏 | "00002000" |
LEN_FILE_MD5_CODE | 宏 | (32)，MD5 十六进制字符串长度 |
LEN_REQ_FILE | 宏 | (1024)，单包固件数据长度 |
LEN_FILE_MASK_CODE | 宏 | (8)，文件掩码字符串长度 |
LEN_FW_TYPE | 宏 | (7) |
MAX_LEN_SOFT_VER | 宏 | (16) |
_STR(x) / STR(x) | 宏 | 二次展开字符串化宏 |
VER_TYPE_ST/TD/RELEASE/SP/BU/FU/ATE | 宏 | 1/2/0/3/4/5/99，版本类型；决定版本号后缀 |
VER_MAIN | 宏 | "V0.11.676"，主版本号（本次拉取版本） |
VER_SEQUENCE | 宏 | ""，临时版本序号，仅非正式版本使用 |
VER_TYPE | 宏 | VER_TYPE_RELEASE（当前为正式版本） |
VERSION_STRING | 宏 | 由 VER_TYPE 条件编译出的最终版本字符串；VER_SEQUENCE+VER_SUFFIX 仅在临时版本追加 |
FW_TYPE_EMS3_6 | 宏 | "EMS3.6"，上报给云端的硬件类型字符串 |
EMS_SOFT_VERSION | 宏 | 等价于 VERSION_STRING |
EMS_SOFT_VERSION_SAFTY | 宏 | "V1.01"，安规配置版本 |
2.2 枚举
| 名称 | 类型 | 说明 |
|---|---|---|
UPGRADE_PLATFORM | 枚举 | UPGRADE_NXP = 1、UPGRADE_GD32 = 2、MAX_PLATFORM；用于 BMS 固件的 MCU 平台判别（对应 JSON "Platform":"GD"/"NXP"） |
ENUpdtStatus | 枚举 | 升级状态机：UPDT_STS_NONE=0x00、UPDT_STS_IDLE、UPDT_STS_UPDATING、UPDT_STS_OVER、UPDT_STS_MAX |
ENForceUpdtSts | 枚举 | STOP_FORCE_UPDT = 0x00、ENABLE_FORCE_UPDT；写入 STUpdateTab.bIsUpdateForce |
ENCheckOrderState | 枚举 | 设备轮询顺序状态：CHECK_NO、CHECK_EMS、CHECK_BMS、CHECK_INV1、CHECK_INV2、CHECK_INV3、CHECK_METER、CHECK_EVC、CHECK_AFCI、CHECK_MAX |
ENUpdateType | 枚举 | 升级设备索引，同时用作 stUpt[] 数组下标：UPDT_EMS=0、UPDT_BMS、UPDT_INV1、UPDT_INV2、UPDT_INV3、UPDT_Meter、UPDT_EVC、UPDT_AFCI、UPDT_MAX |
ENEraseStatusFlash | 枚举 | SECTOR_NOT_ERASED=0x00、SECTOR_IS_ERASED |
E_Resume_Sts | 枚举 | 断点续传状态：RESUME_STS_NONE=0x00、RESUME_STS_Idle、RESUME_STS_Response、RESUME_STS_Sending、RESUME_STS_Over、RESUME_STS_MAX |
2.3 结构体
| 名称 | 类型 | 说明 |
|---|---|---|
STUpdateTab | 结构体 | 单个（或一组）设备的升级上下文，见下表明细 |
json_simple_map_t | 结构体 | { char *key; void *target; u8 size; }，"JSON key → 变量地址 + 宽度" 表驱动映射项，server.c 用它把 ~90 个纯 atoi 赋值字段压成一张 const 表 |
json_time_map_t | 结构体 | { char *key; u8 *p_hours; u8 *p_minutes; }，"分钟数 → 时/分" 的时间字段映射项 |
STUpdateTab 成员明细：
| 成员 | 类型 | 说明 |
|---|---|---|
bIsGotUpdtFileInfo | BOOLEAN | 已从云端取到该设备的文件信息 |
bIsUpdateForce | BOOLEAN | 是否强制/允许下载该设备固件 |
bIsForceUpdtResponse | BOOLEAN | 需要向云端回一条强制升级响应 |
bIsUpdatedFromServer | BOOLEAN | 1 = 本固件来自服务端远程升级 |
as8FileMask[8] | char[] | 文件掩码字符串 |
as8FWType[10] | char[] | 厂商/机型标识（仅 UPDT_EMS 使用） |
as8MD5Code[32] | char[] | 云端下发的固件 MD5 |
as8SoftVer[16] / as8HardVer[16] | char[] | 软件/硬件版本 |
as8FileName[32] | char[] | 固件文件名 |
au8IDCMDUpdate[32] | u8[] | 升级指令流水号 |
u32LenFile / u32OffsetFile | u32 | 固件总长 / 当前下载偏移（断点续传依据） |
u8Platform | u8 | UPGRADE_PLATFORM，BMS 器件平台 |
u8_upgrade_object | u8 | 升级对象（电表场景用） |
as8UpdtReserve[32] | char[] | 非 EMS 设备复用为厂商/机型标识 |
u16_crc_code | u16 | 预留 CRC 字段 |
2.4 导出的全局变量
| 名称 | 类型 | 说明 |
|---|---|---|
g_au8FWBuf[SDRAM_2K] | u8[] | 通用 JSON 临时解析缓冲（json_get_value 的输出目标），定位在 SDRAM_NET_FW_BUFF_ADDR |
g_au8FWBin[SDRAM_1K] | u8[] | HEX→BIN 转换输出缓冲，定位在 SDRAM_NET_FW_BIN_ADDR |
g_u8_fw_sdram1[SDRAM_3M] | u8[] | 固件下载区 1（EMS/INV1/INV3/BMS/Meter/EVC/AFCI），定位在 SDRAM_FIRM1_START_ADDR |
g_u8_fw_sdram2[SDRAM_3M] | u8[] | 固件下载区 2（INV2），定位在 SDRAM_FIRM2_START_ADDR |
3. 函数清单
本文件为纯声明头文件，不含函数定义，仅列出导出的函数原型。作用域均为全局。
| 函数名 | 作用域 | 说明（原型作用） |
|---|---|---|
check_need_response_updt_devcie | 全局 | u8 check_need_response_updt_devcie(u8 *type)：按 INV1→INV2→INV3→BMS→Meter→EMS→EVC→AFCI 顺序取出一个待回响应且需要强制升级的设备类型 |
set_updt_status_current | 全局 | 写入 g_stEMSInfo.u8UpdtStatusCurr |
get_updt_status_current | 全局 | 读取当前升级状态 |
set_response_force_update | 全局 | 置位某设备"需要回强制升级响应"标记 |
is_goto_get_update_file_status | 全局 | 判断是否满足"已取到文件信息 且 可强制升级"（进入下载阶段） |
get_current_point_file_mask | 全局 | 返回当前升级点的文件掩码字符串指针 |
get_current_point_file_len_updt | 全局 | 返回当前升级点固件总长 |
get_current_point_offset_file_updt | 全局 | 返回当前升级点已下载偏移 |
get_curr_updt_point_is_null | 全局 | 判断 pstCurrUpt 是否为空 |
get_current_point_version_force_updt | 全局 | 返回当前升级点的目标软件版本字符串 |
get_system_sn | 全局 | 返回系统 SN（16 字节） |
get_ems_hard_type | 全局 | 返回 FW_TYPE_EMS3_6（"EMS3.6"） |
get_ems_hard_version | 全局 | 返回板级硬件版本 |
get_local_md5_ems_upt_file | 全局 | 返回本地 EMS 升级文件 MD5（32 字符） |
get_current_point_flag_force_updt | 全局 | 返回当前升级点的 bIsUpdateForce |
get_updt_dev_type_curr | 全局 | 返回当前强制升级的设备类型 |
get_current_point_updt_file_info | 全局 | 返回当前升级点的 bIsGotUpdtFileInfo |
is_goto_update_check_status | 全局 | 判断是否满足"未取到文件信息 且 可强制升级"（进入请求文件信息阶段） |
load_current_update_data | 全局 | 升级轮询状态机主体，由升级任务周期调用 |
handle_special_cmd | 全局 | 处理 0x08 特殊指令报文的总入口 |
handle_check_update | 全局 | 处理 0x20 升级检查响应 |
handle_fw_file_from_server | 全局 | 处理 0x21 固件数据包 |
deal_get_config_data | 全局 | 解析云端配置下发 JSON（约 300 个配置项） |
system_hard_reset | 全局 | 硬复位 EMS |
handle_tcp_recv_data | 全局 | TCP/无线报文接收 + CRC 校验 + 命令字分发总入口 |
save_fw_to_spi_flash | 全局 | 按设备类型把固件写入 Flash 或 SDRAM 下载区 |
increase_current_offset_file_updt | 全局 | 累加当前升级点的下载偏移 |
handle_server_debug_run_info_command | 全局 | 解析 DebugRunInfo 指令 |
handle_server_sys_shutdown_command | 全局 | 解析 SYSShutDownEN 一键停机指令 |
handle_server_set_force_charge_command | 全局 | 解析 SetChargeEN 指令充电指令 |
handle_server_energy_data_enable_command | 全局 | 解析 SendEnergyDataEN 指令 |
check_updt_force_is_none | 全局 | 判断所有设备的强制升级标志是否都为 0 |
check_force_upgradable_flag | 全局 | 判断是否还有设备"已从服务端升级"（用于避免并发升级） |
handle_server_sys_self_test_command | 全局 | 解析 SYSSelfTest 指令 |
handle_server_set_bms_activate_time_command | 全局 | 解析 SetBMSActivationTime 指令 |
handle_server_soc_calibration_enable_command | 全局 | 解析 SetSOCCalibrationg 指令 |
注：
set_current_point_updt_file_info、set_current_point_flag_force_updt、handle_server_dispatch_command、handle_server_extra_command、handle_server_power_factor_command、handle_server_evc_charge_enable_command、handle_server_upload_safety_config、handle_special_icdcupdate_cmd、handle_server_smart_dispatch_command、set_smart_control_parameter、set_upload_interval、handle_set_upload_interval、handle_set_bat_brand、parse_meter_data、handle_server_can_send_command、start_can_log_capture、is_can_log_capturing、get_special_cmd_id_code、handle_special_cmd_for_dev、set_file_updating_info、set_current_point_flag_force_updt、save_fw_to_sdram、save_fw_to_flash、store_system_set_data、deal_get_safety_config_data、set_sys_rtc、load_current_update_data_setCurrUpt等函数在server.c中已实现并公开（非static），但未在本头文件中声明，属于隐式导出的内部接口，详见server.c文档。
4. 核心逻辑解析
本文件无运行时逻辑，此处说明其定义内容所支撑的两条关键机制，以便理解各宏/枚举/结构体的用途。
4.1 固件远程升级的"三段式"字段约定
升级流程依赖头文件中三组字段协同：
- 指令发现段：
Command = "Update"+Parameter1 = <目标设备串>+Parameter2 = "uploads/app_update/..."（内含-版本号-片段）+CmdIndex+Description（EMS 场景下承载 MD5）。 - 文件信息段：
UpdateFileMask/FileLen/FileMD5Code/SoftVer/HardVer/FileName/FWType（BMS 另加Platform）。 - 数据段：
UpdateFileMask/FileOffset/FWType/FileLen/FileData（HEX）。
三段的字段名宏、掩码宏、长度宏都定义在本文件，server.c 只做解析与校验，保证字段名不会硬编码散落。
4.2 版本号生成的条件编译链
VER_MAIN = "V0.11.676"（net/server.h:109），VER_TYPE = VER_TYPE_RELEASE（net/server.h:111）。因为 VER_TYPE == VER_TYPE_RELEASE 成立，VERSION_STRING 直接取 VER_MAIN，VER_SEQUENCE/VER_SUFFIX 分支不参与编译（net/server.h:113-134）。当需要出 ST/TD/SP/BU/FU 临时版本时，只改 VER_TYPE 与 VER_SEQUENCE 两个宏即可，EMS_SOFT_VERSION 自动跟随，而 EMS_SOFT_VERSION_SAFTY 始终固定为 "V1.01"。
4.3 升级状态字段的宽度约束
STUpdateTab 中所有字符串字段的宽度都远小于 JSON 上报值（例如 as8MD5Code[32] 无结束符空间、as8SoftVer[16] 与 MAX_LEN_SOFT_VER 相等）。因此 server.c 在填充时统一使用 strlen(...) <= sizeof(...) ? strlen(...) : sizeof(...) 的三元截断写法（如 net/server.c:3322、net/server.c:3354）。这属于头文件宽度约定与实现截断策略的耦合点，改动结构体宽度时须同步核查 server.c 的 memcpy 长度。
5. 对外接口
本文件导出（供外部使用）
- 全部宏常量：
FIELD_NAME_*、SPECIAL_CMD_*、FILE_MASK_*、LEN_*、VER_*、VERSION_STRING、FW_TYPE_EMS3_6、EMS_SOFT_VERSION、EMS_SOFT_VERSION_SAFTY。 - 全部类型：
STUpdateTab、json_simple_map_t、json_time_map_t、UPGRADE_PLATFORM、ENUpdtStatus、ENForceUpdtSts、ENCheckOrderState、ENUpdateType、ENEraseStatusFlash、E_Resume_Sts。 - 4 个 SDRAM 缓冲区的
extern声明：g_au8FWBuf、g_au8FWBin、g_u8_fw_sdram1、g_u8_fw_sdram2。 - 第 3 节列出的全部函数原型。
本文件依赖（include）
chip.h（GD32 基础类型u8/u16/u32/s32、BOOLEAN、TRUE/FALSE，GD32 官方库封装）dispatch.h（net/../logic侧远程调度参数类型）ethernet.h（网络类型、NET_CONNECT_TYPE）sdram.h（SDRAM_2K/1K/3M与各段起始地址宏）
6. 依赖关系
- 依赖：
chip.h、dispatch.h、ethernet.h、sdram.h。不依赖server.c。 - 被依赖：
net/server.c（唯一实现文件）；net/ems.c通过ep./指令响应需要SERVER相关宏；net/ems_download.h通过其APP_MIN_SIZE/APP_MAX_SIZE与MAX_CNT_REQ_FILE_ERROR（net/ems.h:55）配合使用本文件的LEN_REQ_FILE；HMI 与升级任务通过server.h中的访问器读取升级状态。任何#include "server.h"的文件（grep显示主要为net/server.c、net/ems.c系列）都会间接依赖上述 4 个头文件。
7. 备注与风险点
as8MD5Code[32]无结束符空间：server.c用memcpy(..., 32)填充（net/server.c:3340），后续若被当作 C 字符串打印或strstr（如net/server.c:3419的调试printf）会越界读取。SPECIAL_CMD_UPDATE_EMS_APP2、SPECIAL_CMD_UPLOAD_LOG_STR、FIELD_NAME_UPDT_Reversed、SPECIAL_CMD_MID_METER_ENABLE_STR、MAX_SIZE_Special_CMD_Update_Str、ENEraseStatusFlash、E_Resume_Sts等定义在当前代码中未被server.c使用（残留/预留），确认清理前不要直接删除，可能有其它目录文件引用。- 字段名拼写遗留：
FIELD_NAME_UPDT_Reversed（应为 Reserved）、SPECIAL_CMD_ICDCUPDATET_STR（多一个 T）、SPECIAL_CMD_SOC_CALIBRATION_EN_STR的字符串"SetSOCCalibrationg"（多一个 g）—— 这三个字符串是与云端约定死的协议字段，不能擅自纠正，否则云端指令将无法匹配。 FILE_MASK_INV3="00000400"与FILE_MASK_METER="00001000"逻辑上是 16 进制掩码，但代码中一律用strstr(fileMask, FILE_MASK_x)做子串匹配而非位与运算（net/server.c:3227、net/server.c:3705）。这意味着掩码字符串只要"包含"该子串即判定命中，例如掩码"00001004"会同时被认为匹配INV1与METER。这是设计上的顺序优先匹配，但存在误判可能，属于已知遗留写法。VER_SEQUENCE为空串：正式版本下VERSION_STRING="V0.11.676"；一旦把VER_TYPE改成非 RELEASE 而忘记填VER_SEQUENCE，会生成形如"V0.11.676ST"的版本号，与"如 V0.11.700AST"的注释约定不符（缺 A/B 位）。属约定与实现不一致的隐患。