Files
STM32F4-Base/IEC60870-Slave/examples/iec104_example_energy_meter.h
T
STF bdcc8b6500
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
添加遥控、参数装载、文件传输等业务
2026-11-16 22:19:17 -08:00

165 lines
10 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/* 宿主示例电能源:整数方波积分、持久快照恢复和分段逻辑墙钟。
* 实例由调用方持有,所有入口串行;QRP1保留整个实例,不重新Init。
* Evaluate_At/Snapshot为纯查询,历史事件不会受较新的206读取影响。 */
#ifndef IEC104_EXAMPLE_ENERGY_METER_H
#define IEC104_EXAMPLE_ENERGY_METER_H
#include "IEC60870_EnergyFreeze.h"
#ifdef __cplusplus
extern "C" {
#endif
#define EXAMPLE_ENERGY_METER_POINTS 8U
#define EXAMPLE_ENERGY_METER_INDEPENDENT 6U
#define EXAMPLE_ENERGY_METER_EPOCHS 16U
#define EXAMPLE_ENERGY_METER_GAIN_SEGMENTS 16U
#define EXAMPLE_ENERGY_METER_FLOW_BUDGET 4U
#define EXAMPLE_ENERGY_METER_FLOW_BACKLOG 256U
#define EXAMPLE_ENERGY_METER_DEFAULT_PERIOD 1200000U
#define EXAMPLE_ENERGY_METER_REGISTER_MAX UINT64_C(2562047788015)
/* 定义IEC104_EXAMPLE_DTU_PROFILE时,八路输出为P+/Q+/P-/Q-/Q1/Q4/Q2/Q3,
* 前四路保持DTU原6401..6404映射;方波功率取66 W/22 var,近似100V/1A
* 配置下0.4A、PF=0.95的初始负荷。通用示例保留原附录F顺序和功率。
* 两者均为独立的演示积分源,方波反转由period_ms控制,并非真实采集电能。 */
typedef struct {
uint64_t monotonic_ms;
uint64_t utc_ms;
} ExampleEnergyMeterEpoch;
typedef struct {
uint64_t monotonic_ms;
/* 从 origin 起的增量,不含恢复基线;保留亚 Wms 余数,变更不截断过去积分。 */
uint64_t accumulated[EXAMPLE_ENERGY_METER_INDEPENDENT];
double remainder[EXAMPLE_ENERGY_METER_INDEPENDENT];
double active_gain, reactive_gain; /* 已含 energy_factor 的有效增益。 */
bool reverse, reverse_transition, flow_done;
} ExampleEnergyMeterGain;
typedef struct {
/* 独立量依次为P+、P-、Q1、Q2、Q3、Q4;单位Wms/varms。 */
int64_t base_accumulators[EXAMPLE_ENERGY_METER_INDEPENDENT];
uint64_t origin_ms;
uint64_t next_flow_index;
uint64_t flowrev_dropped;
uint64_t last_step_ms;
uint32_t period_ms;
size_t epoch_count;
ExampleEnergyMeterEpoch epochs[EXAMPLE_ENERGY_METER_EPOCHS];
size_t gain_count;
ExampleEnergyMeterGain gains[EXAMPLE_ENERGY_METER_GAIN_SEGMENTS];
IEC60870_EnergyFreezeResult_t last_result;
bool initialized;
bool faulted;
} ExampleEnergyMeter;
/**
* 功能:建立零积分基线、波形起点和首个单调时刻/UTC映射,首条反转从第1个半周期开始。
* 输入参数:self——调用方持有的模块实例;period_ms——功率方波周期,单位毫秒;mono_ms——绝对单调毫秒时刻;utc_ms——UTC毫秒时刻。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
* 说明:period为2000..86400000ms的4倍数。无恢复数据时八个寄存器均从0开始。
* mono为当前绝对单调毫秒,utc为同刻有效墙钟;恢复不会改变波形起点。
*/
bool Example_Energy_Meter_Init(ExampleEnergyMeter *self, uint32_t period_ms,
uint64_t mono_ms, uint64_t utc_ms);
/* 预检/提交同一串行时刻的增益切点;P/Q 增益及 energy_factor 须为有限正数。
* 生效值是 active/reactive_gain * energy_factor;reverse 同时翻转 P/Q 极性。
* 只改变切点之后的积分斜率及象限,旧 Evaluate_At/FLOW 值不变;方波相位不重置。
* 默认增益 1、极性正向不占段;最多保存 16 个实际变化切点,不淘汰旧积分历史。
* 同值重设不耗段,同毫秒新值覆盖该切点;满时拒绝新切点并保持实例不变。
* Can_Set 与 Set 使用同一 now 且两次调用间无实例修改时,预检成功保证提交成功。
* 时间不得早于最后 Step/切点;极性在非半周期边界变化时另排一条 FLOW,
* 与半周期同时反转会抵消该边界。已提交的同毫秒事件不会被重写。
* 分段只保留于本进程;重启先 Restore,再于 origin 设置已恢复配置的当前增益。
*/
bool Example_Energy_Meter_Can_Set_Gains_At(const ExampleEnergyMeter *self, uint64_t mono_ms,
double active_gain, double reactive_gain, double energy_factor, bool reverse);
bool Example_Energy_Meter_Set_Gains_At(ExampleEnergyMeter *self, uint64_t mono_ms,
double active_gain, double reactive_gain, double energy_factor, bool reverse);
/**
* 功能:仅启动时恢复:排序全部八值候选,验证相邻向量逐分量不下降,再由最大向量建立积分基线。
* 输入参数:self——调用方持有的模块实例;core——已初始化的冻结电能核心。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示恢复检查成功;空库保留原整数基线,有候选时验证支配链后恢复基线。false表示读取、数值或内存申请失败。
* 说明:仅启动时调用:扫描保留的I/D及完整有效FLOW,排序并验证八值支配链。
* Windows HeapAlloc临时使用最多3360*8*sizeof(float)字节,返回前释放。
* 不在栈或实例中放大排序存储;失败不得继续启动或沿用部分恢复结果。
*/
bool Example_Energy_Meter_Restore(ExampleEnergyMeter *self,
IEC60870_EnergyFreeze_t *core);
/**
* 功能:从八个浮点示值恢复可行的整数Wh/varh,同时满足六个独立量和两个无功合计的编码原像。
* 输入参数:values——八路浮点电能值数组;registers——八路整数电能寄存器回写数组。
* 输出参数:registers——八路整数电能寄存器回写数组。
* 返回值:true表示计算或反解成功并发布输出数组;false表示输入、范围或数值约束不满足。
* 说明:通用八值顺序:P+、Q+、Q1、Q4、P-、Q-、Q2、Q3;DTU顺序见本文件顶部;单位Wh/varh。
* 逆像恢复保持全部八个binary32编码;不以浮点和选择恢复来源。
* 输出仅在成功时修改,可用于不依赖文件系统的恢复单元测试。
*/
bool Example_Energy_Meter_Restore_From_Values(
const float values[EXAMPLE_ENERGY_METER_POINTS],
uint64_t registers[EXAMPLE_ENERGY_METER_POINTS]);
/**
* 功能:对每个独立量计算它在完整周期和当前相位中的导通毫秒。
* 输入参数:self——调用方持有的模块实例;mono_ms——绝对单调毫秒时刻;registers——八路整数电能寄存器回写数组。
* 输出参数:registers——八路整数电能寄存器回写数组。
* 返回值:true表示计算或反解成功并发布输出数组;false表示输入、范围或数值约束不满足。
* 说明:不保存“上次输出”或推进积分,先读当前值再补旧FLOW仍得到旧时刻的值。
*/
bool Example_Energy_Meter_Evaluate_At(const ExampleEnergyMeter *self,
uint64_t mono_ms, uint64_t registers[EXAMPLE_ENERGY_METER_POINTS]);
/**
* 功能:查询指定单调时刻的八值并编码为浮点示值,成功时统一填零品质。
* 输入参数:self——调用方持有的模块实例;mono_ms——绝对单调毫秒时刻;values——八路浮点电能值数组;quality——八路品质回写数组。
* 输出参数:values——八路浮点电能值数组;quality——八路品质回写数组。
* 返回值:true表示计算或反解成功并发布输出数组;false表示输入、范围或数值约束不满足。
* 说明:不推进积分或事件游标;数值环境或求值失败时返回false,保持两个输出数组原内容。
*/
bool Example_Energy_Meter_Snapshot(const ExampleEnergyMeter *self, uint64_t mono_ms,
float values[EXAMPLE_ENERGY_METER_POINTS],
uint8_t quality[EXAMPLE_ENERGY_METER_POINTS]);
/**
* 功能:加入校时成功后的逻辑切换点,单调时刻不能倒退;相同切点覆盖UTC,已提交事件不重标。
* 输入参数:self——调用方持有的模块实例;mono_ms——绝对单调毫秒时刻;utc_ms——UTC毫秒时刻。
* 输出参数:self——本次操作更新的实例或工作区。
* 返回值:true表示新的逻辑时钟基准已登记;false表示实例、时刻或顺序校验失败。
* 说明:成功设时后在动作回调之外调用。mono是逻辑基准切换点,不代表RTC物理生效。
* 相同mono以最后一次成功设时为准;满队列会丢弃最老时段尚未生成的事件并计数。
* 已提交事件不改时标;独立分段时钟不自动跟随系统时钟的周期刷新。
*/
bool Example_Energy_Meter_Set_Epoch(ExampleEnergyMeter *self,
uint64_t mono_ms, uint64_t utc_ms);
/**
* 功能:使用最后一个不晚于查询时刻的分段,将单调毫秒映射为UTC;旧事件保留其所属分段的时间口径。
* 输入参数:self——调用方持有的模块实例;mono_ms——绝对单调毫秒时刻;utc_ms——UTC毫秒回写位置。
* 输出参数:utc_ms——UTC毫秒回写位置。
* 返回值:true表示找到适用时段并写回UTC毫秒;false表示时段或时刻不可映射。
* 说明:找不到基准、算术溢出或超出日历范围时返回false,保持utc_ms原值,不修改分段队列。
*/
bool Example_Energy_Meter_Time_At(const ExampleEnergyMeter *self,
uint64_t mono_ms, uint64_t *utc_ms);
/**
* 功能:每轮先提交至多4条按发生时刻求值的FLOW,超过256条的积压只保留最新部分并计数。
* 输入参数:self——调用方持有的模块实例;core——已初始化的冻结电能核心;mono_ms——绝对单调毫秒时刻。
* 输出参数:self——推进FLOW游标、时段及故障状态;core——通过记录和封存接口推进持久冻结状态。
* 返回值:true表示本轮推进无错误,仍可能保留待办或等待;false表示推进失败。
* 说明:每轮先按原零点快照提交至多4条FLOW,再推进封存及当前时刻冻结。
* 积压超过256仅保留最新256条并计数;回拨只暂停定时冻结,FLOW仍推进。
* 有效实例推进失败时锁存faulted/last_result;入口无效时直接返回false。调用方停止服务,不得重放失败的持久提交。
*/
bool Example_Energy_Meter_Step(ExampleEnergyMeter *self,
IEC60870_EnergyFreeze_t *core, uint64_t mono_ms);
#ifdef __cplusplus
}
#endif
#endif