10 KiB
10 KiB
IES 积成平台功能说明（CCU601E_D / plat_comm/ieszt）
本文档描述 积成智通 IESZT 二进制协议在 E 工程中的落地方案、与 PlatComm 联网任务 的挂接关系，以及 S_BS_IES_CTRL_DATA 各字段含义。
上层任务状态机、双平台槽位、FTP 分时等见 《平台联网任务功能说明.md》。
1. 模块定位
| 项目 | 说明 |
|---|---|
| 目录 | app/plat_comm/ieszt/ |
| 编译宏 | BS_IES_EN（public_define.h） |
| PlatComm 槽位 | MasterFuncArray 名称 "ieszt"（plat_comm_task.c）；与 OCPP 并存时通常为槽位 0，OCPP 为槽位 1（以 PLAT_EN 配置为准） |
| 全局数据 | s_bs_task_ctrl.s_ies_data（plat_comm_task.h，类型 S_BS_IES_CTRL_DATA） |
| 传输层 | 与 OCPP 共用 bs_connect_impl：u8_tcp_connect / v_bs_send / u16_bs_recv（明文 TCP，无 WebSocket） |
| 当前阶段 | 登录/心跳 + 校时 + 费率 + 二维码 0x08/0x0A |
2. 源文件与功能分区
与 BS_ocpp_ctrl.c 相同，.c 内用 #if 1 //公共 / #if 1 //发送 / #if 1 //接收 / #if 1 //外部控制使用 折叠分区（便于 Keil 大纲跳转与整段屏蔽调试）。
| 文件 | #if 1 分区 |
内容 |
|---|---|---|
bs_ies_ctrl.c |
公共 | v_ies_timer_add、u8_ies_timer_ctrl、定时器初值、v_ies_reset_ctx、v_ies_on_login_ok |
| 发送 | v_ies_logo_on、v_ies_send_ctrl |
|
| 接收 | v_ies_recv_data、v_ies_recv_unpack |
|
| 外部控制使用 | v_ies_init_data、v_ies_tcp_connect、v_ies_private_logic |
|
impl/bs_public_impl.c |
— | u8_get_str_data / u8_set_str_data、u32_bs_get_sys_data / u8_set_sys_data（含 E_STR_QR_DISPLAY、E_BS_GET_SYS_DATA_UNIX_TIMESTAMP） |
bs_ies_interface.c |
公共 | 组帧头、CRC、v_ies_finish_frame_and_send |
| 发送 | v_ies_register_req、v_ies_heart_req、v_ies_fee_req、u8_ies_send_ack |
|
| 接收 | 登录/心跳/校时/费率/二维码；v_ies_unpack_handle（经 bs_public_impl 读写系统） |
|
bs_ies_ctrl.h |
— | 协议常量、IES_SEND_TIMER、S_BS_IES_CTRL_DATA、对外 API |
bs_ies_interface.h |
— | 报文层对外声明 |
移植路线图（阶段 3+）见 ../IES积成平台移植方案.md。
3. 与 PlatComm 的挂接（对照联网任务文档 §4）
3.1 七回调映射
| PlatComm 回调 | IES 实现 | 说明 |
|---|---|---|
v_bs_data_init |
v_ies_init_data |
清零 s_ies_data，写入 u8_bs_flag |
v_bs_tcp_connect |
v_ies_tcp_connect |
建链前清 u8_register_flag；内部 u8_tcp_connect(id) |
v_bs_logon_connect |
v_ies_logo_on |
周期发 0x01；u8_register_flag==1 时返回 1，置槽位 u8_log_on_flag |
v_bs_recv_data |
v_ies_recv_data |
u16_bs_recv → v_ies_unpack_handle |
v_bs_recv_unpack |
v_ies_recv_unpack |
空实现（4G 外部分包预留） |
v_bs_send_ctrl |
v_ies_send_ctrl |
已登录后周期发 0x03、0x05（未获费率时） |
v_bs_private_logic |
v_ies_private_logic |
u8_heart_outTime_cnt 超限 → v_set_bs_renew |
调度顺序与 v_plat_comm_network_round 一致，见 平台联网任务功能说明.md §4.3。
3.2 与 S_BS_CTRL_DATA 的分工
| 数据 | 位置 | 用途 |
|---|---|---|
| TCP/登录标志 | s_bs_ctrl[i].u8_TCP_connect_flag / u8_log_on_flag |
PlatComm 通用状态机 |
| IES 协议态 | s_ies_data |
登录应答、心跳计数、s_timerCnt[] 周期定时、序列号等 |
| 槽位号 | s_ies_data.u8_bs_flag |
与 i、E_STR_PILE_NO 第三参数、v_bs_send(id) 一致 |
4. 运行态结构 S_BS_IES_CTRL_DATA
所有 IES 私有计时与计数集中在 s_bs_task_ctrl.s_ies_data（v_ies_reset_ctx / memset 时一并清零）。
| 字段 | 类型 | 含义 |
|---|---|---|
u8_bs_flag |
U8 | PlatComm 槽位 0/1；对应 E_BS_GET_SYS_DATA_PLAT_EN 与桩编号 E_STR_PILE_NO 的 u8_dataPara |
u8_register_out_cnt |
U8 | 已发 0x01、仍未收到 0x02 的累计次数；超过 BS_IES_LOGIN_RETRY_MAX 触发 v_set_bs_renew |
u8_heart_outTime_cnt |
U8 | 已发 0x03、仍未收到 0x04 的连续次数；由 v_ies_heart_req 递增、v_ies_heart_ack 清零 |
u8_register_flag |
U8 | 1 = 平台登录成功（0x02 且结果字节为 0）；为 1 时 v_ies_logo_on 返回 1 |
u8_syn_time_flag |
U8 | 1 = 已完成平台校时（登录成功或收到 0x76） |
u8_ask_fee_flag |
U8 | 1 = 已获取/下发费率，不再周期发 0x05 |
u16_msgSerialNumber |
U16 | 自发帧序列号（组帧头时 s16_serialNum<=0 自增） |
ulong_restart_timer |
ULONG | 最近一次 TCP 建链成功时刻（get_current_seconds） |
s_timerCnt[] |
数组 | 与 OCPP OCPP_DATA_CTRL.s_timerCnt 同结构：u16_timerCnt 每秒 +1，u16_timeNUM 为周期（秒） |
ack_ctrl[] |
指针数组 | 平台下行需应答帧的异步队列（IES_DATA_RECV_ACK，同 OCPP ack_ctrl）；v_ies_send_ctrl 每轮上送一条 |
4.1 IES_SEND_TIMER 与默认周期（v_ies_init_timer_period）
| 枚举 | 默认 u16_timeNUM（秒） |
说明 |
|---|---|---|
IES_TIMER_LOGIN |
BS_IES_LOGIN_INTERVAL_S（20） |
v_ies_logo_on 发 0x01 |
IES_TIMER_HEART |
BS_IES_HEART_INTERVAL_S（20） |
v_ies_send_ctrl 发 0x03 |
IES_TIMER_FEE_MODULE |
30 | 登录后周期发 0x05 直至 0x06 或 0x7D 写入费率 |
IES_TIMER_FREE_DATA_GUN1/2 |
180 | 空闲实时 0x13 |
IES_TIMER_CHG_DATA_GUN1/2 |
30 | 充电实时 0x15 |
IES_TIMER_METER_GUN1/2 |
3600 | 电表 |
IES_TIMER_TRADE_GUN1 |
10 | 账单 |
内部接口（bs_ies_ctrl.c，与 OCPP 同名语义）：v_ies_timer_add() 每秒递增；u8_ies_timer_ctrl(cmd, GET_FLAG/CLEAR_FALG) 查询到时或清零。
5. 登录与心跳流程
[TCP 未连接]
v_ies_tcp_connect → u8_tcp_connect
（清 u8_register_flag；CLEAR_FALG LOGIN/HEART 定时器）
[TCP 已连接，未登录]
v_ies_logo_on → v_ies_timer_add
IES_TIMER_LOGIN 到时 → v_ies_register_req
收到 0x02 且 [BODY]==0 → v_ies_on_login_ok（含首包心跳定时到点）
超时次数 > BS_IES_LOGIN_RETRY_MAX → v_set_bs_renew + v_ies_reset_ctx
[已登录，u8_log_on_flag==1]
v_ies_send_ctrl → v_ies_timer_add
IES_TIMER_HEART 到时 → v_ies_heart_req
u8_ask_fee_flag==0 且 IES_TIMER_FEE_MODULE 到时 → v_ies_fee_req
v_ies_recv_data → 0x04 → v_ies_heart_ack
→ 0x76 → v_ies_set_clk_sync（v_bs_set_time，ack 挂入 ack_ctrl）
→ 0x7D → 解析费率 → v_bs_save_fee_data，0x7E 挂入 ack_ctrl
v_ies_send_ctrl → ack_ctrl 非空 → u8_ies_send_ack → v_ies_free_ack_data
v_ies_private_logic → v_ies_timer_add
u8_heart_outTime_cnt > BS_IES_HEART_MISS_MAX → v_set_bs_renew
6. 0x68 帧与已实现命令
帧域下标见 bs_ies_ctrl.h 中 IES_FRM_OFF_*（与 A 工程 u8_recvBuf[21/22/23] 一致）。
| 类型码 | 方向 | 函数 |
|---|---|---|
| 0x01 | 上行 | v_ies_register_req |
| 0x02 | 下行 | v_ies_register_ack |
| 0x03 | 上行 | v_ies_heart_req |
| 0x04 | 下行 | v_ies_heart_ack |
| 0x05 | 上行 | v_ies_fee_req |
| 0x06 | 下行 | v_ies_fee_module_ack → v_bs_save_fee_data |
| 0x07 | 上行 | u8_ies_send_ack 二维码下发应答 |
| 0x08 | 下行 | v_ies_qr_dis → QRDisplay[] + Flash |
| 0x09 | 上行 | u8_ies_send_ack 二维码召唤应答 |
| 0x0A | 下行 | v_ies_qr_call |
| 0x75 | 上行 | v_ies_clk_sync_ack |
| 0x76 | 下行 | v_ies_set_clk_sync → v_bs_set_time |
| 0x7D | 下行 | v_ies_fee_cfg_req |
| 0x7E | 上行 | v_ies_fee_cfg_ack |
| 其它 | — | v_ies_rx_cmd_handle 打日志占位 |
7. 配置与联调要点
| 配置项 | 接口 | 说明 |
|---|---|---|
| 平台使能 | E_BS_GET_SYS_DATA_PLAT_EN |
槽位 0/1 与 MasterFuncArray 下标一致 |
| 联网方式 | E_BS_GET_SYS_DATA_NET_TYPE |
0=4G，1=网口；IES 与 OCPP 共用同一套 connect |
| 桩编号 | E_STR_PILE_NO + u8_bs_flag |
双平台时平台 A/B 各一套桩号 |
| 枪数 / 故障 | E_BS_GET_SYS_DATA_GUN_NUM、NOW_FAULT_ALARM_NUM |
登录帧、心跳帧组帧 |
双平台 + 单 4G TCP：产品与 PLAT_EN 需约定主平台；详见移植方案「风险」章节。
FTP 升级中：v_ies_recv_data 在 u8_updata_flag!=0 且 4G 时跳过收包（与 OCPP 策略一致，见联网任务文档 §4.4）。
8. 日志
| 宏 | 定义位置 | 说明 |
|---|---|---|
IES_PRINT_FLAG |
plat_comm_task.h |
值 0xFE，与 OCPP_PRINT_FLAG(0xFF) 同类：不受 u8_task_log_flag 门控时默认输出 |
IES_PRINTF_LOG |
bs_ies_ctrl.h |
MYLOG_MSG(IES_PRINT_FLAG, …)；ieszt 目录内请用此宏，勿用 Plat_Comm_LOG |
| 日志 | 含义 |
|---|---|
IES: init slot= |
v_ies_init_data |
IES: login req pile= |
发出 0x01 |
IES: login ok / login fail |
0x02 解析结果 |
IES: heartbeat tx cnt= |
发出 0x03（含未应答计数） |
IES: heartbeat ack |
收到 0x04 |
IES: clk sync / clk sync ack |
0x76 校时 / 0x75 应答 |
IES: fee module req / fee model saved |
0x05 请求 / 0x06·0x7D 落盘 |
IES: login timeout, renew / heartbeat miss, renew |
触发 v_set_bs_renew |
9. 关联文档
| 文档 | 内容 |
|---|---|
| 平台联网任务功能说明.md | PlatComm 任务、双槽状态机、FTP 分时、v_set_bs_renew |
| IES积成平台移植方案.md | A→E 分阶段移植清单 |
4g_module/4G模块AT指令配置功能说明.md |
4G TCP/FTP 与 PlatComm 分时 |
impl/bs_public_impl.h |
E_STR_* / E_BS_GET_SYS_DATA_* 枚举 |
文档版本：与 plat_comm/ieszt 源码同步；结构体字段变更时请同步更新 §4。