97 lines
6.9 KiB
C
97 lines
6.9 KiB
C
/* 主机录波示例:保存一条冻结的模拟记录,并导出配对 CFG/DAT 文件。
|
||
* 本层负责演示波形和主机文件 I/O;真实采集应以自有存储直接接入
|
||
* IEC60870_FaultRecorder,不能用这里的查表波形代替 ADC 采样。
|
||
*/
|
||
#ifndef IEC104_EXAMPLE_RECORDING_H
|
||
#define IEC104_EXAMPLE_RECORDING_H
|
||
|
||
#include "IEC60870_Comtrade.h"
|
||
|
||
/* 4 kHz / 50 Hz:触发前 320 点 + 触发点 1 点 + 触发后 640 点。
|
||
* 首末样点相隔完整 12 周波,因此包含两端时共 961 点。 */
|
||
#define EXAMPLE_RECORDING_FRAMES 961U
|
||
#define EXAMPLE_RECORDING_CFG_BYTES 4096U
|
||
#define EXAMPLE_RECORDING_PATH_BYTES (9U + IEC60870_COMTRADE_FILENAME_CAPACITY)
|
||
|
||
/* 对象和所有波形/文件缓冲均由调用者持有,示例主程序使用静态对象。
|
||
* recorder 内部引用 frames;初始化后不可按值搬移对象,也不可在任何
|
||
* 目录枚举或文件读取仍引用它时重新生成、释放或修改记录。
|
||
* 本示例只有一条记录,不提供多记录队列或历史文件重新加载。 */
|
||
typedef struct {
|
||
IEC60870_FaultRecorder_t recorder;
|
||
IEC60870_FaultRecorderFrame_t frames[EXAMPLE_RECORDING_FRAMES];
|
||
IEC60870_CP56Time2a_t trigger_time; /* 触发样点的冻结时间,简报和文件共用。 */
|
||
char cfg[EXAMPLE_RECORDING_CFG_BYTES]; /* 已编码的 ASCII CFG,末尾保留 NUL。 */
|
||
char names[2][IEC60870_COMTRADE_FILENAME_CAPACITY]; /* 0=CFG,1=DAT 的基本文件名。 */
|
||
char paths[2][EXAMPLE_RECORDING_PATH_BYTES]; /* 目录响应使用的 COMTRADE/完整文件名。 */
|
||
size_t cfg_size; /* 文件字节数,不包含字符串末尾 NUL。 */
|
||
uint32_t dat_size; /* DAT 不另存整份缓冲,读取时从冻结样点编码。 */
|
||
/* complete:样点、CFG 和文件名全部就绪;saved:两个最终文件均保存成功;
|
||
* published:主程序已将 TI42 简报成功入队,不表示主站已确认收到。
|
||
* 文件服务在 saved && published 时才公开这对文件。 */
|
||
bool complete, saved, published;
|
||
} ExampleRecording;
|
||
|
||
/**
|
||
* 功能:顺序构造一条明确标识为模拟来源的完整录波,再冻结 CFG、DAT 长度及配对文件名。
|
||
* 输入参数:recording——调用方持有的录波快照;trigger_time——录波触发时刻;bay——间隔编号;sequence——录波文件序号。
|
||
* 输出参数:recording——本次操作更新的实例或工作区。
|
||
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
|
||
* 说明:生成确定的 50 Hz / 4 kHz 模拟样点:从序号 0 开始,在 320 触发、960 完成。
|
||
* trigger_time 是序号 320 的时刻;循环不等待真实采样节拍,不验证硬件时序。
|
||
* bay 为 1..99,sequence 为 1..9999;本函数不自动递增序号。
|
||
* 返回 true 时 complete 已置位,saved/published 尚未置位;生成中途失败时
|
||
* 对象可能已经重置,不能继续使用旧记录。trigger_time 可指向对象内的时间字段。
|
||
* 调用者必须确保没有目录或读文件会话仍引用待重建对象,并串行调用这些接口。
|
||
*/
|
||
bool Example_Recording_Demo(ExampleRecording *recording,
|
||
const IEC60870_CP56Time2a_t *trigger_time, uint8_t bay, uint16_t sequence);
|
||
|
||
/**
|
||
* 功能:从触发前后已计算的二次侧 RMS 值重建 SIMULATION 波形,未接入真实 ADC。
|
||
* 输入参数:before/after——8 路 Ua/Ub/Uc/U0/Ia/Ib/Ic/I0,单位依次为 V/V/V/V/A/A/A/A;
|
||
* before_digital/after_digital——前后 16 路数字状态;时间与 bay/sequence 约束同 Demo。
|
||
* 输出参数:recording——完整冻结 CFG/DAT,complete=true,saved/published=false。
|
||
* 返回值:true 表示构造成功;无效输入在修改旧快照前返回 false。
|
||
* 说明:RMS 须有限且非负,按 sqrt(2) 换算后峰值不得超过 int16 正上界;
|
||
* 电压刻度 0.01V、电流刻度 0.001A,量化向零截断,不饱和或溢出。
|
||
* 50Hz/4kHz,共 961 点,0..319 使用 before,320..960 使用 after;三相相角近似
|
||
* 120 度,零序与 A 相同相,不能用于还原实测相角或谐波。此函数不等待实际采样节拍。
|
||
* 全部输入先复制/校验;允许 trigger_time 指向 recording 内的字段。内部构造异常时
|
||
* 对象可能已重建,complete 未置位;调用前须关闭旧对象的目录和读取会话并保证串行。
|
||
*/
|
||
bool Example_Recording_Capture(ExampleRecording *recording,
|
||
const IEC60870_CP56Time2a_t *trigger_time, uint8_t bay, uint16_t sequence,
|
||
const double before[8], const double after[8], uint16_t before_digital, uint16_t after_digital);
|
||
|
||
/**
|
||
* 功能:唯一写者先排除现有最终文件/临时文件,再写两份候选并依次发布。
|
||
* 输入参数:recording——调用方持有的录波快照;parent——已存在的宿主父目录。
|
||
* 输出参数:recording——本次操作更新的实例或工作区。
|
||
* 返回值:true表示本次操作成功,false表示校验拒绝或处理失败。
|
||
* 说明:将完整记录写到 parent/COMTRADE/<文件名>.cfg/.dat,parent 目录须已存在。
|
||
* 要求 complete=true、saved=false,且调用方是这些文件名的唯一写者。
|
||
* 任一最终文件或同名 .tmp 已存在时拒绝保存;存在性检查不替代跨进程互斥。
|
||
* 先写完两个临时文件,再依次改名 DAT、CFG;只有全部成功才置 saved 并返回 true。
|
||
* 失败时尝试清理本次临时文件和已改名的 DAT;清理失败仍返回 false。
|
||
* published 由主程序另行控制。本示例不保证掉电原子性,不提供持久化目录索引,
|
||
* 也不会在重启后自动恢复或重新公开上次运行留下的录波。
|
||
*/
|
||
bool Example_Recording_Save(ExampleRecording *recording, const char *parent);
|
||
|
||
/**
|
||
* 功能:本函数从冻结内存读取,不依赖磁盘保存状态;saved/published 由文件服务入口检查。
|
||
* 输入参数:recording——调用方持有的录波快照;index——本次条目、点或逻辑槽的下标;offset——从起点计算的字节偏移;buffer——调用方提供的数据缓冲;length——本次数据或名称的有效字节数。
|
||
* 输出参数:buffer——调用方提供的数据缓冲。
|
||
* 返回值:true表示指定范围的数据已完整读出;false表示范围非法、读取失败或短读。
|
||
* 说明:从完整记录读取任意字节区间:index 0=CFG,1=DAT,offset 为文件内字节偏移。
|
||
* 区间越界或记录未 complete 时返回 false;零长度读取允许 buffer=NULL。
|
||
* CFG 直接复制,DAT 按需编码;不分配内存、不访问磁盘,供网络回调和保存共用。
|
||
* 此函数只检查 complete;saved/published 的对外可见性由文件服务调用方保证。
|
||
* buffer 不得覆盖 recording;全部目录/读取会话关闭前须保持记录冻结。
|
||
*/
|
||
bool Example_Recording_Read(const ExampleRecording *recording, unsigned index,
|
||
uint32_t offset, uint8_t *buffer, size_t length);
|
||
|
||
#endif /* IEC104_EXAMPLE_RECORDING_H */
|