补充遥调业务代码
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# IEC104 函数 API 接口汇总(按实现文件)
|
||||
|
||||
依据当前工作区的协议库源码及对应头文件整理,按实现所在的 `.c` 文件分节。范围不包含示范程序、测试程序及其业务辅助函数;包括独立 Type 45/46 遥控模块的 14 个公开函数及其完整类型、返回值和生命周期约定。
|
||||
依据当前工作区的协议库源码及对应头文件整理,按实现所在的 `.c` 文件分节。范围不包含示范程序、测试程序及其业务辅助函数;包括Type 45–51/58–64命令模块的16个公开函数及其完整类型、返回值和生命周期约定。
|
||||
|
||||
共覆盖 **25 个实现文件**,其中内部跨文件协作函数为Link 5个、信息对象层2个、召唤引擎2个。表中标有“内部协作”的函数不属于业务 API;文件内的 `static` 辅助函数、宏和类型定义不作为函数接口列出,各模块入口以对应小节和声明头文件为准。
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
| 接入站总召/分组总召 | [Interrogation](#file-21) | Handle_Event接收激活/撤销及状态通知,Process推进并检查期限;NextEvent取业务事件,以Reply_Begin/Submit_Batch/Complete_Data显式应答 |
|
||||
| 接入计数量召唤 | [CounterInterrogation](#file-23) | 独立创建,复用驱动;读取用Reply_Begin和数据接口,冻结/复位用Execute_Begin |
|
||||
| 接入时钟同步 | [ClockSynchronization](#file-24) | Handle_Event校验保存,Process推进应答及期限,只有显式Execute_Next调用一次应用动作;确认回显原时标 |
|
||||
| 接入单点/双点遥控 | [Command 配置](#command-api-config)、[函数契约](#command-api-functions)、[返回值](#command-api-results) | NextEvent取得SELECT/EXECUTE,Accept/Reject消费事件;执行后Report_Result、Submit_Return_Info、Complete,FINISHED清理资源 |
|
||||
| 接入遥控/遥调及带时标命令 | [Command 点表与配置](#command-api-config)、[函数契约](#command-api-functions)、[时间基准](#command-api-time-base) | 配置按CA/IOA排序的只读点表;NextEvent取得SELECT/EXECUTE,Accept/Reject消费,执行后Report_Result、Submit_Return_Info、Complete,FINISHED清理;应用提供时间基准 |
|
||||
| 解析主站请求 | [Asdu_Get_Data / Parse / Get_Element](#file-16) | 先检查 I_FRAME 及 `asdu_result`,再做精确解析与业务条件检查 |
|
||||
| 回复任意 ASDU | [MasterConnection_Send_ASDU](#file-18) | 使用 `&event.connection`;ASDU 可以是单独构造的对象 |
|
||||
| 回复激活确认、终止 | [MasterConnection_Send_ACT_CON / Send_ACT_TERM](#file-18) | 修改传入 ASDU 的 COT/P/N 后提交,执行时机由业务决定 |
|
||||
@@ -2496,9 +2496,9 @@ bool IEC104_ClockSynchronization_Get_Status(const IEC104_ClockSynchronization_t
|
||||
|
||||
## 25. IEC104_Command.c
|
||||
|
||||
实现:[IEC104_Command.c](../../104/business/IEC104_Command.c);声明:[IEC104_Command.h](../../104/business/IEC104_Command.h)。本节列出全部 **14 个公开函数**,并说明其配置、值类型及调用约束。状态机设计见[遥控设计](IEC104_Command_设计架构.md),事件循环与应用处理顺序见[遥控调用流程](IEC104_完整调用流程.md#flow-command)。
|
||||
实现:[IEC104_Command.c](../../104/business/IEC104_Command.c);声明:[IEC104_Command.h](../../104/business/IEC104_Command.h)。本节列出全部 **16 个公开函数**,并说明其配置、值类型及调用约束。状态机设计见[遥控设计](IEC104_Command_设计架构.md),事件循环与应用处理顺序见[遥控调用流程](IEC104_完整调用流程.md#flow-command)。
|
||||
|
||||
模块只处理 Type 45(单点命令)和 Type 46(双点命令)的 COT=6 激活、COT=8 撤销。模块负责格式、寻址、选择/执行匹配、期限和协议收尾;应用负责 IOA 点表、远方/就地、闭锁、返校、输出及设备结果。未配置的类型返回 IGNORED,交后续处理器;不支持遥调、带时标命令、多个遥控并行或跨重连选择保持。决定窗口内的同点激活按[请求校验规则](#command-api-validation)静默丢弃,窗口外不按请求内容去重。
|
||||
模块处理Type 45–51及58–64的COT=6激活、COT=8撤销,默认全局启用14种,但默认点表为空,不执行任何点。模块负责格式、寻址、点类型和模式准入、选择/执行匹配、时标判定、期限及协议收尾;应用提供有序只读点表,负责远方/就地、闭锁、返校、设定值限值、输出及设备结果,并提供可信时间基准。全局未启用的类型返回IGNORED,交后续处理器;点掩码不允许的已启用类型回否定。不支持多个命令并行或跨重连选择保持。决定窗口内的同点激活按[请求校验规则](#command-api-validation)静默丢弃,窗口外不按请求内容去重。
|
||||
|
||||
本节函数表省略公共前缀 `IEC104_Command_`;枚举表注明各自省略的前缀。不能把枚举的非零值统一视为成功。
|
||||
|
||||
@@ -2506,19 +2506,47 @@ bool IEC104_ClockSynchronization_Get_Status(const IEC104_ClockSynchronization_t
|
||||
|
||||
### 25.1 配置、容量与所有权
|
||||
|
||||
`IEC104_CommandConfig_t` 由 Config_Default 填写,Create 按值复制;调用后可修改或释放原配置存储,不影响实例。Create 不接受 NULL 配置,也不自动初始化或开启 Slave。
|
||||
`IEC104_CommandConfig_t`由Config_Default填写,Create按值复制Config;调用后可修改或释放原Config存储,但其points指向的点表只被借用,必须持续有效且只读至Destroy成功。Create不接受NULL配置,也不自动初始化或开启Slave。
|
||||
|
||||
```c
|
||||
typedef enum {
|
||||
IEC104_COMMAND_MODE_DIRECT = 1,
|
||||
IEC104_COMMAND_MODE_SELECT_EXECUTE = 2
|
||||
} IEC104_CommandMode_t;
|
||||
|
||||
typedef struct {
|
||||
uint16_t common_address;
|
||||
uint32_t ioa;
|
||||
uint16_t type_mask;
|
||||
IEC104_CommandMode_t mode;
|
||||
} IEC104_CommandPoint_t;
|
||||
```
|
||||
|
||||
| 点字段/模式 | 校验与含义 |
|
||||
|---|---|
|
||||
| common_address | 1..65534;可以配置尚未注册的CA,但实际受理仍核对Slave注册身份 |
|
||||
| ioa | 1..0xFFFFFF;点表按common_address再ioa严格升序且唯一,同一点允许类型放在同一行 |
|
||||
| type_mask | 非零,仅45–51/58–64的14个已知位;可含全局未启用位,实际允许集合取全局与点掩码交集 |
|
||||
| DIRECT(1) | 只直接执行;有S/E的类型收到SELECT回否定7;51/64只能用此模式 |
|
||||
| SELECT_EXECUTE(2) | 先选择再执行,未选择执行回否定7;点掩码不得含51/64,即使全局未启用这两种也不允许 |
|
||||
|
||||
Create拒绝地址越界、无序/重复点、非法点掩码或模式。点查找为二分;表从Create至Destroy不可改写、重排或释放,不复制到模块、不通过回调查询。更新须Cancel和处理FINISHED、完成收尾,关闭Slave并读空旧通知后Destroy,再用新表Create、重启服务并建立新连接,完整分派CONNECTED/ACTIVATED。新实例不继承会话或时间基准,须重新Set_Time_Base;不能仅重建Command便挂回旧连接热更新。点表只定义命令许可与执行模式,不保存设备当前值。
|
||||
|
||||
| 字段 | 默认值 | 校验及语义 |
|
||||
| --- | --- | --- |
|
||||
| `type_mask` | `IEC104_COMMAND_TYPE_BIT(45U) \| IEC104_COMMAND_TYPE_BIT(46U)` | 非零,仅允许45/46两位;未选中的类型不接手 |
|
||||
| `select_required_mask` | 与默认 `type_mask` 相同 | 必须为 `type_mask` 子集;某位为0表示该类型允许直接执行,也仍可选择后执行 |
|
||||
| `select_timeout_ms` | 30000 | 必须非零;选择生效至匹配执行被Handle_Event受理,包含选择确认的发送等待 |
|
||||
| `type_mask` | `0x3FFF`,45–51/58–64全部14位 | uint16_t,非零;可按应用裁剪,bit14/15必须为0;未选中的类型不接手 |
|
||||
| `points` | NULL | const IEC104_CommandPoint_t *,借用的只读有序点表;与point_count配对 |
|
||||
| `point_count` | 0 | size_t,点元素数;NULL/0合法空表,非NULL/0及NULL/非零均拒绝,不能超过SIZE_MAX/sizeof(IEC104_CommandPoint_t) |
|
||||
| `select_timeout_ms` | 30000 | 每实例统一、仅选择模式有效,必须非零;Config_Default后、Create前可改;计时及选值见[选择有效期](IEC104_Command_设计架构.md#4-状态与期限) |
|
||||
| `decision_timeout_ms` | 15000 | 工作事件生成至Accept/Reject消费;0禁用时长限制 |
|
||||
| `execute_timeout_ms` | 60000 | 执行动作返回STARTED至Report_Result成功;0禁用时长限制 |
|
||||
| `send_act_term` | true | 成功执行收尾时发送ACT_TERM;false时任何结果均不发 |
|
||||
| `act_term_on_failure` | false | 仅 `send_act_term=true` 时有效:启动后Report_Result(FAILED)也发送ACT_TERM;不适用于动作返回FAILED或执行超时 |
|
||||
| `time_tag_max_delay_ms` | 10000 | uint32_t,带时标激活的时差上限;0只关闭时差检查,不关闭IV及UTC换算检查 |
|
||||
| `master_utc_offset_minutes` | 480 | int16_t,主站时标标准时区,范围−1439..1439分钟;SU由公共时间工具处理 |
|
||||
| `negative_on_expired` | false | bool,过期激活默认静默丢弃;true改为否定ACT_CON |
|
||||
|
||||
`IEC104_COMMAND_TYPE_BIT(type)` 的布局为45..51对应bit0..6、58..64对应bit7..13,范围外返回0,避免非法移位。第一版Create仍只接受45/46两位;宏参数会多次求值,只传常量或无副作用表达式。结构体扩展要求库和调用者一起重新编译,不承诺二进制布局兼容。
|
||||
`IEC104_COMMAND_TYPE_BIT(type)`的布局为45..51对应bit0..6、58..64对应bit7..13,范围外返回0,避免非法移位;宏参数会多次求值,只传常量或无副作用表达式。默认全局掩码不代表存在可执行点:空表新激活走到点策略检查时回47。模式按CA/IOA定义,同类型的不同点可以分别DIRECT或SELECT_EXECUTE。旧select_required_mask字段已移除,调用方须删除该字段设置并提供点表;这是源码接口迁移,库和所有调用者须一起重新编译,不承诺二进制兼容。公开函数仍为16个。
|
||||
|
||||
| 编译期设置 | 默认值 | 作用 |
|
||||
| --- | --- | --- |
|
||||
@@ -2526,7 +2554,7 @@ bool IEC104_ClockSynchronization_Get_Status(const IEC104_ClockSynchronization_t
|
||||
| `IEC104_COMMAND_REPLY_CAPACITY` | 4 | 每实例独立短应答槽数,用于校验错误、实例忙和否定撤销;须大于0且小于 `UINT32_MAX / 2` |
|
||||
| 唯一事务槽 | 固定1个 | 内含工作/终结事件、确认、撤销或失配应答、终止的存储及排序身份;必要事务应答不依赖独立池空位 |
|
||||
|
||||
两个容量宏均须大于0,编译选项作用于 IEC104_Command.c。全部存储静态分配,无堆分配;模块借用Slave,Slave寿命覆盖Command。所有入口与Slave在同一事件循环串行执行,不保存动作函数或context指针。
|
||||
两个容量宏均须大于0,编译选项作用于IEC104_Command.c。模块内部存储静态分配,无堆分配;点表由调用方提供并借用。模块借用Slave,Slave寿命覆盖Command。所有入口与Slave在同一事件循环串行执行,不保存动作函数或context指针。
|
||||
|
||||
从事务创建至槽释放,所有站点、所有IOA均视为遥控忙;FINISHED未读或本事务最后应答尚未交接也占槽。决定窗口内同点合法激活只丢弃,不新增忙否定应答。独立短应答可在 `busy=false` 时仍待发送,不阻止创建新事务,但仍参与全局FIFO,且Destroy要求它们全部清空。独立池满只计过载并丢弃新应答,不覆盖旧内容、不主动断链。事务释放后,主站重发的相同命令按新请求处理;直接执行可能再次启动输出。
|
||||
|
||||
@@ -2544,14 +2572,23 @@ bool IEC104_ClockSynchronization_Get_Status(const IEC104_ClockSynchronization_t
|
||||
| `station_id` | uint64_t | 原站点注册身份;同CA删除再注册后编号不同 |
|
||||
| `common_address` | uint16_t | 原CA,实际站地址1..65534 |
|
||||
| `originator_address` | uint8_t | 原OA;参与选择/执行及撤销匹配 |
|
||||
| `type_id` | uint8_t | 45或46 |
|
||||
| `ioa` | uint32_t | 非零24位信息对象地址;点表存在性由应用检查 |
|
||||
| `is_select` | bool | 请求S/E位,true为选择,false为执行 |
|
||||
| `type_id` | uint8_t | 45–51或58–64 |
|
||||
| `ioa` | uint32_t | 非零24位信息对象地址;创建工作事务前已在命令点表中验证,设备动态可用性仍由应用检查 |
|
||||
| `is_select` | bool | 请求S/E位,true为选择,false为执行;51/64恒为false |
|
||||
| `selected` | bool | EXECUTE是否匹配了本事务已有选择;直接执行为false |
|
||||
| `state` | uint8_t | Type45为0/1,Type46为1/2,通常对应分/合;具体设备操作含义由点表定义 |
|
||||
| `qualifier` | uint8_t | QU原始0..31;1短脉冲、2长脉冲、3持续输出,0及其他值由应用解释 |
|
||||
| `state` | uint8_t | 45/58为0/1;46/59为1/2;47/60为1降一步、2升一步;设定值和比特串为0 |
|
||||
| `qualifier` | uint8_t | 45–47及对应时标类型为QU 0..31;48–50及对应时标类型为QL 0..127;51/64为0,具体含义由应用解释 |
|
||||
| `value.normalized` | int16_t(union成员) | 48/61的原始16位定点编码,实际值为normalized/32768.0 |
|
||||
| `value.scaled` | int16_t(union成员) | 49/62的标度化设定值 |
|
||||
| `value.short_float` | float(union成员) | 50/63的短浮点设定值,已拒绝NaN及正负Inf |
|
||||
| `value.bitstring` | uint32_t(union成员) | 51/64的32位比特串;最高位是数据位 |
|
||||
| `has_time` | bool | 58–64为true;其他类型为false |
|
||||
| `time` | IEC60870_CP56Time2a_t | 原始解码CP56,保留IV/SU;非时标类型清零 |
|
||||
| `time_utc_ms` | uint64_t | 按配置时区换算并含毫秒余数的UTC纪元毫秒;非时标类型为0 |
|
||||
| `accepted_ms` | uint64_t | 当前请求由Handle_Event受理的单调毫秒;包含Slave通知排队时间,不是网络收包时间 |
|
||||
|
||||
value为具名union,按type_id读取对应成员;状态类无值类型清零。已受理的带时标激活一定通过IV及UTC换算检查,即使time_tag_max_delay_ms为0也一样。头文件显式包含`IEC60870_Time.h`。事件与动作参数都从模块保存的规范原文重新解码;内部解码失败时NextEvent/Accept返回ERROR,Accept不安排肯定确认也不调用动作,而按SERVICE_ERROR收尾。已交付工作事件仍欠FINISHED;若原文持续不可解码,终结事件只提供清理用身份和SERVICE_ERROR,不可将其值字段用于动作。
|
||||
|
||||
<a id="command-api-events"></a>
|
||||
|
||||
`IEC104_CommandEvent_t` 同样是纯值副本,**NextEvent取走与Accept/Reject消费是两个步骤**。取走的工作事件仍可因撤销、期限或会话结束失效,不能脱离模块检查后直接启动设备动作。
|
||||
@@ -2648,13 +2685,15 @@ Accept同步至多调用一次action,context原样转交、允许NULL,两者
|
||||
| 函数 | 参数与前置条件 | 成功、失败和输出 |
|
||||
| --- | --- | --- |
|
||||
| Config_Default | config指向调用方可写配置 | 无返回;完整填写默认值,NULL无操作,不创建实例/启动期限 |
|
||||
| Create | slave为有效服务,寿命覆盖实例;config非NULL、满足配置表;**在开始消费Slave通知前调用** | 成功返回静态句柄;非法服务/配置、同Slave重复创建、池满或实例号耗尽返回NULL。仅复制配置,不开启网络 |
|
||||
| Create | slave为有效服务,寿命覆盖实例;config非NULL、点表符合范围/顺序/模式约束;**在开始消费Slave通知前调用** | 成功返回静态句柄;非法服务/配置/点表、同Slave重复创建、池满或实例号耗尽返回NULL。复制Config,借用点表至Destroy,不开启网络 |
|
||||
| Destroy | 事务槽为空、无未读FINISHED、独立应答池为空,不在回调中 | true归还实例,旧指针失效;否则false且保留实例。不隐式Cancel、关闭Slave或释放应用引用 |
|
||||
| Cancel | self有效;不在回调中 | 无返回;清全部模块待交应答,以CANCELLED结束活动事务,保留应交FINISHED,会话激活状态不变;无效句柄/回调中无操作 |
|
||||
| Set_Time_Base | self有效、不在回调中;utc_ms及base_ms为同一时刻的UTC/Net单调毫秒 | true保存基准;UTC越界、base_ms晚于当前单调时间或非法调用返回false且原基准不变,详见时间基准一节 |
|
||||
| Clear_Time_Base | 本站时间不可信时调用,不在回调中 | 无返回;清除基准;无效句柄或回调中无操作;不取消已受理事务 |
|
||||
| Handle_Event | event为所属Slave按FIFO取出的通知,借用内容仍有效;所有连接/启停通知必须分派 | HANDLED含状态通知及已识别请求的受理、拒绝、丢弃;IGNORED继续分派;ERROR处理来源/参数/服务错误,不能再发44兜底。详见返回表 |
|
||||
| Process | 每轮网络推进、Slave通知分派后调用 | true包含无事、WAIT、事务已终结或发送故障已收尾;false为句柄/重入/服务/组包错误。最多推进 `2*(1+应答槽容量)` 步,不调用应用动作 |
|
||||
| NextEvent | event为非NULL输出 | READY写入一个纯值事件并记录已取走;EMPTY/ERROR保持输出。取走不消费工作决定;已有FINISHED离线也可取 |
|
||||
| Accept | event为已取走、尚未消费的当前SELECT/EXECUTE;action仅SELECT可NULL;context按值传给回调 | 先校验会话/期限并准备确认,再消费事件,至多调用一次动作;OK不是动作或发送成功,精确返回见下表 |
|
||||
| Accept | event为已取走、尚未消费的当前SELECT/EXECUTE;action仅SELECT可NULL;context按值传给回调 | 先校验会话/期限并解码保存的原文,成功后准备确认、消费事件并至多调用一次动作;OK不是动作或发送成功,精确返回见下表 |
|
||||
| Reject | event同Accept;cause为两个RejectCause之一 | 不调用动作,消费事件并安排7/47,以REJECTED结束;FINISHED可早于否定交接 |
|
||||
| Report_Result | event为Accept动作返回STARTED的原EXECUTE;result为SUCCEEDED/FAILED,尚未成功报告 | 一次记录并冻结结果、停止执行期限;可早于确认交接。不提交返回信息、不隐式Complete |
|
||||
| Submit_Return_Info | event为上述EXECUTE;asdu符合返回信息校验,仍在EXECUTING且Complete未成功 | 一次提交一帧;只能在执行确认交接后接手,否则WAIT。不缓存ASDU、不占用持久FIFO位置 |
|
||||
@@ -2694,32 +2733,38 @@ WAIT后保留本次事件、待报告结果或ASDU,先分派Slave通知、推
|
||||
|
||||
### 25.6 请求校验、匹配和撤销
|
||||
|
||||
45/46请求原文固定为10字节:6字节公共头、3字节IOA、1字节SCO/DCO。当前代次、已激活且可读取的配置内命令,在匹配前先做到期转换,然后按以下优先级处理;已识别请求的拒绝/丢弃均返回HANDLED。
|
||||
各类型的规范ASDU长度分别为:45/46/47为10,48/49为12,50为14,51为13;对应时标类型58–64各增加7字节,最大21。6字节公共头及3字节IOA不变,值、S/E和CP56布局由私有表决定。当前代次、已激活且可读取的配置内命令,在匹配前先做到期转换,然后按以下优先级处理;已识别请求的拒绝/丢弃均返回HANDLED。
|
||||
|
||||
| 顺序 | 条件 | 处理 |
|
||||
| --- | --- | --- |
|
||||
| 1 | 对象数不是1,或对象不足4字节(含IOA) | 计rejected,不应答,不截取多对象伪造单命令 |
|
||||
| 1 | 对象数不是1,或原文不足该类型的规范长度 | 计rejected,不应答,不截取多对象或补零伪造单命令;线上已知类型截短通常先由Receiver拒绝,不进入本模块 |
|
||||
| 2 | COT不是6或8 | COT=45、P/N=1 |
|
||||
| 3 | CA未注册、0或65535 | COT=46、P/N=1 |
|
||||
| 4 | IOA=0 | COT=47、P/N=1 |
|
||||
| 5 | SQ=1、长度不等于10、P/N=1、TEST=1、SCO保留位为1或DCS为0/3 | 否定ACT_CON(7);撤销请求否定DEACT_CON(9) |
|
||||
| 5 | SQ=1、长度不等于规范长度、P/N=1、TEST=1、值非法(含50/63的NaN/Inf)或CP56格式非法 | 否定ACT_CON(7);撤销请求否定DEACT_CON(9) |
|
||||
| 6 | 合法COT=8 | 按撤销规则匹配 |
|
||||
| 7 | 合法COT=6,当前仍为SELECT_WAIT或EXECUTE_WAIT,同generation、station_id及IOA | 静默丢弃,仅增加dropped_requests,返回HANDLED |
|
||||
| 8 | 其他合法COT=6 | 匹配选择、受理新事务或忙/无选择否定7 |
|
||||
| 8 | 其他58–64的COT=6 | 按时间规则处理IV、UTC换算及时差;过期可静默丢弃 |
|
||||
| 9 | SELECTED阶段同点执行且选择确认已交接 | 先匹配原选择;失配终结MISMATCH,匹配后生成EXECUTE,不重新查不可变点表 |
|
||||
| 10 | 其余通过检查的COT=6 | 二分查CA/IOA点;无点回47,点类型不符或DIRECT点收到SELECT回否定7 |
|
||||
| 11 | 点策略通过,实例仍忙或SELECT_EXECUTE点未选择执行 | 否定7;不新建事务或工作事件 |
|
||||
| 12 | 前述检查通过 | 新建唯一事务,生成SELECT或EXECUTE |
|
||||
|
||||
回显保留原类型、TEST、OA、CA和对象字节,VSQ规范为1、长度取10字节,按应答替换COT/P/N;因对象截短或数量不符而丢弃时不回显。除IOA=0外,模块不检查业务点表;应用用Reject(UNKNOWN_IOA)表达点不存在。
|
||||
回显保留原类型、TEST、OA、CA和对象字节(包括非法值和原CP56),VSQ规范为1、长度取该类型规范长度,按应答替换COT/P/N,不重新编码对象;过长请求不复制额外尾字节。因对象截短或数量不符而丢弃时不回显。新激活走到点检查时由模块判断点是否存在、类型和模式是否许可;拒绝不生成工作事件、事务或FINISHED。应用仍可用Reject(UNKNOWN_IOA)表达动态不可用的设备点,用Reject(NEGATIVE)表达越限、闭锁等策略拒绝。
|
||||
|
||||
决定窗口内的丢弃不比较类型、OA、S/E、状态或QU;同点合法激活即使这些字段不同也不替代原工作请求。type_mask及上表前置校验仍优先,COT=8不适用此规则。丢弃不刷新期限、不生成新事件或应答,不增加rejected、busy_rejected或overloads;应用继续处理原SELECT/EXECUTE事件。到期转换之后已非决定阶段时,不再按此规则丢弃。
|
||||
|
||||
SELECTED阶段的选择匹配要求原会话、原station_id、IOA、类型、OA一致,且SCO/DCO屏蔽S/E后的字节相同(状态和QU均比较)。此阶段选择肯定确认尚未交接时,任何执行均按忙拒绝并保留选择;交接后,同点执行失配终结为MISMATCH并回显此次执行。其他站点/IOA的新激活、SELECTED中的重复选择及EXECUTING/ENDED中的新激活仍否定7,原事务继续。
|
||||
SELECTED阶段的选择匹配要求原会话、原station_id、IOA、类型、OA一致,值字节逐字节相同,S/E字节屏蔽bit7后相同(状态和QU/QL均比较);CP56不比较。浮点+0/−0原始字节不同,判MISMATCH;45与58等跨类型组合也先判失配,不被后续点类型拒绝替代。此阶段选择肯定确认尚未交接时,通过时效及点策略检查的执行按忙拒绝并保留选择;交接后,同点执行失配终结为MISMATCH并回显此次执行。51/64始终直接执行,不读取不存在的S/E字节。其他站点/IOA的新激活、SELECTED中的重复选择及EXECUTING/ENDED中的新激活在通过时效及点策略检查后仍忙否定7,原事务继续。匹配执行沿用选择时已经验证的不可变点策略。
|
||||
|
||||
撤销要求原会话、station_id、IOA、类型、OA一致,不比较状态/QU。SELECT_WAIT、SELECTED、EXECUTE_WAIT可成功撤销,用事务自带槽回肯定9,因此独立池满也可撤销;尚未提交的旧确认被取消,新DEACT_CON取得新FIFO序号。已经交给发送层的确认无法撤回,DEACT_CON排在其后。EXECUTING、ENDED或无匹配事务时回否定9,原事务不受影响。本地Cancel不发送DEACT_CON,STOPDT则是连接停用而非COT=8撤销。
|
||||
撤销要求原会话、station_id、IOA、类型、OA一致,不比较值、状态或QU/QL,不判时差、IV及UTC换算,但仍检查CP56格式。SELECT_WAIT、SELECTED、EXECUTE_WAIT可成功撤销,用事务自带槽回肯定9,因此独立池满也可撤销;尚未提交的旧确认被取消,新DEACT_CON取得新FIFO序号。已经交给发送层的确认无法撤回,DEACT_CON排在其后。EXECUTING、ENDED或无匹配事务时回否定9,原事务不受影响。本地Cancel不发送DEACT_CON,STOPDT则是连接停用而非COT=8撤销。
|
||||
|
||||
<a id="command-api-timeouts"></a>
|
||||
|
||||
### 25.7 期限、会话与调度
|
||||
|
||||
全部期限使用 `IEC104_Net_Now_Ms` 的单调毫秒;本版无CP56及设备UTC参数。每阶段至多一个业务期限,已用时间大于或等于期限即到期。
|
||||
事务期限使用`IEC104_Net_Now_Ms`的单调毫秒,与带时标请求的UTC时效判定分开。每阶段至多一个业务期限,已用时间大于或等于期限即到期。
|
||||
|
||||
选择有效期不是必须等待的延时;默认30秒不变。起止时刻、确认排队占用、模式与单事务关系,以及10秒/30秒的工程选值说明统一见[状态与期限](IEC104_Command_设计架构.md#4-状态与期限)。
|
||||
|
||||
| 期限 | 起点 | 停止点 | 到期处理 |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -2737,6 +2782,23 @@ Process、工作事件NextEvent及有效应用应答先用Slave_Check_Request检
|
||||
|
||||
每轮网络推进并读空Slave通知后都调用Process、读取业务事件,再重试应用保留的结果/返回信息/Complete。`need_process=true` 要立即推进;false不表示无待重试任务。等待上限同时受Slave_Prepare、`timer_active/timeout_remaining_ms` 和应用异步状态约束,不能因发送WAIT紧循环空转,具体见[遥控调度流程](IEC104_完整调用流程.md#flow-command-schedule)。
|
||||
|
||||
<a id="command-api-time-base"></a>
|
||||
|
||||
#### 25.7.1 时间基准与带时标激活
|
||||
|
||||
| 函数 | 参数、结果及约束 |
|
||||
|---|---|
|
||||
| Set_Time_Base(self, utc_ms, base_ms) | 保存同一时刻的UTC纪元毫秒及Net单调毫秒;成功true。句柄无效、动作回调内调用、utc_ms超过`(uint64_t)IEC60870_TIME_MAX_SECONDS * 1000U + 999U`或base_ms晚于当前单调时间时false,原基准不变 |
|
||||
| Clear_Time_Base(self) | 本站时间不可信时清除基准;句柄无效或动作回调内调用无效果 |
|
||||
|
||||
模块不读Clock,也不保存时间回调。STOP、断线和Cancel不自动清除基准;基准更新仅影响随后受理的请求,不追溯已经生成的工作事件。应用在校时动作成功后记录utc_ms/base_ms,待Execute_Next返回后再调用Set_Time_Base;不要在动作回调中跨模块推进。
|
||||
|
||||
只对58–64的COT=6激活,在格式校验、撤销处理和决定期间同点丢弃之后,SELECTED匹配及忙判断之前检查。先拒绝IV=1或UTC换算失败;max=`time_tag_max_delay_ms`为0时仅跳过时差比较,不要求基准。max非零时,按`utc_ms + (now - base_ms)`推算站内UTC;无基准、now早于base_ms、加法溢出或超出公共时间范围回否定7。命令时标按配置标准时区及SU换算,并加回毫秒余数。
|
||||
|
||||
站内UTC比命令UTC晚至少max时为过期,默认只增加time_expired并静默丢弃;negative_on_expired=true时另计rejected并回否定7。命令UTC比站内UTC晚至少max时回否定7,计time_rejected和rejected。无效时间、无基准及推算失败也计time_rejected和rejected;单调时钟早于基准另计clock_errors。恰好等于max也拒绝或丢弃。静默过期不增加dropped_requests,不创建事务或业务事件,不产生FINISHED。
|
||||
|
||||
已选择但执行请求过期时,原选择继续保留到select_timeout_ms。撤销不判时差或IV/UTC换算,仍须通过CP56格式检查。时效只在Handle_Event受理时判一次,动作启动前不再检查;默认10秒窗口及15秒决定期限可能使动作开始时的命令年龄接近25秒。需要更严格策略时应用自行检查request.time_utc_ms。时区、窗口、IV处理、过期响应及ACT_TERM须与主站约定。
|
||||
|
||||
<a id="command-api-order"></a>
|
||||
<a id="command-api-return-info"></a>
|
||||
|
||||
@@ -2784,6 +2846,7 @@ TERM策略在Report_Result之后由Complete决定:成功且send_act_term=true
|
||||
| `events_pending` | Slave还有通知须优先读取;为true时need_process=false |
|
||||
| `need_process` | 有可立即尝试的本地发送、到期或失效会话收尾;发送WAIT后不持续置true。离线只剩FINISHED时为false,应用直接NextEvent读取 |
|
||||
| `timer_active` | 当前启用非零时长期限;false不关闭时钟回退检测 |
|
||||
| `time_base_valid` | bool,当前是否持有时间基准;查询不推算或重新验证基准 |
|
||||
| `busy` | 唯一事务仍占槽,含未读FINISHED/待交事务回复;不包含仅有独立短应答的情况 |
|
||||
| `timeout_remaining_ms` | 当前期限剩余毫秒,无期限/已到期/时钟倒退时为0;timer_active=true且为0时立即推进 |
|
||||
| `pending_replies` | 模块持有的事务与独立应答总数;不含已接手的HIGH/在途帧,也不含应用保留的返回信息 |
|
||||
@@ -2796,15 +2859,17 @@ TERM策略在Report_Result之后由Complete决定:成功且send_act_term=true
|
||||
| `negative_submitted` | 已交接的P/N=1应答数 |
|
||||
| `return_info_submitted` | Submit_Return_Info已交接的帧数 |
|
||||
| `waits` | 底层发送明确返回WAIT的次数;通知门禁、模块FIFO等待及正常STOP让出不计入 |
|
||||
| `rejected` | 接收校验、实例忙、失配及未选择等拒绝次数,包含无法可靠回显的畸形请求;不含决定窗口内同点合法激活的静默丢弃 |
|
||||
| `rejected` | 到达模块的接收校验、实例忙、失配及未选择等拒绝次数,包含时间否定;不含决定期间同点激活或过期激活的静默丢弃,也不含Receiver已拒绝的截短 |
|
||||
| `app_rejected` | 应用Reject或动作NOT_STARTED次数,与接收侧rejected分开 |
|
||||
| `busy_rejected` | 因事务占用而拒绝的新激活次数;其他点同样计入,决定窗口内同点合法激活的静默丢弃不计入 |
|
||||
| `busy_rejected` | 通过时效和点策略后因事务占用而拒绝的新激活次数;不存在的点、点类型/模式拒绝及决定窗口内同点静默丢弃不计入 |
|
||||
| `overloads` | 独立应答池满或新事务/事件身份序号耗尽的过载次数;决定窗口内同点合法激活的静默丢弃不计入 |
|
||||
| `dropped_requests` | 过载丢新,以及SELECT_WAIT/EXECUTE_WAIT内同generation、station_id及IOA的合法激活静默丢弃次数;后者可单独增加,不通过覆盖旧事务腾空间 |
|
||||
| `cancelled` | CANCELLED、STOPPED、DISCONNECTED、CONNECTION_CHANGED、SEND_ERROR、SERVICE_ERROR导致的事务结束总数;不证明设备无副作用 |
|
||||
| `deactivated` / `mismatches` | DEACTIVATED成功撤销 / MISMATCH终结的事务数 |
|
||||
| `select_timeouts` / `decision_timeouts` / `execute_timeouts` | 对应期限导致的结束数;时钟回退也走相应到期路径 |
|
||||
| `clock_errors` | 等待阶段发现单调时钟倒退次数;必要确认资源失败时最终原因可能为SERVICE_ERROR |
|
||||
| `clock_errors` | 事务期限或时间基准检查发现单调时钟倒退的次数;同一请求可能触发两处检查并分别计数,不能视为异常请求数;必要确认资源失败时最终原因可能为SERVICE_ERROR |
|
||||
| `time_expired` | unsigned long,达到过期时差上限的激活数,含静默丢弃和配置为否定两种情况 |
|
||||
| `time_rejected` | unsigned long,IV/UTC换算失败、无基准、推算越界/时钟倒退或时标超前而否定的激活数;不含time_expired |
|
||||
|
||||
<a id="command-api-lifecycle"></a>
|
||||
|
||||
@@ -2832,6 +2897,9 @@ IEC104_Command_t *IEC104_Command_Create(IEC104_Slave_t *slave,
|
||||
const IEC104_CommandConfig_t *config);
|
||||
bool IEC104_Command_Destroy(IEC104_Command_t *self);
|
||||
void IEC104_Command_Cancel(IEC104_Command_t *self);
|
||||
bool IEC104_Command_Set_Time_Base(IEC104_Command_t *self,
|
||||
uint64_t utc_ms, uint64_t base_ms);
|
||||
void IEC104_Command_Clear_Time_Base(IEC104_Command_t *self);
|
||||
IEC104_CommandEventResult_t IEC104_Command_Handle_Event(IEC104_Command_t *self,
|
||||
const IEC104_SlaveEvent_t *event);
|
||||
bool IEC104_Command_Process(IEC104_Command_t *self);
|
||||
|
||||
@@ -1,36 +1,71 @@
|
||||
# IEC104 遥控模块设计
|
||||
# IEC104 遥控、遥调与带时标命令设计
|
||||
|
||||
`104/business/IEC104_Command.c/h` 提供 Type 45 单命令和 Type 46 双命令业务。业务入口为 Slave,实例使用静态池,不动态分配内存、不保存应用回调;所有入口与所属 Slave 在同一事件循环中串行调用。一个 Slave 至多绑定一个 Command 实例,一个实例至多保留一个遥控事务。其他命令类型返回 IGNORED,交给后续业务或未知类型兜底。
|
||||
`104/business/IEC104_Command.c/h`统一提供Type 45–51及58–64这14种控制命令。业务入口为Slave,实例使用静态池,不动态分配内存、不保存应用回调;所有入口与所属Slave在同一事件循环中串行调用。一个Slave至多绑定一个Command实例,一个实例至多保留一个命令事务。默认全局启用14种类型,但点表为空,不执行任何点;应用提供点表并可通过type_mask进一步裁剪。全局未启用或范围外的类型返回IGNORED,交给后续业务或未知类型兜底。
|
||||
|
||||
## 1. 职责与默认配置
|
||||
|
||||
模块管理请求校验、选择与执行匹配、撤销、三类期限、应答排序、事务身份及 FINISHED。应用管理点表、权限、闭锁、返校和设备输出,显式报告设备结果并构造监视方向返回信息。协议结束不代表物理输出已经停止。
|
||||
模块管理请求校验、按点类型与模式准入、选择与执行匹配、撤销、三类期限、应答排序、事务身份及FINISHED。应用提供只读命令点表,管理权限、闭锁、限值、返校和设备输出,显式报告设备结果并构造监视方向返回信息。协议结束不代表物理输出已经停止。
|
||||
|
||||
| 配置 | 默认值 | 含义 |
|
||||
|---|---|---|
|
||||
| type_mask | Type 45、46 | 其他类型位在第一版配置中非法 |
|
||||
| select_required_mask | Type 45、46 | 清除对应位允许直接执行;必须是 type_mask 的子集 |
|
||||
| type_mask | 0x3FFF,全部14种类型 | 全局类型准入;非零,仅45–51及58–64,bit14/15必须为0 |
|
||||
| points / point_count | NULL / 0 | 借用有序只读点表及元素数;空表合法,但没有可执行点 |
|
||||
| decision_timeout_ms | 15000 | 工作事件生成至应用决定;0 禁用 |
|
||||
| select_timeout_ms | 30000 | 选择生效至匹配执行被模块受理;不得为0 |
|
||||
| select_timeout_ms | 30000 | 每实例统一的选择有效期,仅用于选择执行模式;不得为0,详见第4节 |
|
||||
| execute_timeout_ms | 60000 | 执行动作返回 STARTED 至 Report_Result;0 禁用 |
|
||||
| send_act_term | true | 成功执行后发送 ACT_TERM |
|
||||
| act_term_on_failure | false | 显式启用时也发送失败执行的终止;send_act_term=false 时忽略 |
|
||||
| time_tag_max_delay_ms | 10000 | 带时标激活的时差上限;0只关闭时差检查,仍拒绝IV及UTC换算失败 |
|
||||
| master_utc_offset_minutes | 480 | 主站时标标准时区,范围−1439..1439分钟;SU由公共时间工具处理 |
|
||||
| negative_on_expired | false | 过期激活默认静默丢弃;true时回否定ACT_CON |
|
||||
|
||||
TEST=1 不执行动作,返回否定确认。广播 CA=65535 不接受。失败终止可选策略发送原执行请求的 COT=10、P/N=0,表示执行过程终止,不表示设备执行成功;结果由应用监视信息和 FINISHED(EXECUTION_FAILED) 表达。该策略为本模块接入约定,默认不开启。
|
||||
|
||||
### 1.1 按CA/IOA配置命令点
|
||||
|
||||
`IEC104_CommandPoint_t`包含common_address、ioa、type_mask及mode。每个CA/IOA仅一行;同一点的多个允许类型放入同一掩码,并共享执行模式。`IEC104_COMMAND_MODE_DIRECT=1`表示只接收直接执行,SELECT回否定7;`IEC104_COMMAND_MODE_SELECT_EXECUTE=2`表示必须先选择,未选择的EXECUTE回否定7。51/64没有S/E,只能属于DIRECT点。
|
||||
|
||||
Create要求点表按CA再IOA严格升序且唯一,使用二分查找;CA范围1..65534,IOA范围1..0xFFFFFF,点type_mask非零且仅含14个已知类型位,mode仅允许上述两值。点掩码可以包含全局未启用的已知类型位,实际允许集合取两者交集;SELECT_EXECUTE点不得包含51/64,即使全局当前未启用它们也不允许。
|
||||
|
||||
points=NULL与point_count=0必须成对,非NULL空表、NULL非空表及元素数超过SIZE_MAX/sizeof(Point)均拒绝。空表可以创建实例,随后走到点策略检查的新激活因无点回47。允许先为尚未注册的CA配置点;受理时仍按Slave注册表核对实际站点身份,点表不代替站点注册。
|
||||
|
||||
Create按值复制Config,但仅借用点表,不复制表、不保存查询回调。应用须使表存储从Create至Destroy持续有效且只读,不得在原地改类型、模式或排序。更新须先Cancel、读完FINISHED并完成应用收尾,关闭Slave并读空生命周期通知后Destroy,再以新表Create并重新启动服务、建立连接,完整分派CONNECTED/ACTIVATED。新实例不继承旧会话或时间基准,必须重新设置可信基准;仅Destroy/Create不能挂回仍运行的旧连接实现热更新。表内不保存设备运行值。旧配置的select_required_mask已移除,调用方须迁移为具体点表并全部重新编译。
|
||||
|
||||
## 2. 请求校验和选择匹配
|
||||
|
||||
45/46 的104原文均为10字节:6字节公共头、3字节IOA、1字节SCO/DCO。唯一完整对象存在后,错误优先级为 COT、CA、IOA、布局/值、事务条件。COT非6/8回45,CA未注册或广播回46,IOA=0回47。对象数不是1或对象截短只计数丢弃;SQ、额外尾字节、P/N、TEST、SCO保留位和DCS非法值回否定7/9,回显规范为VSQ=1、10字节。已识别的拒绝和丢弃均返回HANDLED。
|
||||
标准104采用2/2/3参数,6字节公共头后接3字节IOA;命令元素从`IEC104_ASDU_HEADER_LEN + 3U`开始。规范ASDU长度由类型决定:
|
||||
|
||||
只有SELECT_WAIT、EXECUTE_WAIT两个决定阶段,对同会话generation、同station_id、同IOA且通过全部现有校验的COT=6激活静默丢弃,返回HANDLED。是否已被应用取走工作事件不影响此规则;不比较类型、OA、S/E、状态或QU,但新请求仍须通过type_mask、COT、寻址、格式和值校验。只增加dropped_requests,不增加rejected、busy_rejected或overloads;不覆盖原请求、不刷新决定期限、不生成新事件或应答。先检查到期,已到期事务不再适用此规则;其他点仍忙拒绝,COT=8仍按撤销处理。
|
||||
| 类型(无时标/带时标) | 命令元素 | ASDU长度 | 选择与校验 |
|
||||
|---|---|---|---|
|
||||
| 45 / 58 | SCO | 10 / 17 | 有S/E;保留位必须为0 |
|
||||
| 46 / 59 | DCO | 10 / 17 | 有S/E;DCS只能为1、2 |
|
||||
| 47 / 60 | RCO | 10 / 17 | 有S/E;RCS为1降一步、2升一步 |
|
||||
| 48 / 61 | NVA + QOS | 12 / 19 | 有S/E;原始有符号16位定点值 |
|
||||
| 49 / 62 | SVA + QOS | 12 / 19 | 有S/E;有符号16位标度值 |
|
||||
| 50 / 63 | R32 + QOS | 14 / 21 | 有S/E;拒绝NaN及正负Inf |
|
||||
| 51 / 64 | BSI | 13 / 20 | 无S/E,只能直接执行 |
|
||||
|
||||
SELECTED阶段的选择执行要求同会话、原站点注册编号、IOA、类型、OA,且SCO/DCO屏蔽S/E后相同。此阶段选择确认尚未交接时,执行按忙拒绝并保留选择;确认交接后同点不匹配执行终结为MISMATCH,否定回显本次执行。其他点的新激活只忙拒绝。匹配前检查选择期限,到期选择不能复活。
|
||||
配置内请求先检查当前事务到期,再检查唯一完整对象。COT非6/8回45,CA未注册或广播回46,IOA=0回47;之后检查SQ、规范长度、P/N、TEST、命令值及CP56格式,错误回否定7/9。公共解析器负责SCO/DCO/RCO及CP56校验;QU/QL的业务含义交应用解释。对象数量不符、或到达模块的原文不足规范长度时计rejected并丢弃,不能补零伪造对象。线上已知类型的截短通常更早由Receiver拒绝,不会到达Command,不能据此期待Command计数增加或连接继续。
|
||||
|
||||
撤销按会话、站点编号、IOA、类型、OA匹配,不比较状态。SELECT_WAIT、SELECTED、EXECUTE_WAIT中的匹配撤销复用事务存储,肯定DEACT_CON回显撤销请求。执行已经启动、事务已结束或没有匹配时否定撤销。发送接口已经返回OK的选择确认不能撤回,随后DEACT_CON按顺序交接。
|
||||
过长请求只回显规范长度前缀,VSQ规范为1;除VSQ、COT和P/N外保留原文字节,包括非法值。回显不重新构造合法对象。已识别的拒绝和丢弃均返回HANDLED。
|
||||
|
||||
只有SELECT_WAIT、EXECUTE_WAIT两个决定阶段,对同会话generation、同station_id、同IOA且通过前置报文校验的COT=6激活静默丢弃,返回HANDLED。是否已被应用取走工作事件不影响此规则;不比较类型、OA、S/E、状态或QU,但新请求仍须通过全局type_mask、COT、寻址、格式和值校验,此时尚不查点策略或时差。只增加dropped_requests,不增加rejected、busy_rejected或overloads;不覆盖原请求、不刷新决定期限、不生成新事件或应答。先检查到期,已到期事务不再适用此规则;其他点通过时效及点策略后才忙拒绝,COT=8仍按撤销处理。
|
||||
|
||||
决定期间同点激活的丢弃在时标判定之前;其他带时标激活在SELECTED匹配和忙判断之前执行第8节的时效检查。这样匹配的过期执行不会绕过检查,忙时其他点的过期请求也不会产生迟到的忙否定。
|
||||
|
||||
其后的顺序是SELECTED匹配→查点/点类型/直接点SELECT校验→实例忙或SELECT_EXECUTE点未选择执行→新建事务。走到点策略检查时,无CA/IOA点回47;类型不在该点掩码内、DIRECT点收到SELECT回否定7;空闲SELECT_EXECUTE点未选择便执行也回否定7。拒绝的新请求不建事务、不出工作事件或FINISHED,不改变原事务。点策略在忙检查之前,所以不存在的其他点不会被统一改为忙否定。撤销仍走前面的事务匹配,不因点表查询改变原有9应答。
|
||||
|
||||
SELECTED阶段的选择执行要求同会话、原站点注册编号、IOA、类型、OA,且值字节及屏蔽S/E后的命令字节相同。状态、QU/QL均参与比较,CP56不比较,允许选择和执行使用不同时标;45与58等跨类型组合仍为MISMATCH,不被后续点类型拒绝替代。浮点按原始字节比较,+0与−0不同。此阶段选择确认尚未交接时,通过时效及点策略检查的执行按忙拒绝并保留选择;确认交接后同点不匹配执行终结为MISMATCH,否定回显本次执行。匹配执行不重新查不可变点表,许可和模式已在选择时校验,类型完全一致保证沿用原策略。其他点的新激活先检查点策略,再忙拒绝。匹配前检查选择期限,到期选择不能复活。
|
||||
|
||||
撤销按会话、站点编号、IOA、类型、OA匹配,不比较值、状态或限定词,不判时差;带时标撤销仍须通过CP56格式检查。SELECT_WAIT、SELECTED、EXECUTE_WAIT中的匹配撤销复用事务存储,肯定DEACT_CON回显撤销请求。执行已经启动、事务已结束或没有匹配时否定撤销。发送接口已经返回OK的选择确认不能撤回,随后DEACT_CON按顺序交接。
|
||||
|
||||
## 3. 应用交互与设备结果
|
||||
|
||||
事件为纯值副本,身份包含模块实例、事务、工作事件序号和类型。Accept/Reject只接受已经取出且未消费的工作事件。模块使用自己保存的请求调用动作;调用者修改事件副本不能改变执行参数。
|
||||
事件为纯值副本,身份包含模块实例、事务、工作事件序号和类型。Accept/Reject只接受已经取出且未消费的工作事件。模块每次从已保存的规范原文解码请求;调用者修改事件副本不能改变执行参数。
|
||||
|
||||
状态类45–47及对应时标类型使用state和QU;48–50使用`value.normalized/scaled/short_float`及QL,state为0;51/64使用`value.bitstring`,state、qualifier及is_select均为0。normalized保留16位定点原始值,实际值为normalized/32768.0。带时标请求另含原始CP56(保留IV/SU)及换算后的UTC毫秒,非时标请求相关字段清零。毫秒值包含CP56的毫秒余数,不能只把整秒乘1000。
|
||||
|
||||
保存的原文再次解码失败属于内部错误。Accept在安排肯定确认和消费事件之前解码,失败按SERVICE_ERROR收尾且不调用动作;NextEvent失败不把未交付工作事件标为已读,已交付事务仍保留FINISHED义务。若终结时原文仍不可解码,只交付事务身份及SERVICE_ERROR,不把值字段当作动作参数;应用仍可读取终结事件并释放资源,避免坏原文永久占槽。
|
||||
|
||||
| 入口 | 成功后的含义 |
|
||||
|---|---|
|
||||
@@ -50,9 +85,17 @@ Get_Transaction仅查询当前尚占槽的事务:ENDED仍可查询active=false
|
||||
|
||||
状态依次为SELECT_WAIT、SELECTED、EXECUTE_WAIT、EXECUTING、ENDED;直接执行跳过选择阶段。EXECUTING内部另记录结果是否已报告、返回阶段是否关闭和确认/终止交接状态,避免重复动作、覆盖结果及重复终止。
|
||||
|
||||
期限采用Net单调毫秒;已用时间大于或等于期限即到期,时钟倒退按到期并计clock_errors。期限配置为0只禁用时长限制,正在决定、选择或等待设备结果时仍检查单调时钟倒退。决定期限从工作事件生成开始,包含事件尚未被应用取走的时间;选择和执行期限从动作返回后重新采样开始。这里的请求到达指Handle_Event受理时刻,包含Slave通知排队时间。
|
||||
期限采用Net单调毫秒;已用时间大于或等于期限即到期,时钟倒退按到期并计clock_errors。决定和执行期限配置为0只禁用时长限制,正在决定、选择或等待设备结果时仍检查单调时钟倒退;选择期限不得为0。决定期限从工作事件生成开始,包含事件尚未被应用取走的时间;选择和执行期限从相应动作返回STARTED后重新采样开始。这里的请求到达指Handle_Event受理时刻,包含Slave通知排队时间。
|
||||
|
||||
Accept/Reject消费交互后停止决定期限;Report_Result后停止执行期限。选择期限有意覆盖选择确认的发送等待,作为返校保持上限。执行超时不发ACT_TERM,已经执行动作所对应的肯定确认仍可继续提交;随后STOP或Cancel可以清除尚未提交的应答。结果报告后没有额外业务收尾期限,应用漏调Complete会持续占槽,直到明确取消或会话结束。
|
||||
`select_timeout_ms`是每个Command实例统一的选择有效期,仅用于SELECT_EXECUTE点,不是每点独立参数。默认30000ms,应用可在Config_Default之后、Create之前修改为所需非零值。它是选择保持的最长时间,不是必须等满的延时;主站收到选择确认后即可发送执行。
|
||||
|
||||
选择动作返回STARTED后进入SELECTED,并重新采样单调时钟开始计时;NULL选择动作同样计时。选择确认尚在等待发送时,选择有效期已经消耗,不以主站看到确认作为起点。Handle_Event在期限内受理匹配执行后转入EXECUTE_WAIT,停止选择计时,并从新的EXECUTE工作事件开始应用decision_timeout_ms,等待Accept/Reject。Handle_Event受理执行时若恰好到达选择期限边界,原选择也已失效,以SELECT_TIMEOUT结束,不能被迟到执行恢复。
|
||||
|
||||
选择超时后,须待应交付的FINISHED读完且事务回复完成交接或清理,才能回收事务槽。选择保持及收尾期间,其他点的新激活通过前序报文、时标和点策略校验后仍按忙拒绝。DIRECT点没有选择等待,但仍共享同一个事务槽,不能绕过已有选择或执行事务。
|
||||
|
||||
30秒可作为联调起点。主站自动紧接着发送执行时,可考虑10秒;需要人工确认时,可考虑30秒。这些是工程配置建议,应结合主站选择与执行的实际间隔、网络往返、选择确认发送排队及事件循环调度余量联调确定,不代表协议规定值。选择有效期与time_tag_max_delay_ms独立:前者限制已选择事务的保持时间,后者检查带时标激活受理时的新鲜度;二者也都不替代链路t0..t3。
|
||||
|
||||
Accept/Reject消费交互后停止决定期限;Report_Result后停止执行期限。执行超时不发ACT_TERM,已经执行动作所对应的肯定确认仍可继续提交;随后STOP或Cancel可以清除尚未提交的应答。结果报告后没有额外业务收尾期限,应用漏调Complete会持续占槽,直到明确取消或会话结束。
|
||||
|
||||
## 5. 通知、FIFO与返回信息
|
||||
|
||||
@@ -76,12 +119,41 @@ Handle_Event先校验来源并按Slave的FIFO消费连接/启停通知,不因
|
||||
|
||||
退出顺序:Command_Cancel,读空FINISHED并清理应用引用,Slave_Close,读空并分派Slave通知,Command_Destroy,移除站点,Slave_Destroy。动作回调只允许Get_Status/Get_Transaction,不得重入修改入口、推进网络或发布上报。
|
||||
|
||||
## 7. 固定存储、验证与扩展
|
||||
## 7. 布局、固定存储与验证
|
||||
|
||||
私有`COMMAND_LAYOUTS(X)`是唯一类型布局清单,记录type_id、value_length、has_se、has_time。X-macro分别展开只读布局表和字节数组union,规范长度按“9 + 值长度 + S/E字节数 + CP56长度”生成;`COMMAND_MAX_LENGTH`取该union的sizeof,目前为21字节,并静态检查不超过104的249字节ASDU上限。这是本模块14种控制命令的容量上界,不代表所有ASDU或其他业务的存储模型。
|
||||
|
||||
事务request_bytes、reply_bytes、独立回复槽及提交局部缓冲统一使用该容量,持久记录另存有效长度。复制、解析、包装和发送只使用规范有效长度,不能把sizeof(buffer)当作报文长度。原工作请求与撤销/失配回显分别保存,长短槽复用不会发送旧尾部。
|
||||
|
||||
S/E偏移只由`Se_Offset`计算,读取只能在已确认has_se的`Is_Select`或`Same_Command`中发生。51没有该字节,64相同偏移是CP56首字节,不能先读再判断。`Decode_Element`调用公共层公开的类型解码接口,不依赖内部信息对象布局表。布局、阶段支持掩码和实例type_mask分别表达“认识”“允许启用”和“本实例启用”,互不替代。
|
||||
|
||||
`IEC104_COMMAND_CAPACITY`默认跟随TCP服务容量;每实例一个事务槽,`IEC104_COMMAND_REPLY_CAPACITY`默认4。事务必要应答不依赖回复池剩余容量。池满只拒绝/丢新,不覆盖活动事务,不主动断开连接。Process每轮推进次数有界。实际sizeof及配置矩阵结果统一记录在[测试说明](../test/IEC104测试文档.md),不把宿主机结果当作其他目标的预算。
|
||||
|
||||
示例地址、动作与返回信息见[子站示例](../examples/IEC104子站示例.md)。Type45命令6001..6008对应Type1遥信1001..1008;Type46命令6101..6108对应Type3位置1101..1108,双点初值均为1。两类遥信均纳入示例站总召及遥信分组,逐批读取应用当前值,能反映遥控执行后的状态;点表及分组属于应用,不改变Command模块职责。
|
||||
示例地址、动作与返回信息见[子站示例](../examples/IEC104子站示例.md)。45/58命令6001..6008对应Type1遥信1001..1008;46/59命令6101..6108对应Type3位置1101..1108,双点初值均为1;49/62命令6301..6308写入Type11遥测2001..2008。应用持有24行命令点表,6008、6108、6308采用DIRECT,其余SELECT_EXECUTE,CA来自命令行配置。总召及对应分组逐批读取应用当前值,反映执行后的状态;命令许可和模式由模块按该表执行,物理点映射、限值及召唤分组仍属于应用。
|
||||
|
||||
验证覆盖TCP容量1/2与回复容量1/4、期限边界、动作只调用一次、通知优先、FIFO、部分写入、结果先于确认、撤销及站点引用,并使用真实本机TCP核对45/46流程。决定窗口内的同点激活丢弃不依赖内容相同,也不提供窗口外去重;事务释放后,相同ASDU按新请求处理,允许直接执行时仍可能再次输出。
|
||||
验证覆盖TCP容量1/2与回复容量1/4、独立手写的14种类型长度、值与时标校验、匹配、变长FIFO、期限边界、动作只调用一次、通知优先、部分写入、结果先于确认、撤销及站点引用,并使用真实本机TCP核对遥控、设定值、带时标执行和过期丢弃。测试期望不共用实现布局清单,避免表错时输入和期望一起错。决定窗口内的同点激活丢弃不依赖内容相同,也不提供窗口外去重;事务释放后,相同ASDU按新请求处理,允许直接执行时仍可能再次输出。
|
||||
|
||||
带时标58/59、遥调及并发不属于第一版。后续扩展需保持事件身份、引用与交接契约;结构体新增字段要求调用方一起重新编译,不承诺二进制布局兼容。
|
||||
扩展仍须保持事件身份、引用与交接契约;公开Request、Event、Config、Status新增字段后,库及调用方须一起重新编译,不承诺二进制布局兼容。新增类型需同步清单、解码分支和独立测试;新值类型或掩码范围外类型还涉及公开接口。容量会随清单最大长度增长,须重新测量目标内存;这里不提供跨业务统一存储管理,也不实现并发事务、Type70/102/105/107或突发上送。
|
||||
|
||||
## 8. 带时标激活与时间基准
|
||||
|
||||
应用调用`IEC104_Command_Set_Time_Base(self, utc_ms, base_ms)`提供同一时刻的UTC纪元毫秒和Net单调毫秒。句柄无效、动作回调内调用、UTC超出公共时间工具范围或base_ms晚于当前单调时间时返回false;失败不替换原基准。`Clear_Time_Base`在本站时间不可信时清除基准,动作回调内调用不生效。模块不读取Clock,不保存时间回调;STOP和断线保留基准,更新只影响随后受理的请求。
|
||||
|
||||
判定仅针对58–64的COT=6激活,在Handle_Event受理时做一次。公共CP56格式错误已经按请求校验回否定;格式合法后先检查IV及UTC换算,随后才应用max=`time_tag_max_delay_ms`:
|
||||
|
||||
| 条件 | 处理与计数 |
|
||||
|---|---|
|
||||
| IV=1或UTC换算失败 | 否定7,time_rejected与rejected加一;max=0仍拒绝 |
|
||||
| max=0 | 不比较时差,不要求时间基准 |
|
||||
| max非零且无基准、now早于base_ms、推算溢出或超出时间范围 | 否定7,time_rejected与rejected加一;单调时钟倒退另计clock_errors |
|
||||
| 站内UTC − 命令UTC ≥ max | time_expired加一;默认静默丢弃,negative_on_expired=true时回否定7并计rejected |
|
||||
| 命令UTC − 站内UTC ≥ max | 否定7,time_rejected与rejected加一 |
|
||||
| 其他 | 继续匹配选择、忙检查或创建事务 |
|
||||
|
||||
站内UTC由`utc_ms + (now - base_ms)`推算,先检查回退和加法范围。CP56按master_utc_offset_minutes换算,SU由公共工具处理,并加回毫秒余数。静默过期不计rejected或dropped_requests,不占事务槽、不生成工作事件或FINISHED;time_base_valid仅表示持有基准,并非每次查询都重新验证其时效。
|
||||
|
||||
clock_errors按发现异常的检查次数累计,事务期限检查和时间基准检查可能在同一请求中分别增加,不能把它当作异常请求数量。
|
||||
|
||||
执行请求过期时不改变已有选择,它继续保留至select_timeout_ms。撤销不做时差、IV或UTC换算判定,但仍检查CP56编码格式。决定期间同点激活先按原规则丢弃,不增加时间计数。默认静默丢弃避免迟到否定被主站误认为重试结果;max、IV策略、时区、过期响应和ACT_TERM应与主站互操作约定一致。
|
||||
|
||||
时效只在受理时检查,Accept前不再检查命令时标;受理后的等待由决定期限控制。默认10秒时差窗口加15秒决定期限,动作启动时命令可能已接近25秒旧。需要更严格限制时,应用可在动作中检查request.time_utc_ms并返回NOT_STARTED;这不是模块承诺的动作时效上限。
|
||||
|
||||
@@ -128,7 +128,7 @@ flowchart TD
|
||||
| `IEC104_APP_LAYER_PARAMETERS_DEFAULT` | 定义在 [IEC104_Types.h](../../104/IEC104_Types.h):Type ID 1、VSQ 1、COT 2、默认 OA 0、CA 2、IOA 3、ASDU 最大 249 字节 |
|
||||
| 静态存储容量 | 编译期由 [IEC104_TcpServer_Config.h](../../104/IEC104_TcpServer_Config.h) 配置,默认可创建 1 个服务。与上述运行参数分开 |
|
||||
|
||||
业务模块有各自的Config_Default/Create,不能把业务期限填进Slave的链路配置。遥控类型掩码、三个期限、ACT_TERM策略及编译期实例/应答池容量见[遥控创建与配置](#flow-command-create);这些期限须由应用与网络等待条件合并,Slave_Prepare不会自动读取业务模块状态。
|
||||
业务模块有各自的Config_Default/Create,不能把业务期限填进Slave的链路配置。命令点表、全局类型掩码、三个期限、ACT_TERM策略及编译期实例/应答池容量见[遥控创建与配置](#flow-command-create);这些期限须由应用与网络等待条件合并,Slave_Prepare不会自动读取业务模块状态。
|
||||
|
||||
104 专用的默认参数宏保留在 104 接入层。共用 `IEC60870_AppLayerParameters_t` 只描述布局,不替调用方选择传输配置。业务一般通过 `IEC104_Slave_Get_Application_Layer_Parameters` 或事件连接的对应 getter 取得标准 104 参数,无需自行维护宏副本。
|
||||
|
||||
@@ -290,41 +290,61 @@ Execute结果须按枚举分支:WAIT先处理Slave通知,EMPTY只表示没
|
||||
|
||||
<a id="flow-command"></a>
|
||||
|
||||
### 1.5 接入单点、双点遥控模块
|
||||
### 1.5 接入遥控、遥调与带时标命令模块
|
||||
|
||||
`IEC104_Command`接手Type45单点命令、Type46双点命令,提供选择、执行、撤销、期限和返回信息顺序管理。每个Slave至多一个实例,每实例至多一个未释放事务;不同站点的遥控也互斥。点表、闭锁、远方/就地、真实输出及设备忙状态由应用提供。模块使用静态池,不分配内存、不保存回调,只在Accept中调用本次传入的动作。接口声明与全部返回值见[API第25节](IEC104_API接口汇总.md#file-25),协议校验及内部存储见[遥控设计](IEC104_Command_设计架构.md)。
|
||||
`IEC104_Command`接手Type45–51及58–64,提供按点准入、选择、执行、撤销、时标判定、期限和返回信息顺序管理。默认全局启用14种类型,但点表为空,必须提供具体点才能执行。每个Slave至多一个实例,每实例至多一个未释放事务;不同站点的命令也互斥。应用提供有序只读点表,按CA/IOA配置类型和模式,管理闭锁、远方/就地、限值、真实输出及设备忙状态。模块使用静态池,不分配内存、不保存回调,只在Accept中调用本次传入的动作。接口声明与全部返回值见[API第25节](IEC104_API接口汇总.md#file-25),协议校验及内部存储见[遥控设计](IEC104_Command_设计架构.md)。
|
||||
|
||||
<a id="flow-command-create"></a>
|
||||
|
||||
#### 1.5.1 创建实例与配置
|
||||
|
||||
编译`104/business/IEC104_Command.c`及Slave依赖,头文件路径包含`104/`、`104/business/`和`common/`。Slave句柄创建成功后即可创建遥控实例,允许在Slave_Init之前或之后,但必须早于第一次消费Slave通知。否则模块会漏掉CONNECTED/ACTIVATED,不能靠最终连接状态补出历史启停顺序。站点由Slave统一注册,CA不放进Command配置;当前不接受广播CA=65535。
|
||||
编译`104/business/IEC104_Command.c`及Slave依赖,头文件路径包含`104/`、`104/business/`和`common/`。Slave句柄创建成功后即可创建遥控实例,允许在Slave_Init之前或之后,但必须早于第一次消费Slave通知。否则模块会漏掉CONNECTED/ACTIVATED,不能靠最终连接状态补出历史启停顺序。站点由Slave统一注册,Command点表按CA引用;允许先配置尚未注册的CA,实际请求仍检查注册身份,不接受广播CA=65535。
|
||||
|
||||
以下C函数只负责创建默认实例。调用方须检查返回NULL、清理已创建资源;成功后把句柄保存到所属事件循环,Slave寿命须覆盖Command_Destroy。
|
||||
以下C函数为CA=1配置两个同类型、不同模式的点;静态const点表保证借用寿命。调用方须注册对应站点、检查返回NULL并清理已创建资源;成功后把句柄保存到所属事件循环,Slave及点表的寿命须覆盖Command_Destroy。
|
||||
|
||||
```c
|
||||
#include "IEC104_Command.h"
|
||||
|
||||
static IEC104_Command_t *Create_Command(IEC104_Slave_t *slave)
|
||||
{
|
||||
static const IEC104_CommandPoint_t points[] = {
|
||||
{1U, 6001U, IEC104_COMMAND_TYPE_BIT(45U) | IEC104_COMMAND_TYPE_BIT(58U),
|
||||
IEC104_COMMAND_MODE_SELECT_EXECUTE},
|
||||
{1U, 6008U, IEC104_COMMAND_TYPE_BIT(45U) | IEC104_COMMAND_TYPE_BIT(58U),
|
||||
IEC104_COMMAND_MODE_DIRECT}
|
||||
};
|
||||
IEC104_CommandConfig_t config;
|
||||
IEC104_Command_Config_Default(&config);
|
||||
config.type_mask = IEC104_COMMAND_TYPE_BIT(45U) | IEC104_COMMAND_TYPE_BIT(58U);
|
||||
config.points = points;
|
||||
config.point_count = sizeof(points) / sizeof(points[0]);
|
||||
return IEC104_Command_Create(slave, &config);
|
||||
}
|
||||
```
|
||||
|
||||
| 配置 | 默认行为 | 修改时的约束 |
|
||||
|---|---|---|
|
||||
| type_mask | 接手45、46 | 不得为0;本版其他类型位使Create失败,未启用类型返回IGNORED |
|
||||
| select_required_mask | 45、46均须先选择 | 必须为type_mask子集;只清除允许直接执行类型的对应位 |
|
||||
| type_mask | 0x3FFF,接手45–51/58–64 | 不得为0;可裁剪,保留bit14/15不能置位,未启用类型返回IGNORED |
|
||||
| points / point_count | NULL / 0,空点表 | NULL与0必须成对;非空表按CA再IOA严格升序且唯一,Create借用至Destroy |
|
||||
| decision_timeout_ms | 15000ms | 从工作事件生成开始计时;0只禁用时长限制 |
|
||||
| select_timeout_ms | 30000ms | 不得为0;含选择确认等待发送的时间 |
|
||||
| select_timeout_ms | 30000ms | 每实例统一、仅选择模式;不得为0,在Config_Default后、Create前调整,详见[选择有效期](IEC104_Command_设计架构.md#4-状态与期限) |
|
||||
| execute_timeout_ms | 60000ms | 从执行动作返回STARTED至Report_Result;0只禁用时长限制 |
|
||||
| send_act_term | true | false时成功、失败都不发ACT_TERM,仍须Complete |
|
||||
| act_term_on_failure | false | 仅send_act_term=true时生效;失败终止的P/N仍为0,只表示流程结束 |
|
||||
| time_tag_max_delay_ms | 10000ms | 0只关闭时差检查,仍拒绝IV及UTC换算失败 |
|
||||
| master_utc_offset_minutes | 480 | 主站标准时区分钟数,范围−1439..1439;SU由公共时间工具处理 |
|
||||
| negative_on_expired | false | 过期激活静默丢弃;true改为否定确认 |
|
||||
|
||||
静态池容量由编译宏`IEC104_COMMAND_CAPACITY`控制,默认与TCP服务容量相同;每实例独立应答槽由`IEC104_COMMAND_REPLY_CAPACITY`控制,默认4。事务自带确认、终止及撤销/失配应答存储,独立槽处理忙拒绝和校验否定,不能用增加应答槽开启多个事务。重复绑定同一Slave、池满或配置非法时Create返回NULL。
|
||||
|
||||
每点设置common_address、ioa、type_mask和mode:CA为1..65534,IOA为1..0xFFFFFF,点掩码非零且只含14个已知类型位;可包含全局未启用位,实际取交集。mode仅DIRECT或SELECT_EXECUTE;51/64不能放入SELECT_EXECUTE点。NULL/0是合法默认空表,但不会执行点命令。非NULL/0、NULL/非零、点表无序/重复、非法范围及元素数乘法越界都会使Create失败。
|
||||
|
||||
点表是借用存储,Create不复制、不保存查点回调;从Create到Destroy不可修改或释放。更新时先Cancel、处理FINISHED并完成应用收尾,Slave_Close后读空并分派旧通知,再Destroy;以新表Create后重新启动Slave、建立连接,按FIFO交付完整CONNECTED/ACTIVATED,并重新设置时间基准。新Command不继承旧会话,不能直接挂回旧连接热换点表。原select_required_mask字段已移除,旧调用方须改为点表并重新编译。全局type_mask仍可裁剪;示例用赋值明确选择已接入的六种类型,不能用`|=`裁剪全类型默认值。
|
||||
|
||||
启用带时标类型后,由应用把可信UTC纪元毫秒与同一时刻的Net单调毫秒交给`IEC104_Command_Set_Time_Base`。校时动作成功时先在应用保存request->utc_ms/base_ms,待`ClockSynchronization_Execute_Next`返回后再更新Command;不要在动作回调内跨模块调用修改入口。时间不可信时调用`Clear_Time_Base`,STOP/断线不会自动清除基准。示例system模式还在启动及每60秒读取一次Clock以吸收系统时间调整,simulated模式只使用成功校时产生的基准。
|
||||
|
||||
时标检查在Handle_Event受理激活时完成,早于SELECTED匹配及忙判断;IV、换算错误、无基准或超前回否定,过期默认不生成应答和事件。选择通过而执行过期时,原选择保留至选择期限。max=0不需要基准,但仍校验CP56、IV及UTC换算。该检查不在Accept前重做,默认受理窗口与决定期限可能使动作开始时的命令年龄接近25秒;更严格的现场策略可在动作中检查request.time_utc_ms。完整边界见[时间基准API](IEC104_API接口汇总.md#command-api-time-base)。
|
||||
|
||||
<a id="flow-command-dispatch"></a>
|
||||
|
||||
#### 1.5.2 先分派Slave通知,再读取遥控事件
|
||||
@@ -333,7 +353,7 @@ static IEC104_Command_t *Create_Command(IEC104_Slave_t *slave)
|
||||
|
||||
| Command_Handle_Event结果 | 应用下一步 |
|
||||
|---|---|
|
||||
| EVENT_HANDLED | 此请求已由遥控接手;包括校验否定、忙拒绝、过载丢弃及决定窗口内同点激活的静默丢弃,不能再次兜底 |
|
||||
| EVENT_HANDLED | 此请求已由遥控接手;包括校验否定、忙拒绝、过载丢弃、决定窗口内同点激活及过期激活的静默丢弃,不能再次兜底 |
|
||||
| EVENT_IGNORED | I帧可继续交给后续业务;未启用类型、未激活、视图不可用或旧代次可能走此结果 |
|
||||
| EVENT_ERROR | 记录来源、参数或服务错误并进入应用错误处理;不要把它当IGNORED继续执行命令 |
|
||||
|
||||
@@ -347,11 +367,13 @@ Handle_Event消费当前通知时只校验来源,不能在外层用`Check_Requ
|
||||
|
||||
#### 1.5.3 选择、执行匹配及应用决定
|
||||
|
||||
空闲收到S/E=1、COT=6,模块生成SELECT并进入SELECT_WAIT;S/E=0只有在该类型允许直接执行时才生成EXECUTE,否则否定ACT_CON。应用取到工作事件后检查点表和策略,调用Accept或Reject。IOA不存在用`IEC104_COMMAND_REJECT_UNKNOWN_IOA`回47;其他策略拒绝用`IEC104_COMMAND_REJECT_NEGATIVE`回否定7。
|
||||
新激活通过报文、时标及已有选择匹配后,模块按CA/IOA二分查点。无点回47,点类型不符或DIRECT点收到S/E=1回否定7;点策略通过后才检查实例忙和SELECT_EXECUTE点未选择执行。空闲SELECT_EXECUTE点的选择生成SELECT,匹配执行才生成EXECUTE;DIRECT点的执行直接生成EXECUTE。51/64没有S/E,只能配置为DIRECT。被拒的新请求不建事务、不出工作事件或FINISHED,已有事务继续。
|
||||
|
||||
SELECT_WAIT、EXECUTE_WAIT期间,同会话generation、同station_id、同IOA的合法COT=6激活静默丢弃,返回HANDLED;不比较类型、OA、S/E、状态或QU,但type_mask及全部既有寻址、格式和值校验仍优先。无论应用是否已取走原工作事件,都继续处理该事件:丢弃不覆盖原请求、不刷新决定期限、不生成新事件或应答,只增加dropped_requests,不增加rejected、busy_rejected或overloads。期限到达后先终结原事务,再处理新请求;其他点仍忙拒绝,COT=8仍按撤销规则处理。
|
||||
应用按type_id读取state、QU/QL及value对应union成员,检查权限、闭锁、动态设备可用性和限值后调用Accept或Reject。静态点存在性已由模块检查;动态设备点不可用仍可用`IEC104_COMMAND_REJECT_UNKNOWN_IOA`回47,越限等策略拒绝用`IEC104_COMMAND_REJECT_NEGATIVE`回否定7。
|
||||
|
||||
Accept先确认工作事件仍有效并准备确认存储,再消费事件、至多调用一次action。SELECT可传NULL,视为选择成功且select_effect=false;EXECUTE必须提供动作。action须短时返回,不推进Slave、不发布上报、不保留request指针;回调内只允许查询本实例Get_Status/Get_Transaction。异步设备工作由应用另存必要值和引用,设备结果回到同一事件循环提交。
|
||||
SELECT_WAIT、EXECUTE_WAIT期间,同会话generation、同station_id、同IOA的COT=6激活通过前置报文校验后静默丢弃,返回HANDLED;不比较类型、OA、S/E、状态或QU,全局type_mask及寻址、格式和值校验仍优先,此时尚不查点策略或时差。无论应用是否已取走原工作事件,都继续处理该事件:丢弃不覆盖原请求、不刷新决定期限、不生成新事件或应答,只增加dropped_requests,不增加rejected、busy_rejected或overloads。期限到达后先终结原事务,再处理新请求;其他点通过时效和点策略后才忙拒绝,COT=8仍按撤销规则处理。
|
||||
|
||||
Accept先确认工作事件仍有效并从保存的原文解码请求,再准备确认、消费事件、至多调用一次action。内部解码失败返回ERROR并按SERVICE_ERROR收尾,不发肯定确认或调用动作。SELECT可传NULL,视为选择成功且select_effect=false;EXECUTE必须提供动作。action须短时返回,不推进Slave、不发布上报、不保留request指针;回调内只允许查询本实例Get_Status/Get_Transaction,不允许Set/Clear_Time_Base。异步设备工作由应用另存必要值和引用,设备结果回到同一事件循环提交。
|
||||
|
||||
| 动作结果 | 选择阶段 | 执行阶段 |
|
||||
|---|---|---|
|
||||
@@ -361,7 +383,7 @@ Accept先确认工作事件仍有效并准备确认存储,再消费事件、
|
||||
|
||||
`Accept==REPLY_OK`只表示事件已消费,以上三种结果都可返回OK。应用应检查自己保存的动作结果,或用Get_Transaction确认`active && phase==IEC104_COMMAND_PHASE_EXECUTING`,再安排执行结果流程;提交确认时可能已遇STOP或发送失败,所以STARTED也不保证返回后事务仍有效。选中后等待新的EXECUTE事件,不能再次Accept旧SELECT事件。
|
||||
|
||||
SELECTED阶段选择确认交给发送层后、选择未到期时,执行须匹配原会话、station_id、IOA、类型、OA以及屏蔽S/E后的命令字节(状态与QU)。此阶段选择确认尚未交接时收到执行,一律忙拒绝并保留选择;交接后同一点不匹配执行回否定7并以MISMATCH结束选择。其他点执行、SELECTED中的重复选择及EXECUTING/ENDED中的新激活仍忙拒绝,不破坏已有事务。
|
||||
SELECTED阶段选择确认交给发送层后、选择未到期时,通过时效检查的执行须匹配原会话、station_id、IOA、类型、OA、原始值字节,以及屏蔽S/E后的命令字节(状态与QU/QL);不比较CP56。+0与−0原始字节不同,45与58等类型不同,均先判MISMATCH,不被后续点策略拒绝替代。匹配执行不再查不可变点表。选择确认尚未交接时,通过时效和点策略的执行忙拒绝并保留选择;其他点执行、SELECTED中的重复选择及EXECUTING/ENDED中的新激活先过点策略再忙拒绝,不破坏已有事务。
|
||||
|
||||
| Accept / Reject结果 | 是否可重试 |
|
||||
|---|---|
|
||||
@@ -457,7 +479,7 @@ WAIT_FINISHED: 继续Process和NextEvent,不重复Complete,不再Submit_Retu
|
||||
|
||||
Handle_Event在有效遥控I帧的匹配前检查;Process、NextEvent及应用应答入口在允许推进时先检查会话,再检查期限。未读通知优先于这些推进,但不能挡住Handle_Event消费通知;已存在FINISHED直接交付。主站命令的“到达”指Handle_Event受理时刻,含Slave通知排队时间,不是网络成帧时间。
|
||||
|
||||
Accept/Reject后决定计时停止;Report_Result后执行计时停止,不因后续发送WAIT超时。选择期限有意包含选择确认的发送等待,限制返校最长保持时间。报告结果后漏调Complete会持续占槽,直到应用Cancel或会话结束;链路和本地发送期限仍独立生效,见[期限查询](#flow-deadlines)。
|
||||
Accept/Reject后决定计时停止;Report_Result后执行计时停止,不因后续发送WAIT超时。选择有效期不是必须等满的延时,匹配执行受理后改由决定期限管理;完整计时、排队及选值说明见[状态与期限](IEC104_Command_设计架构.md#4-状态与期限)。报告结果后漏调Complete会持续占槽,直到应用Cancel或会话结束;链路和本地发送期限仍独立生效,见[期限查询](#flow-deadlines)。
|
||||
|
||||
<a id="flow-command-abort"></a>
|
||||
|
||||
@@ -759,7 +781,7 @@ IEC60870_Asdu_Get_Data(&event.asdu, &bytes, &length)
|
||||
|
||||
解析视图 `info` 借用参数和原文字节,二者在取对象期间必须有效且不变。`Get_Element` 复制出具体对象,但输出结构须由 Type ID 选择;尺寸足够不能代替正确的 C 类型。若随后改写事件的 COT/P/N,不能继续把旧解析视图当作更新后的公共头。
|
||||
|
||||
以上是自定义业务直接使用公共编解码器的流程。交给Command_Handle_Event的45/46由模块按协议错误优先级完成校验,应用不先按“完整解析失败就忽略”过滤它,也不另发ACT_CON;应用从SELECT/EXECUTE事件开始检查点表与策略,见[遥控通知分派](#flow-command-dispatch)。
|
||||
以上是自定义业务直接使用公共编解码器的流程。交给Command_Handle_Event的45–51/58–64由模块按协议错误优先级及命令点表完成校验,应用不先按“完整解析失败就忽略”过滤它,也不另发ACT_CON;应用从SELECT/EXECUTE事件开始检查设备动态策略,见[遥控通知分派](#flow-command-dispatch)。
|
||||
|
||||
### 6.3 延迟处理、事件复制与连接寿命
|
||||
|
||||
@@ -1324,7 +1346,7 @@ Close 后读空事件,也可以再次 Init 重开;新服务和连接的身
|
||||
Type100种类规则:104/business/IEC104_GeneralInterrogation.c
|
||||
计数量读取/冻结/复位:104/business/IEC104_CounterInterrogation.c
|
||||
Type103校时校验与显式动作:104/business/IEC104_ClockSynchronization.c
|
||||
Type45/46选择执行、结果及返回信息:104/business/IEC104_Command.c
|
||||
Type45–51/58–64选择执行、时标、结果及返回信息:104/business/IEC104_Command.c
|
||||
共用发送接口分派: IEC60870_Slave.c → IEC104_Slave.c 内的发送适配器
|
||||
ASDU 与信息对象: IEC60870_Asdu.c → IEC60870_InformationObjects.c
|
||||
监听和网络调度: IEC104_TcpServer.c
|
||||
@@ -1337,5 +1359,5 @@ ASDU 与信息对象: IEC60870_Asdu.c → IEC60870_InformationObjects.c
|
||||
平台非阻塞 I/O: IEC104_Net_Windows.c
|
||||
```
|
||||
|
||||
库提供命令、校时、总召、参数和文件等信息对象的编解码,以及响应提交接口。召唤引擎已实现站/分组总召和计数量读取/冻结/复位;ClockSynchronization已实现Type103校验、补偿、期限及原文确认;Command已实现Type45/46选择执行、撤销、三类期限和按事务提交返回信息。遥调47..51、带时标命令58..64、参数和文件业务尚未接入,不能把对象编解码支持等同于完整业务支持。业务权限和硬件操作仍由应用提供;Time转换、Clock墙上时间及Net单调计时用途不同,默认示例只更新模拟时钟和模拟遥控点值。
|
||||
库提供命令、校时、总召、参数和文件等信息对象的编解码,以及响应提交接口。召唤引擎已实现站/分组总召和计数量读取/冻结/复位;ClockSynchronization已实现Type103校验、补偿、期限及原文确认;Command已实现Type45–51/58–64选择执行、撤销、值与时标判定、三类期限和按事务提交返回信息。参数和文件业务尚未接入,不能把对象编解码支持等同于完整业务支持。业务权限和硬件操作仍由应用提供;Time转换、Clock墙上时间及Net单调计时用途不同,默认示例只更新模拟时钟和模拟点值。
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
> **当前接口同步**:2026-10-08。已新增 `IEC104_Receiver.c/h`,并从删除前备份原样恢复 `IEC104.c/h`及旧全局接口,两套接收实现共存。上面的2026-09-23同步说明为历史记录;本文主要描述Receiver,旧入口边界另行注明。
|
||||
> **测试清理**:2026-10-19。接口过期的旧回归测试及专用辅助文件已删除,当前测试入口及覆盖范围见[测试说明](../test/IEC104测试文档.md)。
|
||||
> **信息对象同步**:2026-10-21。`IEC60870_InformationObjects.c/h`提供12种监视、18种命令的独立对象编解码;`IEC60870_Asdu.c/h`统一维护公共头、VSQ/SQ、容量、对象分派及原文应答。编码经对象函数表,解码按Type ID分派;带时标类型复用基础值处理及公共CP56工具。该模块由业务显式调用,不改变Receiver准入或链路序号处理;当时实际总召、校时和遥控流程仍待业务接入。接口及示例见[README](README.md#asdu信息对象模块)。
|
||||
> **业务同步**:2026-10-30。总召、计数量、Type103校时及Type45/46遥控已有独立业务模块;遥调和带时标命令仍待实现。遥控采用单事务、显式动作及返回信息提交,设备策略和物理输出由应用提供,见[遥控设计](IEC104_Command_设计架构.md)。
|
||||
> **业务同步**:2026-10-31。总召、计数量、Type103校时及Command业务已实现;Command统一处理Type45–51及58–64,默认全局启用14种但点表为空。应用提供只读点表,按CA/IOA配置允许类型和直接/选择执行模式,51/64只能直接执行。采用单事务、显式动作及返回信息提交,设备策略和物理输出由应用提供,见[遥控设计](IEC104_Command_设计架构.md)。
|
||||
> **TCP接入同步**:2026-10-15。`IEC104_Connection.c/h`负责子站连接调度;`IEC104_TcpServer.c/h`提供IPv4监听及非阻塞收发,Windows依赖在Net后端。业务通过Create取得静态池不透明句柄,使用Init、Prepare/Process或Poll、NextEvent、Enqueue_Event/Send_Response、Get_Status/Get_Remote_Address;Close_Connection只断开指定代次主站,Close整个服务后读空事件再Destroy。公开头文件只依赖`IEC104_Types.h`及标准类型。构建和业务接入见 [TCP服务设计](IEC104_TcpServer_设计架构.md)。
|
||||
> **子站入口同步**:2026-10-23。`IEC104_Slave`统一管理服务、调度和应答,NextEvent自动提供ASDU视图及原连接接口;业务无需手动绑定generation。延迟任务通过Copy_Event复制原文并重建自引用,旧请求在重连、重新Init和服务槽复用后仍被隔离。共享TCP值类型已迁入`IEC104_TcpTypes.h`。
|
||||
> **业务边界**:子站业务从Slave接入,Slave内部调用TcpServer。本文的Receiver、Connection、SendManager及链路调用说明面向内部实现;业务不创建或驱动这些对象,不持有内部借用视图。业务可使用Codec和公共时间工具处理NextEvent返回的ASDU副本。
|
||||
@@ -470,8 +470,8 @@ Receiver已实现每连接成帧和完整APDU交付;独立发送队列、业
|
||||
| `t1/t2/t3`、`k`和`w`调用时机 | Connection + TcpServer(已实现) | Poll使用单调时间推进Tick,执行确认、探测和超时收尾;被动监听不发起TCP连接,未实现主站`t0`建连流程 |
|
||||
| I/S/U实际发送 | TcpServer + Connection(已实现) | Prepare取得待发字节,send后立即回报增量;部分发送下轮续传,业务不再直接调用底层完成接口 |
|
||||
| 总召、计数量召唤与Type 103校时 | 独立业务模块(已实现) | 通过Slave事件及共用站点表分派,总召/计数量使用业务事件;校时由Execute_Next显式执行,确认回显原时标,见[时钟同步设计](IEC104_ClockSynchronization_设计架构.md) |
|
||||
| 单点、双点遥控(Type45/46) | IEC104_Command(已实现) | 独立静态池、单事务互斥;管理选择执行、撤销、三类期限、原文确认及按事务提交返回信息,见[遥控设计](IEC104_Command_设计架构.md) |
|
||||
| 遥调及带时标命令(47..51、58..64) | 待实现业务模块 | 公共信息对象已提供编解码;尚未接入选择执行、设备动作和时标策略 |
|
||||
| 单点、双点遥控(Type45/46) | IEC104_Command(已实现) | 独立静态池、单事务互斥;按CA/IOA点表管理类型、直接/选择执行模式,处理撤销、三类期限、原文确认及返回信息,见[遥控设计](IEC104_Command_设计架构.md) |
|
||||
| 遥调及带时标命令(47..51、58..64) | IEC104_Command(已实现) | 与45/46共用事务和FIFO;按类型解析值与限定词,51/64直接执行;应用提供时间基准,受理带时标激活时检查时效 |
|
||||
| 实际遥信/遥测数据源、输出及设备设时 | 应用接入层 | 按业务模块请求读取点表或执行设备动作;示例提供模拟点表、遥控输出和模拟时钟,协议库不自动操作硬件 |
|
||||
|
||||
### 10.2 统一连接上下文
|
||||
@@ -529,6 +529,6 @@ I帧完成接口要求快照的 `N(S)==sent_vs`,只推进本地完成边界和
|
||||
| 2(已实现) | 接入发送前准备、部分写入续传及独立确认记录,补齐实际I/O和收发串行调度 | 发出 `N(S)=0` 后收到 `N(R)=1` 能正确确认并释放原ASDU;发送失败不重复推进状态,旧确认不清除新增待确认数据 |
|
||||
| 3(已实现) | 连接生命周期、U 控制、定时器及窗口策略 | 受控传输与时间事件下可验证启动、停止、心跳、超时和窗口边界;序号错误停止当前批次并关闭连接 |
|
||||
| 4(对象及四类业务已实现) | 公共对象编解码、总召/计数量、校时及Type45/46遥控;继续接入真实数据源和设备输出 | 验证地址路由、召唤进度、校时原文确认、遥控选择执行/撤销/期限及返回信息顺序;模拟模式不设系统时间,硬件设时、实际输出和主站联调须另行验收 |
|
||||
| 5(待实现) | 遥调47..51及带时标命令58..64 | 补充按类型匹配、时标解码及延迟策略,再扩展应用接口与回归 |
|
||||
| 5(已实现) | 遥调47..51及带时标命令58..64 | 私有布局统一推导长度与容量,公共解析器校验值和CP56,按值及QU/QL匹配;时间基准与过期策略由配置和应用接入,实际主站互操作仍须联调 |
|
||||
|
||||
---
|
||||
|
||||
@@ -37,7 +37,7 @@ Slave提供[共用站点表](IEC104_API接口汇总.md#station-registry):应
|
||||
| `business/IEC104_GeneralInterrogation.c/h` | Type100规则及兼容的Interrogation_Create入口 |
|
||||
| `business/IEC104_CounterInterrogation.c/h` | Type101规则、创建及一次动作执行入口;见[计数量设计](IEC104_CounterInterrogation_设计架构.md) |
|
||||
| `business/IEC104_ClockSynchronization.c/h` | Type103校时校验、显式动作及原文确认;见[时钟同步设计](IEC104_ClockSynchronization_设计架构.md) |
|
||||
| `business/IEC104_Command.c/h` | Type45/46遥控、选择执行、撤销、三类期限及返回信息;见[遥控设计](IEC104_Command_设计架构.md) |
|
||||
| `business/IEC104_Command.c/h` | Type45–51/58–64遥控、遥调、按点模式、选择执行、撤销、时标判定及返回信息;见[遥控设计](IEC104_Command_设计架构.md) |
|
||||
| `IEC104_TcpTypes.h` | Slave与TcpServer共用的配置、调度、事件和状态值类型,无服务操作接口 |
|
||||
| `IEC60870_InformationObjects.c/h` | 67种独立信息对象,覆盖监视、命令、初始化、参数和文件;编码通过只读函数表分派,支持变长文件段 |
|
||||
| `IEC60870_Time.c/h` | 101/104共用时间工具:CP16/CP24/CP56Time2a编解码、本地标准时间转换、SU修正、日历/星期和纪元秒数工具;使用约定见[时间工具设计](../common/IEC60870_Time_设计架构.md) |
|
||||
@@ -70,7 +70,7 @@ Slave提供[共用站点表](IEC104_API接口汇总.md#station-registry):应
|
||||
| 104站/分组总召 | 在Slave及其依赖之外加入`104/business/IEC104_Interrogation.c`和`104/business/IEC104_GeneralInterrogation.c`,头文件搜索路径增加`104/business/`;应用按QOI选点表,响应NEED_DATA提交数据 |
|
||||
| 104计数量召唤 | 引擎加`104/business/IEC104_CounterInterrogation.c`,头文件搜索路径增加`104/business/`;与总召分别创建,状态通知交付两边,动作通过Execute_Begin执行 |
|
||||
| 104时钟同步 | Slave依赖加`104/business/IEC104_ClockSynchronization.c`,独立实例及静态池;只由Execute_Next执行同步action,模块不依赖Clock设备适配 |
|
||||
| 104遥控 | Slave依赖加`104/business/IEC104_Command.c`,头文件搜索路径增加`104/business/`;每Slave一个实例、一个事务,Accept显式执行动作,应用报告结果和提交返回信息 |
|
||||
| 104遥控/遥调 | Slave依赖加`104/business/IEC104_Command.c`,使用公共信息对象和Time解析;每Slave一个实例、一个事务,Accept显式执行动作,应用报告结果、提交返回信息并提供带时标命令的时间基准;模块不读取Clock |
|
||||
| 101/104公共时间工具 | `IEC60870_Time.c`,对已有时间值进行日历校验、时间转换及编解码 |
|
||||
| 101/104时间源:Windows系统时钟 | `IEC60870_Clock.c`、`IEC60870_Time.c`;`IEC60870_CLOCK_USE_RTC=0`(默认),Clock.c直接使用Windows的Kernel32接口 |
|
||||
| 101/104时间源:RTC预留接口 | 上述两个源文件,定义`IEC60870_CLOCK_USE_RTC=1`,另需板级驱动实现`IEC60870_Clock_RTC_Read/Set`;具体芯片驱动暂不提供 |
|
||||
@@ -128,7 +128,7 @@ I/S的启停准入和停止阶段立即确认规则集中在 `IEC104_Link.c` 的
|
||||
|
||||
公共层仅需 `IEC60870_Asdu.c`、`IEC60870_InformationObjects.c`、`IEC60870_Codec.c`、`IEC60870_Time.c`;头文件依赖也不包含任何104模块。101接入提供约定的字段宽度和容量,104接入提供标准2/2/3及249字节上限。两种接入共用同一套对象构造和解析接口。
|
||||
|
||||
业务包含`IEC104_Slave.h`,取得`Slave_NextEvent`交付的I帧后可直接使用ASDU视图并解析具体对象,或先构造ASDU再交给发送接口。ASDU编解码层不分配内存、不操作连接、不读取或设置系统时钟;共用连接接口可构造并提交确认/终止应答。站/分组总召可交给IEC104_Interrogation管理校验、分批、撤销、期限和重试,应用响应业务事件提交数据,自行维护IOA、分组及遍历状态;Type45/46的选择/执行由IEC104_Command管理,Type103由独立校时模块管理,权限策略及设备动作仍由应用接入。
|
||||
业务包含`IEC104_Slave.h`,取得`Slave_NextEvent`交付的I帧后可直接使用ASDU视图并解析具体对象,或先构造ASDU再交给发送接口。ASDU编解码层不分配内存、不操作连接、不读取或设置系统时钟;共用连接接口可构造并提交确认/终止应答。站/分组总召可交给IEC104_Interrogation管理校验、分批、撤销、期限和重试,应用响应业务事件提交数据,自行维护IOA、分组及遍历状态;Type45–51/58–64由IEC104_Command管理,Type103由独立校时模块管理,权限策略及设备动作仍由应用接入。
|
||||
|
||||
| 层次 | 职责 |
|
||||
|---|---|
|
||||
@@ -324,9 +324,11 @@ BEGIN携带实际CA、station_id和QOI=20..36;应用检查数据源并决定
|
||||
|
||||
调用过action的确认走Try,错误校验应答走普通HIGH;WAIT只重试确认,STOP取消未交接任务但不回滚时钟。广播动作一次,快照目标分别确认;满槽丢新并计数,不断链。同内容的新请求仍执行,可能再次回拨。持续NORMAL发布可能推迟Try确认,应用通过包含回调执行期的confirm_pending串行协调新的带时标上报。默认示例只设模拟时钟,`--clock system`才调用Windows时间源。完整契约见[时钟同步设计](IEC104_ClockSynchronization_设计架构.md)和[调用流程](IEC104_完整调用流程.md#flow-clock-synchronization)。
|
||||
|
||||
### 单点、双点遥控业务
|
||||
### 遥控、遥调与带时标命令业务
|
||||
|
||||
[Command](../../104/business/IEC104_Command.h)处理Type45/46、COT=6激活与COT=8撤销;默认两种类型都须先选择。每个Slave只能绑定一个实例,同一实例从创建事务到读取FINISHED并交接完应答期间一直忙,所有站点的新遥控互斥。Type47..51及58..64未接手,继续交给后续处理器或44兜底。
|
||||
[Command](../../104/business/IEC104_Command.h)处理Type45–51及58–64、COT=6激活与COT=8撤销;默认全局type_mask=0x3FFF,但points=NULL、point_count=0,不接入任何可执行点。应用提供按CA再IOA严格升序且唯一的只读点表,每点配置允许类型和DIRECT或SELECT_EXECUTE;51/64没有S/E位,只能采用DIRECT。Create借用点表至Destroy,不复制、不允许热更新;实际受理类型取全局和点掩码的交集。无点的新激活回47,点类型或模式不符回否定7,不生成工作事务。每个Slave只能绑定一个实例,同一实例从创建事务到读取FINISHED并交接完应答期间一直忙,所有站点的新命令互斥。全局未启用类型继续交给后续处理器或44兜底。
|
||||
|
||||
设定值由request.value交付应用;选择和执行比较原始值字节及屏蔽S/E后的QU/QL,不比较CP56。带时标激活默认按10秒窗口检查,应用通过Set_Time_Base提供UTC纪元毫秒及对应Net单调毫秒;过期默认静默丢弃,超前、无基准或无效时间回否定。max=0只关闭时差检查,仍拒绝IV及UTC换算失败。校时成功后应在动作回调外更新基准;STOP/断线保留基准,失去可信时间时Clear_Time_Base。
|
||||
|
||||
Handle_Event校验并生成SELECT/EXECUTE事件,Accept先消费事件再至多调用一次本次传入的动作;不保存回调。EXECUTE启动后先Report_Result记录设备结果,再逐帧Submit_Return_Info,全部OK后Complete。确认未交接时仍可报告结果以停止执行期限;返回信息WAIT时由应用保存ASDU重试。执行确认、返回信息与ACT_TERM走Try,模块内应答按全局FIFO提交。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user