Files
STM32F4-Base/App/protocol/iec60870/104/business/IEC104_Command.h
T
wandering1 90cc9a7d99 feat(iec104): 把 104 骨架完整迁到 MCU 板端并在台架跑通总召
把 IEC104 从模拟器端整体搬到板端:协议栈原先由独立 iec104Task 驱动,
现在改为 netTask 单 owner 的 threadless 驱动,退役独立任务。

驱动与后端:
- 新增 iec104_net_mcu.c/.h,实现 IEC104_Net.h 的 11 个 ABI 函数,
  用槽表加单调句柄映射 net_socket 的单 fd 模型;CLIENT 拆除只走
  net_drop_conn_locked,绝不 net_close 监听 fd。
- net_socket 增 5 个 owner-only 接口(net_accept_locked、
  net_drop_conn_locked、net_pending_bytes、net_send_try、
  net_mono_now_ms)。
- iec104_serv.c 重写为 iec104_serv_net_tick(),在 netTask 1ms 主循环
  里驱动 core;无 osDelay/阻塞调用,喂狗是第一句。
- Src/freertos.c 删除 iec104Task 三件套,对应栈水位探针表项同步删除。

内存:目标板 192KB SRAM 装不下 vendor 默认容量档,按实测裁剪到
skeleton 档(TCP 缓冲、业务池、SOE 256->128、值槽密集化),
RW_IRAM1 118,408 B / 90.3%,留 2,178 B 余量。

台架修复(只在真硬件暴露):
- SNTP s_ctx.fd 零初始化后为 0,而 net fd 0 是合法槽位下标,
  首次代次变化时误 net_close(0) 关掉 ftpTask 的监听槽,导致 104
  连接被 FTP 的 220 banner 抢走;改为显式 .fd = -1。
- Accept 幂等:单 fd 模型下 vendor 每轮重试 Accept 会拿到同一 fd,
  后端改为会话在役时返 WOULD_BLOCK,Close 不再清槽。

验证:
- Keil 全量重建 0 error 0 warning,uvprojx 零抖动。
- 模拟器真实 TCP 13/13、transport 10/10。
- netmcu 后端单测 13/13(新增 N12)。
- 台架 serial-boot-test required 全中;板端 2404 总召 129 帧收到
  59 遥信(53 有源、全 IV)+ 16 双点 + 30 遥测(PT1 三相非零、
  UN/频率/温度按未标定置 IV)、遥控选择执行全否定、校时 COT 7。
- 期间顺带修正 UI 漂移自检文案、.serialtest required 陈旧项、
  coding-standard 对 vendor 与外部 ABI 名字的排除口径。
2026-11-18 10:29:18 +08:00

