121 lines
7.6 KiB
C
121 lines
7.6 KiB
C
/*
|
||
* COMTRADE 1999 编码:生成 ASCII 配置文件和 BINARY 波形数据。
|
||
* 调用方持有冻结的录波、元数据及全部输出缓冲;本模块不分配内存,
|
||
* 不操作文件系统、平台时钟或通信链路。文件保存与 TI=210 传输由上层负责。
|
||
*/
|
||
#ifndef IEC60870_COMTRADE_H
|
||
#define IEC60870_COMTRADE_H
|
||
|
||
#include "IEC60870_FaultRecorder.h"
|
||
#include "IEC60870_Time.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* BAY08_0010_20141114_192135_830.cfg 共 34 字符,另留结尾 NUL;不含目录前缀。 */
|
||
#define IEC60870_COMTRADE_FILENAME_CAPACITY 35U
|
||
#define IEC60870_COMTRADE_TEXT_MAX 64U
|
||
#define IEC60870_COMTRADE_NUMBER_MAX 13U
|
||
|
||
/* 工程量 = multiplier * DAT 整数值 + offset。
|
||
* 系数用十进制 ASCII 字符串传入,避免区域设置影响小数点和目标端浮点 printf。
|
||
* 允许正负号、小数点及 e/E 指数;尾数至少一位数字,总长不超过 13 字符,
|
||
* 指数绝对值不超过 99。multiplier 必须非零,primary/secondary 必须为正数。
|
||
* 通道顺序固定为 Ua/Ub/Uc/U0(V)、Ia/Ib/Ic/I0(A),对应录波帧 analog[]。
|
||
* 'P' 表示换算后为一次量,'S' 表示二次量;primary/secondary 描述变比。
|
||
* DAT 的 -32768 保留为缺测标记,有效数值范围为 -32767..32767。
|
||
* 本模块按原值编码,不限幅,也不把无符号 ADC 计数自动转换成电气量。 */
|
||
typedef struct {
|
||
const char *multiplier, *offset, *primary, *secondary;
|
||
char primary_or_secondary;
|
||
} IEC60870_ComtradeAnalog_t;
|
||
|
||
typedef struct {
|
||
const char *station, *device; /* 非空可打印 ASCII,最长 64 字符,禁止逗号。 */
|
||
IEC60870_ComtradeAnalog_t analog[IEC60870_FAULT_RECORDER_ANALOG_COUNT];
|
||
/* 两数组均按录波的 digital_count 提供元素,顺序对应遥信位顺序。
|
||
* 名称数组为 NULL 时生成 D1..D64;常态数组为 NULL 时各通道常态均为 0。
|
||
* 名称限制与 station 相同;常态只能为 0 或 1。这些指针均不转移所有权。 */
|
||
const char *const *digital_names;
|
||
const uint8_t *digital_normal;
|
||
/* 捕获触发时刻后保持不变,采用项目本地标准时间 UTC+8,IV=0、SU=0。
|
||
* COMTRADE 1999 的日期行不含时区,接收端须按相同时间口径解释。
|
||
* trigger_microseconds 仅补足 CP56 毫秒以下的余数,不是整秒内微秒数。 */
|
||
IEC60870_CP56Time2a_t trigger_time;
|
||
uint16_t trigger_microseconds; /* 毫秒以下的 0..999 微秒。 */
|
||
} IEC60870_ComtradeConfig_t;
|
||
|
||
/**
|
||
* 功能:设置默认标识、单位比例系数/变比和自动遥信名;config=NULL 时无操作。
|
||
* 输入参数:无。
|
||
* 输出参数:config——写入默认配置;NULL时不操作。
|
||
* 返回值:无。
|
||
* 说明:触发时间仍为无效状态,调用方必须填写实际捕获的时间后才能生成 CFG。
|
||
*/
|
||
void IEC60870_Comtrade_Config_Default(IEC60870_ComtradeConfig_t *config);
|
||
|
||
/**
|
||
* 功能:根据 READY 状态的冻结录波生成 CFG;成功返回 true,失败返回 false。
|
||
* 输入参数:recorder——冻结录波源;config——配置及调用期间借用的元数据;capacity——缓冲可用容量。
|
||
* 输出参数:buffer——可选CFG缓冲;容量足够且预检通过后写入文本和终止NUL;length——成功写入不含NUL的CFG长度。
|
||
* 返回值:true表示CFG长度查询或完整生成成功;false表示输入、格式边界或容量校验失败。
|
||
* 说明:输出为 ASCII、CRLF 换行、无 BOM,末尾附加 NUL;length 不含 NUL, 保存文件时只写 length 字节。buffer=NULL 且 capacity=0
|
||
* 可查询所需长度, 实际输出容量必须大于该长度。失败不改输出及 length。 调用期间借用全部元数据,元数据和录波必须保持不变;输入、输出不得重叠。 固定为单采样率、BINARY、时标倍率
|
||
* 1;首点时间 = 触发时间减去 trigger_index/rate。小数微秒四舍五入,CFG 起始/触发时刻和 DAT 时标 采用同一舍入规则,因此不能另用“当前时间”代替冻结的触发时间。
|
||
* 拒绝超过 1 MHz 的采样率、超出 uint32 的 DAT 长度、达到保留缺测时标 0xffffffff 的时间偏移、非法元数据/日期和落在 2000..2099 以外的首点。
|
||
* 不支持闰秒。
|
||
*/
|
||
bool IEC60870_Comtrade_Build_CFG(const IEC60870_FaultRecorder_t *recorder,
|
||
const IEC60870_ComtradeConfig_t *config, char *buffer, size_t capacity,
|
||
size_t *length);
|
||
|
||
/**
|
||
* 功能:返回 DAT 的精确字节数;只需不可变的 READY 录波,不依赖 CFG 元数据。
|
||
* 输入参数:recorder——冻结录波源。
|
||
* 输出参数:size——非NULL长度输出;成功写入DAT总字节数,失败保持原值。
|
||
* 返回值:true表示DAT长度已计算;false表示录波未就绪、格式边界或输出指针非法。
|
||
* 说明:成功返回 true 并写 size,失败返回 false 且不改 size。
|
||
*/
|
||
bool IEC60870_Comtrade_Data_Size(const IEC60870_FaultRecorder_t *recorder,
|
||
uint32_t *size);
|
||
|
||
/**
|
||
* 功能:从任意字节 offset 开始编码恰好 length 字节,允许在一条采样记录内部开始 或跨多条记录,便于 TI=210 分段读取及重复读取同一偏移。
|
||
* 输入参数:recorder——冻结录波源;offset——文件或映像内的字节偏移;length——字节数。
|
||
* 输出参数:buffer——编码或复制结果的目标字节区。
|
||
* 返回值:true表示请求字节范围已复制;false表示录波、范围或目标缓冲无效。
|
||
* 说明:成功返回 true。 每条记录依次为:4 字节点号(从 1 开始)、4 字节相对首点的微秒时标、 8 个 int16 模拟量、向上取整(digital_count/16) 个 uint16
|
||
* 遥信字。 多字节字段均为小端;遥信 1 对应首字最低位,末字未使用位清零。 offset==文件大小且 length==0 合法;其他请求必须整体处于文件范围内, 不自动补齐 EOF。
|
||
* length 非零时 buffer 不得为 NULL。 从 CFG/DAT 读取开始直到应用最后关闭文件,录波必须保持 READY 且不变, 不得提前 Release。
|
||
* 输出不得与录波对象/帧存储重叠;非法参数不改输出。
|
||
*/
|
||
bool IEC60870_Comtrade_Read_DAT(const IEC60870_FaultRecorder_t *recorder,
|
||
uint32_t offset, uint8_t *buffer, size_t length);
|
||
|
||
/**
|
||
* 功能:生成不含目录的 BAY 文件名,data_file=true 选 .dat,否则选 .cfg。
|
||
* 输入参数:bay——间隔编号;sequence——顺序号;trigger_time——触发日历;data_file——true生成DAT名称,false生成CFG名称;capacity——缓冲可用容量。
|
||
* 输出参数:buffer——编码或复制结果的目标字节区。
|
||
* 返回值:true表示文件名已完整生成;false表示参数非法或容量不足,输出不变。
|
||
* 说明:bay=1..99、sequence=1..9999,名称精确到触发时刻的毫秒;同一对文件须 使用相同参数。调用方负责按间隔持久化序号、检查重名和添加 COMTRADE 目录。 成功返回
|
||
* true;非法时间/参数或容量不足返回 false 且不改 buffer。
|
||
*/
|
||
bool IEC60870_Comtrade_File_Name(uint8_t bay, uint16_t sequence,
|
||
const IEC60870_CP56Time2a_t *trigger_time, bool data_file,
|
||
char *buffer, size_t capacity);
|
||
/**
|
||
* 功能:序号 9999 的下一值为 1;输入 0 或大于 9999 时返回 0 表示非法输入。
|
||
* 输入参数:sequence——顺序号。
|
||
* 输出参数:无。
|
||
* 返回值:1..9999循环序号的下一值;9999回到1,0或大于9999的非法输入返回0。
|
||
* 说明:此函数只计算下一值,不保存序号,也不保证对应文件名尚未使用。
|
||
*/
|
||
uint16_t IEC60870_Comtrade_Next_Sequence(uint16_t sequence);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* IEC60870_COMTRADE_H */
|