165 lines
10 KiB
C
165 lines
10 KiB
C
/* 宿主示例电能源:整数方波积分、持久快照恢复和分段逻辑墙钟。
|
||
* 实例由调用方持有,所有入口串行;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
|