529 lines
43 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.
/*
* 模块:IEC104控制命令业务层,45..51及58..64,COT=6激活、COT=8撤销。
* 职责:校验请求、选择/执行匹配、撤销、阶段期限、原文确认和事务收尾。
* 状态命令QU仅接受0..3,设定值QL仅接受0;51/64无此字段。未支持的限定词独立否定,
* 不改变既有事务;公共编解码仍保留完整位域,应用还须拒绝设备未实现的输出方式。
* 点表、闭锁、远方/就地策略及实际输出由应用负责;本模块不判定设备操作是否安全。
* 每个Slave至多一个实例,每实例至多一个未释放事务;其他业务仍独立推进。
* 静态存储、无动态分配、不保存回调;所有入口须与Slave在同一事件循环串行调用。
* 只有Accept调用应用动作,先消费事件、再至多调用一次;Handle_Event/Process不调用应用。
* 返回信息由Submit_Return_Info沿原连接HIGH提交,确认/返回信息/终止保持FIFO顺序。
* TEST=1仅演练协议:合法选择回肯定ACT_CON,匹配执行/直接执行回肯定ACT_CON及ACT_TERM,
* 匹配撤销回肯定DEACT_CON;全部保留T位,不交付应用事件、不调用动作、不产生返回信息。
* 测试与真实请求共用唯一事务槽,T位参与匹配;槽被另一种请求占用时独立忙否定,不能接管原选择。
* TEST仍检查点表、类型/模式、QU/QL、时标及SBO匹配;时标过期始终否定,无静默选项。
*
* 接入顺序:先Create,再按Slave通知FIFO分派Handle_Event;每轮Process后读空NextEvent。
* SELECT/EXECUTE事件由Accept或Reject消费;EXECUTE启动成功后,先Report_Result,
* 再逐帧Submit_Return_Info,全部OK后Complete;最终读取FINISHED清理应用资源。
* Report_Result也可晚于返回信息,但必须早于Complete,且设备结果产生后应及时报告。
* 固定执行收尾:SUCCEEDED后Complete回肯定ACT_TERM,FAILED后Complete回否定ACT_TERM。
* 等待执行结果超时由模块自动安排否定ACT_TERM并立即FINISHED(EXECUTE_TIMEOUT),结果仍未知。
* 该超时不关闭TCP;应用仍须驱动Process/网络发送残留回复,并独立维护实际设备的忙状态。
* WAIT表示本次应用操作尚未接手,保留输入并在读取通知/推进网络后重试;OK不得重复提交。
* 动作/确认/设备结果/FINISHED是不同节点:FINISHED只结束协议事务,不撤销物理输出。
* STOP、断线或Cancel不回滚动作,也不把原连接的返回信息转交到新连接。
* 提交OK表示发送层已复制;正常FINISHED还要等事务尾进入SendBuffer,不等待ACK。
* FINISHED.return_info_undelivered在结束时冻结;Cancel不撤回已入HIGH的帧,保守补报可能重复。
*
* 退出顺序:Cancel、读完FINISHED、Slave_Close、读空并分派通知、Destroy,
* 然后由应用移除站点并销毁Slave。模块不负责Slave或应用持有引用的释放。
*/
#ifndef IEC104_COMMAND_H
#define IEC104_COMMAND_H
#include "IEC104_Slave.h"
#include "IEC60870_Time.h"
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/* 不透明静态池句柄;Destroy成功后失效,不得按值复制内部对象或继续使用旧指针。 */
typedef struct IEC104_Command IEC104_Command_t;
/* 供无副作用的类型常量使用;45..51映射bit0..6,58..64映射bit7..13。
* 范围外为0,不作非法移位。Create接受全部14位,默认全部启用。 */
#define IEC104_COMMAND_TYPE_BIT(type) ((uint16_t)( \
((type) >= 45U && (type) <= 51U) ? (1U << (((type) - 45U) & 15U)) : \
(((type) >= 58U && (type) <= 64U) ? (1U << (((type) - 51U) & 15U)) : 0U)))
/* 点级执行方式;0为非法值,必须显式选定一种方式。51/64仅允许DIRECT。 */
typedef enum {
IEC104_COMMAND_MODE_DIRECT = 1, /* 只接受直接执行,选择请求回否定确认。 */
IEC104_COMMAND_MODE_SELECT_EXECUTE /* 须先选择,执行必须匹配仍有效的本事务选择。 */
} IEC104_CommandMode_t;
/* 同一IOA仅一项;按ioa严格升序排列,Create校验、受理时二分查找。
* 表由应用拥有,从Create到Destroy须保持有效且只读;可放在静态const存储中。
* 库不复制点表、不持有设备指针。动态闭锁、权限和数值限值仍由应用在Accept前判断。
*
* 公共地址不逐点存储:实例的站点CA即表的CA(自Create起恒定)。
* 因此一张点位相同的表可被不同CA的实例共用,不必按CA复制。
* [vendor 兼容补丁] ARM Compiler 5 下 uint16_t 为2字节对齐,
* 去掉 common_address 后本结构由12字节降到8字节。 */
typedef struct {
uint32_t ioa; /* 1..0xFFFFFF,控制点地址。 */
uint16_t type_mask; /* 非零,限14种已知类型;实际可用类型与全局type_mask取交集。 */
IEC104_CommandMode_t mode; /* 此点所有允许类型共用同一种执行方式。 */
} IEC104_CommandPoint_t;
/* 创建时按值复制的配置,但points所指数组仍借用,不能在实例存活期间修改或释放。
* 期限以Net单调时钟计算,等于边界即到期;
* 决定/执行期限为0仅禁用时长限制,等待阶段遇到时钟倒退仍终结;选择期限必须非零。
* Report_Result后计完成期限,Complete后计交接期限;提前ENDED的残留回复也限时清理。
* 新增两项期限为0时,同时禁用该阶段的超时及计时回退处理;FINISHED仍须应用读取。 */
typedef struct {
uint16_t type_mask; /* 默认启用45..51、58..64全部14种;应用可裁剪,不能为空。 */
/* 选择保持上限,单位ms,默认30000且不得为0;同实例所有选择执行点共用。
* 选择动作返回STARTED(含NULL选择)后计时,包含选择确认的发送等待;
* 匹配执行被Handle_Event受理即停止,随后进入决定期限,不必等满此时长。
* 自动选择后紧接执行可用10000作为联调起点,人工确认可保留30000;
* 应结合主站流程及通信/调度余量在Create前确定。保持期间占唯一事务槽。
* DIRECT点不进入选择保持;此参数与命令时标时差time_tag_max_delay_ms独立。 */
uint32_t select_timeout_ms;
/* 工作事件生成至Accept/Reject的阶段上限,默认15000;0禁用时长限制。
* 不保证此期间始终可执行:带时标命令在Accept前仍须满足time_tag_max_delay_ms。
* 两个数值都是可配置的工程默认,不能用决定期限替代命令的新鲜度检查。 */
uint32_t decision_timeout_ms;
uint32_t execute_timeout_ms; /* 动作STARTED至Report_Result,默认60000;0禁用时长限制。
* 到期/时钟回退安排否定ACT_TERM,结果仍未知,不关闭连接。 */
uint32_t complete_timeout_ms; /* Report_Result返回OK至Complete,成功/失败结果均适用;默认30000。
* 到期不发ACT_TERM:应用仍须在期限内显式声明返回信息阶段结束。 */
uint32_t handover_timeout_ms; /* Complete至最后应答交接,默认60000;也用于ENDED残留回复清理。
* 执行超时安排TERM后,从进入ENDED另起清理期限;读取FINISHED或发送WAIT不刷新。 */
uint32_t time_tag_max_delay_ms; /* 默认10000;0只关闭时差检查,仍拒绝IV=1/UTC换算失败。 */
int16_t master_utc_offset_minutes; /* 主站标准时区,默认480,范围-1439..1439;SU另由公共层处理。 */
bool negative_on_expired; /* TEST=0默认true否定COT49,受理/动作前均适用;false静默。TEST始终否定。 */
const IEC104_CommandPoint_t *points; /* 按IOA排序的只读点表,默认NULL;模式由各点决定。 */
size_t point_count; /* 点数,默认0;须与points同时为空或同时非空。 */
} IEC104_CommandConfig_t;
/* 可按值保存的请求快照;不含站点/ASDU等借用指针。
* state为单命令0/1、双命令1/2、步调节1降/2升;具体操作含义由应用点表定义。
* accepted_ms为Handle_Event受理时刻,不是网络接收时间;决定计时不含此前Slave通知排队时间。 */
typedef struct {
uint64_t generation, receive_serial; /* 原连接代次、当前工作请求的I帧接收编号。 */
uint64_t station_id; /* 站点注册身份;同CA重新注册后此值不同。 */
uint16_t common_address; /* 请求公共地址CA,不接受广播65535。 */
uint8_t originator_address, type_id; /* 请求源发地址OA、类型45..51或58..64。 */
uint32_t ioa; /* 非零24位信息对象地址;已通过配置点表的许可检查。 */
bool is_select, selected; /* S/E及本事务匹配选择标志;51/64两者恒为false。 */
uint8_t state, qualifier; /* 基础45..47:状态/QU(0..3);48..50:0/QL(仅0);51:0/0。 */
union {
int16_t normalized; /* 48/61:原始定点编码,实际值为normalized/32768.0。 */
int16_t scaled; /* 49/62:有符号标度值。 */
float short_float; /* 50/63:有限IEEE 754 binary32。 */
uint32_t bitstring; /* 51/64:32位数据,不包含选择位。 */
} value; /* 按type_id读取;状态命令清零。 */
bool has_time; /* 58..64为true,字段含义与对应基础类型相同。 */
IEC60870_CP56Time2a_t time; /* 解码后的原始时标,保留IV/SU,不是可直接发送的字节布局。 */
uint64_t time_utc_ms; /* UTC纪元毫秒,含毫秒余数;无时标为0。Accept动作前复查时差。 */
uint64_t accepted_ms; /* 当前工作请求受理时的单调毫秒。 */
} IEC104_CommandRequest_t;
/* SELECT和EXECUTE为待决定工作事件;FINISHED仅通知清理,无需应答。 */
typedef enum {
IEC104_COMMAND_SELECT = 1, /* 应用检查策略并Accept/Reject选择,可执行返校动作。 */
IEC104_COMMAND_EXECUTE, /* 应用Accept/Reject执行;selected区分选择后执行和直接执行。 */
IEC104_COMMAND_FINISHED /* 该事务唯一的结束通知,原因及副作用标志在事件中给出。 */
} IEC104_CommandEventType_t;
/* 首次结束时冻结,后续STOP/Cancel不会覆盖;枚举不表示设备输出已停止。 */
typedef enum {
IEC104_COMMAND_FINISH_NONE = 0, /* 工作事件的占位值,不是FINISHED的正常原因。 */
IEC104_COMMAND_FINISH_COMPLETED, /* 应用报告成功,Complete后最后应答已交接。 */
IEC104_COMMAND_FINISH_EXECUTION_FAILED, /* 输出已启动,但应用报告失败,协议收尾已交接。 */
IEC104_COMMAND_FINISH_REJECTED, /* 应用Reject,或动作返回NOT_STARTED。 */
IEC104_COMMAND_FINISH_ACTION_FAILED, /* 动作返回FAILED/非法值,可能存在副作用。 */
IEC104_COMMAND_FINISH_MISMATCH, /* 选择确认被接手后,同一点执行的类型/OA/值/限定词不符。 */
IEC104_COMMAND_FINISH_DEACTIVATED, /* 主站COT=8成功撤销尚未启动执行的事务。 */
IEC104_COMMAND_FINISH_SELECT_TIMEOUT, /* 选择保持到期,释放选择,已被发送层接手的确认无法撤回。 */
IEC104_COMMAND_FINISH_DECISION_TIMEOUT, /* 未及时Accept/Reject,模块安排否定确认。 */
IEC104_COMMAND_FINISH_EXECUTE_TIMEOUT, /* 未及时Report_Result,结果未知;安排否定TERM,连接继续运行。 */
IEC104_COMMAND_FINISH_CANCELLED, /* 本地Cancel结束事务。 */
IEC104_COMMAND_FINISH_STOPPED, /* 原连接STOPDT停用。 */
IEC104_COMMAND_FINISH_DISCONNECTED, /* 原连接断开。 */
IEC104_COMMAND_FINISH_CONNECTION_CHANGED, /* 新连接代次或会话身份已失效。 */
IEC104_COMMAND_FINISH_SEND_ERROR, /* 发送ERROR/FATAL,且不是等待分派正常STOP通知。 */
IEC104_COMMAND_FINISH_SERVICE_ERROR, /* Slave服务错误或内部身份/应答资源无法继续使用。 */
IEC104_COMMAND_FINISH_COMPLETE_TIMEOUT, /* 已报告结果,未在期限内Complete;不安排ACT_TERM。 */
IEC104_COMMAND_FINISH_HANDOVER_TIMEOUT, /* Complete后必要回复仍未交接;已入HIGH的帧不撤回。 */
IEC104_COMMAND_FINISH_TIME_EXPIRED, /* Accept动作前复查时标已过期,未调用本次动作。 */
IEC104_COMMAND_FINISH_TIME_REJECTED, /* Accept动作前基准不可用、回退、越界或时标超前。 */
IEC104_COMMAND_FINISH_DUPLICATE_SELECT /* 同点合法重复选择终结旧选择,否定确认针对新请求。 */
} IEC104_CommandFinishReason_t;
/* 事件是可保存的纯值,应答须原样传回;调用方不能用修改request改变实际执行内容。
* 任何工作事件曾被取走的事务,恰好交付一次FINISHED;后者无需应答。
* 应用跨循环持有站点/context或异步动作时,应在首个工作事件时自行Acquire,
* FINISHED清理且物理输出确已结束后Release,不能等读到FINISHED后才申请引用。 */
typedef struct {
IEC104_CommandEventType_t type; /* 决定事件的处理方式,参与身份校验。 */
uint64_t instance_id, transaction_id, event_serial; /* 实例、事务、事件三层身份,原样回传。 */
IEC104_CommandRequest_t request; /* 最后接纳的工作请求,不被撤销/不匹配请求覆盖。 */
IEC104_CommandFinishReason_t reason; /* 仅FINISHED有效;工作事件为NONE。 */
bool select_effect, execute_effect; /* 仅FINISHED有效:对应动作曾STARTED/FAILED,可能需清理。 */
bool return_info_undelivered; /* 仅FINISHED有效:有已接手返回信息尚未进入SendBuffer或无法确认。
* 结束时冻结;不涵盖应用尚未提交OK的帧,不表示对端是否收到。 */
} IEC104_CommandEvent_t;
typedef enum {
IEC104_COMMAND_ACTION_NOT_STARTED = 0, /* 必须保证没有任何副作用。 */
IEC104_COMMAND_ACTION_STARTED, /* 选择生效或输出启动;输出结果另行报告。 */
IEC104_COMMAND_ACTION_FAILED /* 未报告启动成功,但可能已留下副作用。 */
} IEC104_CommandActionResult_t;
/* Accept同步调用的动作,不保存函数/context指针。
* context为应用传入的上下文,可为NULL;request由模块内部快照构造,仅本次调用有效。
* 须短时返回,不得保存request指针、推进Slave或发布上报;设备的异步完成用Report_Result报告。
* 回调期间仅可Get_Status/Get_Transaction;其他修改入口拒绝重入。
* 返回值须准确说明是否有副作用,非法值按FAILED处理,模块不会重试动作。 */
typedef IEC104_CommandActionResult_t (*IEC104_CommandAction_t)(void *context,
const IEC104_CommandRequest_t *request);
typedef enum {
IEC104_COMMAND_RESULT_SUCCEEDED = 1, /* 启动后设备实际执行成功。 */
IEC104_COMMAND_RESULT_FAILED /* 启动后设备实际执行失败,不等同于拒绝启动。 */
} IEC104_CommandResult_t;
typedef enum {
IEC104_COMMAND_REJECT_NEGATIVE = 1, /* 通用策略拒绝,回COT=7、P/N=1。 */
IEC104_COMMAND_REJECT_UNKNOWN_IOA, /* 点表不存在此IOA,回COT=47、P/N=1。 */
IEC104_COMMAND_REJECT_INTERLOCK, /* 应用确认遥控执行软压板状态错误,回COT=48、P/N=1。 */
IEC104_COMMAND_REJECT_TIME /* 应用确认遥控执行时间戳错误,回COT=49、P/N=1。 */
} IEC104_CommandRejectCause_t;
typedef enum {
IEC104_COMMAND_EVENT_ERROR = -1, /* 参数/来源/服务错误;不能据此重放已产生的动作。 */
IEC104_COMMAND_EVENT_IGNORED = 0, /* 不接手,I帧可继续交后续处理器。 */
IEC104_COMMAND_EVENT_HANDLED = 1 /* 已接手,包括校验拒绝/计数丢弃,不应再走44兜底。 */
} IEC104_CommandEventResult_t;
typedef enum {
IEC104_COMMAND_NEXT_ERROR = -1, /* 句柄/参数/重入或服务错误,输出未写入。 */
IEC104_COMMAND_NEXT_EMPTY = 0, /* 暂无可交付事件,可能须先读Slave通知;输出未写入。 */
IEC104_COMMAND_NEXT_READY = 1 /* 已交付纯值事件,同一事件不会再次出队。 */
} IEC104_CommandNextResult_t;
/* 以下为共同分类;OK究竟消费事件、记录结果还是接手ASDU,以各接口说明为准。
* WAIT均未接手本次应用输入;Submit_Return_Info的OK表示原文已由HIGH路径接手,不保证相对NORMAL的采集顺序。 */
typedef enum {
IEC104_COMMAND_REPLY_STALE = -2, /* 身份/阶段已失效、事件已消费或事务结束,不得重试旧操作。 */
IEC104_COMMAND_REPLY_ERROR = -1, /* 参数/用法/重入或服务错误,检查接口具体前置条件。 */
IEC104_COMMAND_REPLY_WAIT = 0, /* 等待通知/确认/FIFO/网络,保留输入,推进事件循环后重试。 */
IEC104_COMMAND_REPLY_OK = 1 /* 本次操作已接手;不保证设备成功、网络ACK或FINISHED已就绪。 */
} IEC104_CommandReplyResult_t;
typedef enum {
IEC104_COMMAND_PHASE_SELECT_WAIT = 1, /* 等应用决定选择;决定期限从事件生成开始。 */
IEC104_COMMAND_PHASE_SELECTED, /* 已选择,等待匹配执行;选择确认可能仍未交接。 */
IEC104_COMMAND_PHASE_EXECUTE_WAIT, /* 等应用决定执行;已停止选择期限。 */
IEC104_COMMAND_PHASE_EXECUTING, /* 已启动,等待结果/返回信息/Complete/最后应答交接。 */
IEC104_COMMAND_PHASE_ENDED /* 协议已结束,可能仍保留FINISHED或未交接应答。 */
} IEC104_CommandPhase_t;
typedef struct {
bool active; /* 尚未ENDED;不是当前连接是否可操作的保证。 */
IEC104_CommandPhase_t phase; /* 当前协议阶段;结果报告和Complete不另建阶段。 */
bool confirm_submitted; /* 当前工作请求的确认已交给发送层,不表示写完或ACK。 */
/* result_reported:结果已冻结、执行期限停止;completed:已接手Complete,返回阶段关闭;
* term_submitted:ACT_TERM已被发送层接手;提前取消/断线可能不提交,不能据此等事务结束。
* 执行结果超时会安排TERM,但result_reported和completed仍为false,不伪造应用结果或Complete。 */
bool result_reported, completed, term_submitted;
} IEC104_CommandTransactionInfo_t;
/* 累计计数从Create起维护;查询不改变阶段、不做超时转换。
* busy表示事务槽仍占用,包含待消费FINISHED及模块内待提交应答;正常完成另等尾帧HANDED。
* 提前结束时,已入HIGH的帧可在槽释放后继续交接;独立短应答不占事务槽。
* need_process不因发送WAIT持续置true;每轮网络推进后仍须Process重试。
* 计数用途是诊断,不是可靠账单;各计数可重叠,unsigned long到达上限后自然回绕。 */
typedef struct {
uint64_t generation; /* 当前已分派的连接代次,断线后为0。 */
/* active:模块已处理ACTIVATED且尚未停用,不代替操作前的实时会话校验;
* events_pending:须优先读取Slave通知;need_process:有可立即推进的内部工作;
* timer_active:当前启用了非零时长期限;原决定/选择/执行阶段另检查时钟倒退。
* 完成/交接/ENDED清理阶段仅在对应期限非零时检查回退。 */
bool active, events_pending, need_process, timer_active;
bool busy; /* 唯一事务槽仍占用,此时其他站点/其他IOA也不能新建事务。 */
bool time_base_valid; /* 持有时间基准;不表示推算时尚未越界,STOP/断线不清除。 */
/* 当前阶段期限剩余毫秒;无期限/已到期/时钟倒退时为0。
* 不表示命令时标还有效多久,也不保证Accept可执行;查询不做动作前时效判断。 */
uint32_t timeout_remaining_ms;
/* pending_replies为模块仍持有的应答数,不含发送层已接手的帧和应用保留的返回信息;
* pending_events为尚未取走的工作事件或FINISHED数,本版最多1。 */
unsigned pending_replies, pending_events;
/* accepted:受理的选择/执行数(选择后执行计两次,含无应用事件的TEST);
* selected/executed:真实应用路径对应STARTED次数,TEST不增加;
* completed/execution_failed:协议成功/失败收尾数,completed含TEST;action_failed:动作FAILED结束数。 */
unsigned long accepted, selected, executed, completed, execution_failed, action_failed;
/* submitted:所有已被发送层接手的帧,含返回信息;negative_submitted:其中P/N=1的应答;
* return_info_submitted:已接手返回信息;waits:发送接口明确返回WAIT的次数。 */
unsigned long submitted, negative_submitted, return_info_submitted, waits;
unsigned long return_info_undelivered; /* 结束时有未确认交接返回信息的事务数,非ASDU数量。 */
/* rejected:接收校验/点策略/匹配/忙/无选择/重复选择等拒绝数;app_rejected:Reject或NOT_STARTED数;
* busy_rejected:因事务槽占用拒绝数;overloads:独立应答池满或事务/事件序号耗尽次数;
* dropped_requests:过载丢新数及决定期间同OA同点激活的静默丢弃数(不含选择阶段的重复选择),
* 静默不计rejected/busy_rejected/overloads;重复选择复归只计rejected,不计busy_rejected/cancelled;
* cancelled:本地取消、停用、断线、换代、发送/服务错误导致的事务结束总数。 */
unsigned long rejected, app_rejected, busy_rejected, overloads, dropped_requests, cancelled;
/* deactivated:成功撤销数;mismatches:选择失配数;其余三个为各期限导致的结束数。 */
unsigned long deactivated, mismatches, select_timeouts, decision_timeouts, execute_timeouts;
/* 事务期限或时间基准检查发现单调时钟倒退的次数;两个检查的计数可能重叠。 */
unsigned long clock_errors;
unsigned long time_expired; /* 过期激活或TEST撤销;真实激活静默时不计rejected,否定时另计rejected。 */
unsigned long time_rejected; /* CP56编码/IV/换算/基准/倒退/推算/超前错误;同时计rejected,不含过期。 */
unsigned long complete_timeouts, handover_timeouts; /* 两种新增收尾原因,不计completed。 */
unsigned long dropped_replies; /* 新期限清理时丢弃的本事务模块回复帧数,不含已进HIGH的帧。 */
unsigned long action_time_expired, action_time_rejected; /* Accept复查失败,不混入受理时标计数。 */
unsigned long confirm_room_waits; /* Accept确认容量不足次数,不混入发送接口waits。 */
} IEC104_CommandStatus_t;
/**
* 功能:填写本版默认配置:全局启用45..51、58..64,点表为空;应用须配置具体点才能接收工作事件。
* 输入参数:config为输出结构;NULL时无操作。
* 输出参数:启用全部14种类型,点表为空;选择/决定/执行期限为30000/15000/60000毫秒,
* 完成/交接(及清理)期限为30000/60000毫秒,
* 收尾规则固定:成功肯定ACT_TERM,报告失败后Complete或执行结果超时否定ACT_TERM。
* 返回值:无。
* 说明:决定15s、选择30s、执行60s、完成30s、交接/清理60s。
* 成功肯定ACT_TERM,报告失败后Complete或等待执行结果超时否定ACT_TERM;业务超时不关闭连接。
* 时标窗口10s,主站时区UTC+8,过期激活默认安排否定COT49;仅TEST=0可显式关闭。
* 选择30s为可调整的工程默认;应用可在本函数之后、Create之前修改select_timeout_ms。
* 默认启用带时标类型;受理前须设置可信时间基准,或显式关闭时差检查。
* 入参:config为调用方可写结构;NULL时无操作。返回:无;不创建实例或启动计时。
*/
void IEC104_Command_Config_Default(IEC104_CommandConfig_t *config);
/**
* 功能:从静态池创建并绑定一个遥控实例;不自动开启Slave或消费其通知。
* 输入参数:slave为有效服务句柄,寿命覆盖本实例;config按值复制,但其中点表借用至Destroy。
* 输出参数:成功时初始化空事务、空回复池和零统计,不建立网络监听,也不调用应用代码。
* 返回值:成功为实例句柄;配置/点表/Slave非法、重复绑定、池或实例身份序号耗尽时为NULL。
* 说明:入参:slave为有效Slave,寿命须覆盖实例;config非NULL,按值复制,调用后可修改原结构;
* 但config->points数组仍借用,须直到Destroy成功都有效且不可变,不能传短命局部数组。
* 必须在开始消费Slave通知之前创建,以完整接收CONNECTED/ACTIVATED。
* 池容量IEC104_COMMAND_CAPACITY默认等于TCP服务容量;独立应答容量
* IEC104_COMMAND_REPLY_CAPACITY默认4,均在编译模块时通过宏配置。
* points=NULL且point_count=0表示合法空表;已启用类型的新激活通过前序校验后回未知IOA。
* 非空表须按CA/IOA严格升序且唯一;CA/IOA、类型掩码、mode须合法,51/64不得配置为选择执行。
* 点类型掩码可含全局未启用的已知类型,但不能绕过全局type_mask;没有隐式默认点或通配点。
* 点表不支持运行时更新;修改策略须停服并取消收尾、Destroy,再以新表Create。
* 重建后须重新建立连接并完整分派CONNECTED/ACTIVATED,且重新设置时间基准,不继承旧实例会话。
*/
IEC104_Command_t *IEC104_Command_Create(IEC104_Slave_t *slave, const IEC104_CommandConfig_t *config);
/**
* 功能:设置可信站内时间基准;utc_ms为UTC纪元毫秒,base_ms为同一时刻的Net单调毫秒。
* 输入参数:self——本模块实例。
* utc_ms——UTC毫秒时刻。
* base_ms——单调时间基准。
* 输出参数:self——本模块实例的更新结果。
* 返回值:!Owned(self) || self->in_action || utc_ms > COMMAND_MAX_UTC_MS || base_ms > IEC104_Net_Now_Ms()时返回false;其余分支返回false、true。
* 说明:不读Clock、不保存回调;影响激活受理及Accept动作前复查,STOP/断线保留基准。
* 句柄无效、动作回调内、utc_ms超出TIME_MAX_SECONDS*1000+999或base_ms晚于当前Net时间时
* 返回false且保留原基准;成功返回true。允许尚未激活或离线时设置。
* max非零时,Accept通过决定期限和旧回复门禁后再次检查;时标到期不得启动动作。
*/
bool IEC104_Command_Set_Time_Base(IEC104_Command_t *self, uint64_t utc_ms, uint64_t base_ms);
/**
* 功能:本站时间不可信时清除基准;不取消已受理事务。无效句柄或动作回调内无操作。
* 输入参数:self——本模块实例。
* 输出参数:self——本模块实例的更新结果。
* 返回值:无。
* 说明:后续受理及Accept复查使用新状态。
*/
void IEC104_Command_Clear_Time_Base(IEC104_Command_t *self);
/**
* 功能:归还静态实例槽;不隐式Cancel,不关闭Slave,也不代替应用释放站点引用。
* 输入参数:self为待销毁句柄。
* 输出参数:成功清零实例;不隐式Cancel、不读取FINISHED、不关闭Slave。
* 返回值:成功true,句柄随即失效;条件不满足或句柄无效为false,实例保留。
* 说明:入参:self为待销毁实例;事务槽、未读事件及全部独立应答槽必须均空,且不在动作回调内。
*/
bool IEC104_Command_Destroy(IEC104_Command_t *self);
/**
* 功能:本地结束事务,原因CANCELLED;保留欠应用的FINISHED,清空模块尚持有的全部应答。
* 输入参数:self为实例句柄;无效句柄或动作回调中调用时无操作。
* 输出参数:活动事务以CANCELLED结束,所有独立回复丢弃;会话激活状态保持,后续仍可接新请求。
* 返回值:无。
* 说明:已交发送层的帧无法撤回;保持会话激活,不回滚物理动作。
* 入参:self为实例;回调中/无效句柄无操作。返回:无;应用仍须读完FINISHED。
* ENDED事务保持首次终结原因,不重复产生FINISHED。
*/
void IEC104_Command_Cancel(IEC104_Command_t *self);
/**
* 功能:接收Slave通知并推进会话/请求状态;不调用应用动作,不保存event或其ASDU借用指针。
* 输入参数:self为实例;event须来自所属Slave的NextEvent或合法Copy_Event副本。
* 输出参数:连接/启停通知更新会话并按原因取消旧事务;I帧交Request处理。
* 返回值:激活且视图可用时接手配置内的控制类型,当前会话状态通知也为HANDLED;
* 未激活的I帧、视图不可用、未接手类型或旧代次通知为IGNORED;
* 参数、来源、重入或服务错误为ERROR。非法请求可否定或丢新计数,HANDLED不表示已应答。
* SELECT_WAIT/SELECTED期间,同会话、同station_id、同IOA、同T的有效重复选择终结旧选择,
* 否定ACT_CON回显新请求;不要求OA/值/QU/类型与旧选择相同,但须通过时标及点策略校验。
* 即首次选择已获肯定确认,再次选择被否定时,首次选择仍会失效,不能继续凭它执行;
* 已被发送层接手的首次肯定确认不会撤回,模块仍持有的旧确认会清除,不另追加ACT_TERM。
* 计rejected,旧事件失效;已投递工作事件的事务交付一次FINISHED(DUPLICATE_SELECT)。
* 否定使用事务自带回复,WAIT或独立短回复池满不阻止旧选择失效;回复/FINISHED收尾后回收槽。
* 应用按FINISHED清理原返校资源;槽回收后须重新选择获准、确认被接手,才能再受理执行。
* EXECUTE_WAIT已受理执行请求,即使设备尚未动作也不按上述选择复归;EXECUTING同样隔离。
* SELECT_WAIT/EXECUTE_WAIT期间,其余同会话、同station_id、同IOA、同T的合法激活按OA区分:
* 同OA静默丢弃,计dropped_requests;不同OA计rejected/busy_rejected,独立否定ACT_CON回显新请求,
* 遵循短回复的WAIT/满槽丢新规则。两者均返回HANDLED,不覆盖原请求/事件、不刷新期限;
* 同OA不比较其余命令字段,此分支仍在时差及点策略之前。格式校验和撤销规则不变。
* 撤销在COT/CA校验后先查点地址:未知IOA回47,已知点无匹配可撤销事务才回否定9;
* 地址错误沿用独立短回复,不取消原事务、不刷新其期限,T/OA及请求对象保持回显。
* QU/QL在同点匹配之前校验:未支持的值独立回否定7/9,不吞成重发、不撤销原选择。
* TEST通过上述校验后自动模拟确认流程,不生成SELECT/EXECUTE/FINISHED事件;
* 测试SBO必须先选择并等确认被发送层接手,执行须匹配T/OA及原命令;异OA执行/撤销不取消测试选择,
* 同T的有效重复选择仍按上述规则复归,TEST不交付FINISHED,且始终与真实事务隔离。
* 新激活通过时标及既有选择匹配后,先查点再查忙:无点回47;点类型/执行模式不符回否定7。
* 点级策略拒绝与全局未知类型不同:已识别类型不因该点禁用而回44。
* 点策略拒绝不建立事务、不生成工作事件/FINISHED,按独立短回复的背压规则交接。
* 对IGNORED的I帧继续分派后续业务,最后由应用兜底;不要对HANDLED再发44。
* 说明:入参:self为实例;event是所属Slave按FIFO取出的通知,须在通知内容仍有效时分派。
* 全部连接/启停通知必须送达;通知消费不受队列里后续WAIT_EVENTS阻挡。
*/
IEC104_CommandEventResult_t IEC104_Command_Handle_Event(IEC104_Command_t *self,
const IEC104_SlaveEvent_t *event);
/**
* 功能:推进会话检查、到期转换、发送队首及事务回收;不调用应用代码。
* 输入参数:self为实例句柄。
* 输出参数:每轮至多推进2*(1+独立回复容量)步;队首WAIT或有待消费通知时立即让出。
* 返回值:true包括无事、背压等待或事务已终结;false为参数/重入或服务错误。
* 发送故障也可能已经转成FINISHED,此函数返回true不代表链路或设备执行成功。
* 执行结果超时安排否定TERM并立即产生FINISHED,不关闭连接、不自动重做设备动作。
* 说明:入参:self为实例;每轮网络/通知处理后调用,最多推进2*(1+独立应答槽数)步。
* 队首WAIT立即让出,不能用紧循环等待发送;需处理Slave通知/网络后再次调用。
*/
bool IEC104_Command_Process(IEC104_Command_t *self);
/**
* 功能:取出一条应用事件,同一工作事件最多交付一次;取出不等于Accept/Reject消费。
* 输入参数:self为实例;event为非NULL输出结构,只有READY时改写。
* 输出参数:工作事件交付记录当前和历史交付标志;FINISHED交付清通知义务并尝试释放事务槽。
* 返回值:READY/EMPTY/ERROR,见NextResult;EMPTY也可能表示须先读Slave通知。
* 工作事件交付前检查会话/期限,已有FINISHED可在离线或尚有Slave通知时读取。
* 入口独立检查ENDED残留回复的清理期限;FINISHED已读时也可清理并释放槽,返回EMPTY。
* 读取FINISHED可能立即释放模块的站点引用,应用跨循环引用必须此前已自行Acquire。
* 本次触发执行结果超时即可读取FINISHED,否定TERM仍由Process交接;两者不互相等待。
* 此时事务查询的result_reported/completed仍为false;FINISHED不是设备动作完成证明,
* 设备尚忙时应用须继续保留自己的资源引用,并拒绝会与现有动作冲突的新命令。
* 说明:入参:self为实例;event非NULL,接收可按值保存的事件副本,仅READY时写入。
*/
IEC104_CommandNextResult_t IEC104_Command_NextEvent(IEC104_Command_t *self,
IEC104_CommandEvent_t *event);
/**
* 功能:接受一个已由NextEvent交付的工作事件;先消费身份,再同步至多调用一次action。
* 输入参数:self/event为实例及原工作事件;action/context仅在本次调用借用,不保存。
* SELECT允许action=NULL,表示逻辑选择生效而无硬件副作用;EXECUTE必须提供action。
* 输出参数:先等模块旧回复、复查时标和HIGH容量,再准备确认、消费事件和调用动作。
* 按结果进入选择保持、执行等待结果或ENDED;动作后只提交本次确认。
* 返回值:OK只表示工作事件已消费,不表示动作STARTED或确认已交接;动作失败也返回OK。
* WAIT为未读Slave通知、模块旧回复或HIGH确认空间不足;事件未消费,动作未调用。
* STALE为身份/阶段失效或动作前时标复查终结,不得执行输出;
* ERROR为参数/重入/服务或确认资源错误,动作未调用。
* 动作前检查HIGH能容纳2字节条目头及本次确认;动作后只提交本次确认,不推进旧回复。
* 此容量准入依赖串行调用及回调不修改协议状态;STOP/断线/发送故障仍可能阻止确认。
* 即使action返回STARTED,提交确认时仍可能结束事务;应用应查询事务并继续接收FINISHED。
* 说明:入参:self为实例;event须原样传回SELECT/EXECUTE事件;context原样转交action,不保存。
* SELECT的action可为NULL,选择生效但select_effect=false;EXECUTE必须提供action。
*/
IEC104_CommandReplyResult_t IEC104_Command_Accept(IEC104_Command_t *self,
const IEC104_CommandEvent_t *event, IEC104_CommandAction_t action, void *context);
/**
* 功能:不调用动作,消费工作事件,按指定原因安排否定应答,以REJECTED结束事务。
* 输入参数:self/event为实例和原事件;cause为通用拒绝、未知IOA、软压板状态错误或时间戳错误。
* 输出参数:以当前工作请求否定回显7/47/48/49,计app_rejected并产生FINISHED(REJECTED)。
* 返回值:OK表示事件已消费且应答已安排,可能已提交或因随后故障被取消;
* WAIT未消费、须先处理通知;STALE身份/阶段已失效;ERROR参数/原因/重入或服务错误。
* FINISHED可先于否定应答交接,读取FINISHED不代表槽已释放。
* 说明:event为尚未消费的SELECT/EXECUTE;cause使用RejectCause枚举,不直接传线上的COT值。
* 软压板状态由应用确认;显式时间拒绝不受过期静默配置影响,不增加自动时标检查计数。
*/
IEC104_CommandReplyResult_t IEC104_Command_Reject(IEC104_Command_t *self,
const IEC104_CommandEvent_t *event, IEC104_CommandRejectCause_t cause);
/**
* 功能:报告设备结果,结果只记录一次并冻结;不发返回信息,也不隐式Complete。
* 输入参数:self/event为实例及启动成功的原EXECUTE事件;result为SUCCEEDED或FAILED。
* 输出参数:写入事务result并记录完成期限起点;不发送确认/终止、不关闭返回信息阶段、不调用应用。
* 返回值:OK已记录;WAIT因未读通知尚未记录;STALE事务结束/超时或事件不符;
* ERROR参数/结果非法、已报告/已Complete、重入或服务错误。
* 本次触发执行结果超时后返回STALE;模块已安排否定TERM,不能重新报告结果或重做动作。
* 说明:本函数及下列Submit_Return_Info/Complete只接受Accept动作返回STARTED的原EXECUTE事件。
* 入参:self为实例,event为上述事件,result为SUCCEEDED或FAILED。
* 可早于ACT_CON交接;设备完成后应及时报告,OK停止执行期限并启动complete_timeout_ms。
*/
IEC104_CommandReplyResult_t IEC104_Command_Report_Result(IEC104_Command_t *self,
const IEC104_CommandEvent_t *event, IEC104_CommandResult_t result);
/**
* 功能:通过原连接HIGH提交一帧返回信息,不经过可覆盖的NORMAL队列。
* 输入参数:self/event为实例和启动成功的EXECUTE令牌;asdu为调用方持有的完整监视ASDU。
* 输出参数:完整验证104布局、对象、类型、COT、CA及标志;OK后累计发送和返回信息计数。
* 返回值:OK为发送层已复制到HIGH或SendBuffer,可释放/复用ASDU缓冲,不能重交;WAIT须保留ASDU重试;
* ERROR为ASDU/参数/重入/服务错误或Complete后仍待收尾,尚未接手;STALE为事务/事件失效。
* 正常STOP且通知待分派时先WAIT;其他发送ERROR/FATAL终结事务并返回STALE,不可重试旧ASDU。
* 必要的后续变位由应用另按COT=3上报。
* 正常结束等待最后一条事务应答进入SendBuffer;异常结束以FINISHED的冻结标志决定补报。
* 同一HIGH生命周期的返回信息遵守FIFO,最后一条已交接即可证明已接手的前缀全部交接。
* 返回信息不等待NORMAL排空;同一测点跨HIGH/NORMAL的采样顺序由应用与主站另行约定。
* 应用未提交OK的后缀仍由应用管理;成功提交不表示对端ACK,断线不会迁移到新连接。
* 说明:入参:self为实例;event为启动成功的原EXECUTE;asdu为有效、完整的监视方向ASDU。
* 类型1..21/30..40,至少一对象,COT=11或3,P/N=0,TEST/CA与命令一致;完整校验对象。
* IOA可与命令IOA不同;应用EXECUTE事件只来自TEST=0,模拟命令不产生返回信息。
* 调用可以早于或晚于Report_Result,但须早于Complete。
* 模块有更早待交应答、确认未接手、HIGH无空间或未读通知时WAIT,不缓存ASDU、也不占排序位置。
*/
IEC104_CommandReplyResult_t IEC104_Command_Submit_Return_Info(IEC104_Command_t *self,
const IEC104_CommandEvent_t *event, const IEC60870_Asdu_t *asdu);
/**
* 功能:声明本事务不再产生返回信息;固定安排ACT_TERM并由Process完成后续交接。
* 输入参数:self/event为实例及启动成功的原EXECUTE事件;设备结果必须已经Report_Result。
* 输出参数:分配终止FIFO序号,置completed并启动交接期限;成功肯定终止,失败否定终止。
* 两种已报告结果都占用终止序号,P/N在Submit_Head组包时确定;不会把失败改写成成功。
* 返回值:OK立即关闭返回阶段,不必重调;WAIT为未读通知,尚未接手;
* ERROR为尚未报告结果、仍待收尾时重复调用、参数/重入/服务错误;已结束/事件不符为STALE。
* OK后启动handover_timeout_ms;正常完成须所有必要回复已被接手且事务尾为HANDED。
* 成功回COT=10/P/N=0,已报告FAILED回COT=10/P/N=1;正常FINISHED须等TERM进入SendBuffer。
* 到期丢弃本事务模块残留回复,已进入HIGH的帧不撤回;FINISHED冻结补报结果。
* 等待执行结果超时由模块自动安排否定TERM并立即FINISHED,本接口返回STALE。
* 超时TERM表示命令服务未确认成功,结果仍未知;否定TERM不能证明物理输出已停止。
* 说明:入参:self为实例,event为启动成功的原EXECUTE;结果须已报告,全部返回信息须已提交OK。
* 允许零帧返回信息;可在确认未交接时调用,模块保持确认先于ACT_TERM的顺序。
*/
IEC104_CommandReplyResult_t IEC104_Command_Complete(IEC104_Command_t *self,
const IEC104_CommandEvent_t *event);
/**
* 功能:只读查询仍占槽的事务,可在动作回调内使用,不做会话推进或期限转换。
* 输入参数:self为实例;event为本事务历史SELECT/EXECUTE或已取FINISHED;info为非NULL输出。
* 输出参数:当前阶段、是否尚未ENDED、确认/结果/Complete/终止状态;不推进会话或期限。
* 返回值:true写入快照,ENDED的active=false;无效参数/身份、槽已回收时false且不修改info。
* 不保留历史事务;刚读出的FINISHED若已触发槽回收,使用它查询也会false。
* 说明:入参:self为实例;event可为该事务任一已交付的SELECT/EXECUTE/FINISHED;info非NULL。
*/
bool IEC104_Command_Get_Transaction(const IEC104_Command_t *self,
const IEC104_CommandEvent_t *event, IEC104_CommandTransactionInfo_t *info);
/**
* 功能:只读查询会话、调度提示及累计计数,可在动作回调内使用。
* 输入参数:self为实例;status为非NULL输出,可在动作回调内使用。
* 输出参数:在累计统计副本上即时计算会话通知、事务占用、待交回复/事件及期限剩余量。
* 返回值:true写入快照;句柄/参数/Slave服务无效时false且不修改status。
* events_pending优先读Slave通知;need_process用于立即调度,timer_active配合剩余时间等待。
* need_process=false不免除每轮网络推进后的Process,也不代表应用没有待重试的ASDU/Complete。
* 说明:入参:self为实例,status非NULL接收快照;计算剩余时间但不转换已到期事务。
*/
bool IEC104_Command_Get_Status(const IEC104_Command_t *self, IEC104_CommandStatus_t *status);
#ifdef __cplusplus
}
#endif
#endif /* IEC104_COMMAND_H */