Files
STM32F4-Base/IEC60870-Slave/common/IEC60870_Comtrade.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

121 lines
7.6 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.
/*
* 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 */