380 lines
17 KiB
Markdown
380 lines
17 KiB
Markdown
# libmms_s 模块分析
|
||
|
||
**日期**：2026-06-10
|
||
|
||
---
|
||
|
||
## 1. 模块概览
|
||
|
||
`libmms_s` 是 IEC 61850 MMS 服务端的封装库，基于 `libiec61850` v1.5.3 的服务端 API，提供 ICD 文件解析、动态数据模型创建、IedServer 生命周期管理，以及控制/定值/参数/文件等子系统的初始化。
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
src/protocol/libmms_s/
|
||
├── inc/
|
||
│ ├── mms_s.h # 核心头文件：日志宏、全局访问接口、类型转换
|
||
│ ├── mms_s_icd.h # ICD 解析数据结构（完整 SCL 类型体系）
|
||
│ ├── mms_s_model.h # 动态模型创建接口
|
||
│ ├── mms_s_value.h # DA 初始值设定
|
||
│ ├── mms_s_control.h # 控制功能接口
|
||
│ ├── mms_s_param.h # 定值组参数接口
|
||
│ ├── mms_s_setting.h # 定值（SP）接口
|
||
│ └── mms_s_file.h # 文件传输服务接口
|
||
└── src/
|
||
├── mms_s.cpp # 核心：init/run/task/类型转换
|
||
├── mms_s_icd.cpp # ICD XML 解析器（tinyxml2）
|
||
├── mms_s_model.cpp # 动态 IedModel 创建
|
||
├── mms_s_control.cpp # 控制（SBO/直控）处理
|
||
├── mms_s_param.cpp # 定值组（SG/SE）管理
|
||
├── mms_s_setting.cpp # 定值（SP）管理
|
||
├── mms_s_value.cpp # 数据属性初始值设定
|
||
└── mms_s_file.cpp # MMS 文件传输服务
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 核心架构
|
||
|
||
### 2.1 单例全局状态
|
||
|
||
```cpp
|
||
LOCAL IedServer gp_iedServer = NULL; // 全局 IED 服务器（单例）
|
||
LOCAL stru_icd *gp_icd = NULL; // 全局 ICD 数据（单例）
|
||
LOCAL int g_running = 0; // 线程运行标志
|
||
LOCAL bool g_dbg_switch = false; // 调试输出开关
|
||
```
|
||
|
||
整个库采用单例模式，全局只有一个 IedServer 和一个 ICD 数据结构。
|
||
|
||
### 2.2 模块分层
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ myMms_s.h │ ← 公共 API + 类型定义
|
||
├──────────────────────────────────────────┤
|
||
│ mms_s.cpp (init / run / 类型转换) │ ← 库入口
|
||
├──────────────────────────────────────────┤
|
||
│ mms_s_icd.cpp │ mms_s_model.cpp │ ← ICD 解析 → 模型构建
|
||
├──────────────────────────────────────────┤
|
||
│ mms_s_value.cpp (DA 初始值) │ ← 模型回调
|
||
├──────────────────────────────────────────┤
|
||
│ mms_s_control.cpp │ mms_s_param.cpp │ ← 功能模块
|
||
│ mms_s_setting.cpp │ mms_s_file.cpp │
|
||
├──────────────────────────────────────────┤
|
||
│ libiec61850 (libiec61850.a) │ ← 底层协议栈
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 完整初始化流程
|
||
|
||
`mms_s_init()` 的执行顺序（[mms_s.cpp:261](src/protocol/libmms_s/src/mms_s.cpp#L261)）：
|
||
|
||
```
|
||
1. icd_parse(icd_path) → 解析 ICD 文件 → stru_icd
|
||
2. model_init(*gp_icd) → 创建动态数据模型 → IedModel
|
||
3. IedServerConfig_create() → 创建服务器配置
|
||
4. IedServer_createWithConfig() → 创建 IedServer 实例
|
||
5. control_init() → 安装控制回调
|
||
6. param_init() → 安装定值组回调
|
||
7. file_init() → 安装文件服务
|
||
8. IedServer_setRCBEventHandler() → 注册 RCB 事件监听
|
||
9. IedServer_start(port) → 启动服务器（默认端口 102）
|
||
10. setting_init() → 初始化定值
|
||
11. IedServer_isRunning() → 检查运行状态
|
||
12. Thread_create(mms_s_run_task) → 启动后台线程
|
||
```
|
||
|
||
---
|
||
|
||
## 4. ICD 解析子系统
|
||
|
||
### 4.1 数据结构体系（[mms_s_icd.h](src/protocol/libmms_s/inc/mms_s_icd.h)）
|
||
|
||
对应 IEC 61850-6 SCL 标准的完整类型体系：
|
||
|
||
**数据类型模板层（DataTypeTemplates）**：
|
||
| 结构 | 说明 | 关键字段 |
|
||
|------|------|---------|
|
||
| `stru_LNodeType` | 逻辑节点类型 | lnClass, vec_do, map_do(key:name) |
|
||
| `stru_DO` | 数据对象定义 | desc, type（→ DOType id） |
|
||
| `stru_DOType` | 数据对象类型 | cdc, vec_da, map_da, vec_sdo, map_sdo |
|
||
| `stru_DA` | 数据属性定义 | bType, type, dchg, qchg, fc, text |
|
||
| `stru_DAType` | 数据属性类型 | vec_bda, map_bda(key:name) |
|
||
| `stru_BDA` | 基本数据属性 | bType, type, fc, dchg, qchg |
|
||
| `stru_EnumType` | 枚举类型 | vec_ord, map_enumVal(key:ord) |
|
||
|
||
**实例化模型层（IED/Server）**：
|
||
| 结构 | 说明 |
|
||
|------|------|
|
||
| `stru_ied` | IED 顶层模型（含 model, name, 各逻辑设备） |
|
||
| `stru_LDevice` | 逻辑设备（含 Ldevice 指针, sgcb, ln0, vec_ln） |
|
||
| `stru_LN0` | LLN0（含 数据集, 报告控制, 定值控制） |
|
||
| `stru_LN` | 普通逻辑节点 |
|
||
| `stru_DOI` | 数据对象实例（含 SDI, DAI） |
|
||
| `stru_SDI` | 子数据对象实例（可递归嵌套） |
|
||
| `stru_DAI` | 数据属性实例（含 sAddr, val） |
|
||
| `stru_DataSet` | 数据集（含 FCDA 列表） |
|
||
| `stru_FCDA` | 功能约束数据属性（ldInst/lnClass/doName/daName/fc） |
|
||
| `stru_ReportControl` | 报告控制块（含 TrgOps, OptFields, RptEnabled_max） |
|
||
| `stru_SettingControl` | 定值控制块（actSG, numOfSGs） |
|
||
|
||
**运行时辅助结构**：
|
||
| 结构 | 说明 |
|
||
|------|------|
|
||
| `stru_all_DO` | DO 运行时树（含 libiec61850 DataObject 指针, map_all_sdo, map_all_da） |
|
||
| `stru_all_DA` | DA 运行时树（含 libiec61850 DataAttribute 指针, map_all_da 子节点） |
|
||
| `stru_contorl_DO` | 控制 DO 定位信息（ldevice_inst/ln_class/ln_inst/do_name/p_all_do） |
|
||
| `stru_saddr_point` | sAddr 到模型节点的映射（node, da_t, da_q） |
|
||
| `stru_setting_info` | 定值信息（DA 指针, 类型, 值） |
|
||
|
||
### 4.2 解析流程（[mms_s_icd.cpp](src/protocol/libmms_s/src/mms_s_icd.cpp)）
|
||
|
||
```
|
||
icd_parse(icd_file)
|
||
├── XMLDocument.LoadFile()
|
||
├── parse_ied() → 解析 IED 实例
|
||
│ ├── parse_LDevice() → 每个逻辑设备
|
||
│ │ ├── parse_LN0() → LLN0（数据集/报告控制/定值控制/DOI）
|
||
│ │ │ ├── parse_DataSet()
|
||
│ │ │ ├── parse_ReportControl()
|
||
│ │ │ │ ├── parse_ReportControl_TrgOps()
|
||
│ │ │ │ ├── parse_ReportControl_OptFields()
|
||
│ │ │ │ └── parse_ReportControl_RptEnable() → RptEnabled_max
|
||
│ │ │ ├── parse_DOI() → parse_SDI() / parse_DAI()
|
||
│ │ │ └── parse_SettingControl()
|
||
│ │ └── parse_LN() → 普通 LN + DOI
|
||
│ └── (沿 SCL > IED > AccessPoint > Server > LDevice 路径)
|
||
├── parse_dataTypeTemplates() → 解析模板
|
||
│ ├── parse_LNodeType()
|
||
│ ├── parse_DOType()
|
||
│ ├── parse_DAType()
|
||
│ ├── parse_EnumType()
|
||
│ └── parse_BDA_fc() ×2 → 传播 FC/dchg/qchg 到嵌套 BDA
|
||
└── check_ied_dataTypeTemplates() → 一致性校验
|
||
└── 递归验证每个实例节点都能在模板中找到定义
|
||
```
|
||
|
||
### 4.3 BDA 属性传播机制
|
||
|
||
关键设计：当 DA 的 type 指向 DAType（Struct 类型）时，`parse_BDA_fc()` 将父级 DA 的 fc/dchg/qchg 属性向下传播到 DAType 中所有 BDA，确保嵌套 Struct 的底层 BDA 也能继承正确的 FC 约束。
|
||
|
||
---
|
||
|
||
## 5. 动态模型创建子系统
|
||
|
||
### 5.1 model_init() 主流程（[mms_s_model.cpp:1319](src/protocol/libmms_s/src/mms_s_model.cpp#L1319)）
|
||
|
||
```
|
||
1. IedModel_create(name)
|
||
2. model_ldevice_init()
|
||
├── LogicalDevice_create()
|
||
├── model_ln0_init()
|
||
│ ├── LogicalNode_create("LLN0")
|
||
│ ├── model_dataobject_init() → 创建所有 DO/SDO/DA
|
||
│ ├── model_DataSet_init() → 创建数据集+条目
|
||
│ ├── model_ReportControlBlock_init() → 创建 RCB
|
||
│ └── SettingGroupControlBlock_create()
|
||
└── model_LNodes_init() → 创建普通 LN
|
||
3. model_sync_ied_default_values() → 同步 ICD DAI 中的 sAddr/val
|
||
4. model_search_control_DataObjects() → 搜索 ctlModel→vec_control_do
|
||
5. icd.ied.model->initializer = mms_s_values_init → 注册回调
|
||
```
|
||
|
||
### 5.2 类型映射表
|
||
|
||
**bType → DataAttributeType**（[mms_s_model.cpp:43](src/protocol/libmms_s/src/mms_s_model.cpp#L43)）：
|
||
`BOOLEAN → IEC61850_BOOLEAN`, `INT32 → IEC61850_INT32`, `FLOAT32 → IEC61850_FLOAT32`, `Struct → IEC61850_CONSTRUCTED`, `Quality → IEC61850_QUALITY`, `Timestamp → IEC61850_TIMESTAMP`, `Dbpos → IEC61850_GENERIC_BITSTRING` 等，共约 25 种映射。
|
||
|
||
**FC → FunctionalConstraint**（[mms_s_model.cpp:86](src/protocol/libmms_s/src/mms_s_model.cpp#L86)）：
|
||
`ST/MX/SP/SV/CF/DC/SG/SE/SR/OR/BL/EX/CO/US/MS/RP/BR/LG/GO` → 对应 IEC61850 枚举。
|
||
|
||
### 5.3 SG/SE 双数据属性设计
|
||
|
||
当 DA 的 FC=SG 时，除了创建 FC=SG 的 DA 外，还会额外创建一个 FC=SE 的同名 DA（key 加 `_SE` 后缀）。反之 FC=SE 同理。sAddr 映射时也会对应添加 `_SG` / `_SE` 后缀区分。
|
||
|
||
这是一个独创设计——在同一个 DO 下同时暴露 SG（当前激活值）和 SE（编辑缓冲区值），使得外部系统可以同时访问定值的"当前生效值"和"正在编辑中的值"。
|
||
|
||
### 5.4 sAddr 映射机制
|
||
|
||
ICD 文件中 DAI 元素的 `sAddr` 属性定义了该数据点与外部数据源的绑定关系。`model_sync_ied_default_values()` 将 sAddr 写入模型节点的 `sAddr` 字段，同时建立：
|
||
- `icd.ied.vec_saddr` — sAddr 列表
|
||
- `icd.ied.map_saddr_point` — sAddr → ModelNode 映射
|
||
|
||
对于 FC=SG 的点，sAddr 后缀 `_SG`；FC=SE 的点后缀 `_SE`。
|
||
|
||
---
|
||
|
||
## 6. 控制子系统（[mms_s_control.cpp](src/protocol/libmms_s/src/mms_s_control.cpp)）
|
||
|
||
### 6.1 双回调模式
|
||
|
||
| 回调 | 阶段 | 职能 |
|
||
|------|------|------|
|
||
| `check_handler()` | Select / Interlock | 权限校验，匹配合法 DO 则返回 CONTROL_ACCEPTED |
|
||
| `control_handler()` | Operate | 执行控制命令，更新 t（时间戳）+ stVal，触发外部回调 |
|
||
|
||
### 6.2 控制执行流程
|
||
|
||
```
|
||
客户端 → Select Request → check_handler() → CONTROL_ACCEPTED
|
||
客户端 → Operate Request → check_handler() (interlock check) → control_handler()
|
||
├── IedServer_updateUTCTimeAttributeValue(t)
|
||
├── 匹配 sAddr → cb_control() → 通知应用层
|
||
└── 根据 stVal 类型:
|
||
├── BOOLEAN → IedServer_updateAttributeValue()
|
||
└── Dbpos → IedServer_updateDbposValue()
|
||
```
|
||
|
||
### 6.3 控制 DO 发现
|
||
|
||
`model_search_control_DataObjects()` 遍历模型树，找到所有包含 `ctlModel` DA 的 DO，存入 `icd.ied.vec_control_do`。`control_init()` 遍历该列表，为每个安装 `control_handler` 和 `check_handler`。
|
||
|
||
---
|
||
|
||
## 7. 定值组子系统（[mms_s_param.cpp](src/protocol/libmms_s/src/mms_s_param.cpp)）
|
||
|
||
### 7.1 SG vs SE
|
||
|
||
| FC | 含义 | mmsValue 加载时机 |
|
||
|----|------|------------------|
|
||
| SG | Setting Group — 当前激活定值区的实际值 | 激活定值组切换时加载 |
|
||
| SE | Setting Editable — 编辑缓冲区值 | 编辑定值组切换时加载 |
|
||
|
||
### 7.2 回调链
|
||
|
||
```
|
||
激活定值组切换 → param_active_sg_changed_handler() → param_load_active_sg_values()
|
||
编辑定值组切换 → param_edit_sg_changed_handler() → param_load_edit_sg_values()
|
||
编辑确认 → edit_sg_confirmation_handler() → 回读 SE 值 → cb_param()
|
||
```
|
||
|
||
### 7.3 值的加载与校验
|
||
|
||
- 加载：根据 sAddr+"_SG"/"_SE" 在 `map_saddr_point` 中查找节点，按 MMS 类型分发更新函数
|
||
- 回读：`edit_sg_confirmation_handler()` 读取 SE DA 当前值，做 min/max/step 校验，通过后触发外部回调 `g_param_cb`
|
||
- 类型分发表：`g_param_update_funcs[]`（写）和 `g_param_get_funcs[]`（读），覆盖 BOOLEAN/INT/UINT/FLOAT/STRING
|
||
|
||
---
|
||
|
||
## 8. 定值子系统（[mms_s_setting.cpp](src/protocol/libmms_s/src/mms_s_setting.cpp)）
|
||
|
||
### 8.1 与参数的差异
|
||
|
||
定值（FC=SP）不参与定值组切换，是单一设置值。
|
||
|
||
### 8.2 写保护机制
|
||
|
||
1. 全局访问策略：`IedServer_setWriteAccessPolicy(IEC61850_FC_SP, ACCESS_POLICY_DENY)`
|
||
2. 精确放行：通过 `IedServer_handleWriteAccess()` 为已注册 sAddr 安装 `writeAccessHandler`
|
||
3. `writeAccessHandler` 做值校验（范围+步长），通过后触发外部回调 `cb_setting`
|
||
|
||
### 8.3 校验流程
|
||
|
||
```
|
||
客户端写 SP 值 → writeAccessHandler()
|
||
├── 匹配 sAddr
|
||
├── 类型分发 (setting_get_BOOLEAN/INT/UINT/FLOAT/STRING)
|
||
│ └── setting_min_max_step_get() → 读取同级 minVal/maxVal/stepSize
|
||
│ └── 范围校验 + 步长校验
|
||
├── cb_setting() → 通知应用层
|
||
└── return DATA_ACCESS_ERROR_SUCCESS → libiec61850 更新 mmsValue
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 数据属性值初始化（[mms_s_value.cpp](src/protocol/libmms_s/src/mms_s_value.cpp)）
|
||
|
||
`mms_s_values_init()` 作为 `IedModel.initializer` 回调，在 IedServer 创建过程中由 libiec61850 自动调用。
|
||
|
||
**初始化类型覆盖**：BOOLEAN, INT8U/32, FLOAT32, VisString*, Unicode*, Timestamp, Dbpos, Enum（特殊：按文本值或序号查找枚举值）。
|
||
|
||
**Dbpos 特殊处理**：`mms_s_da_value_init_Dbpos()` 按 val 值映射到 DBPOS_INTERMEDIATE_STATE(0)/OFF(1)/ON(2)/BAD_STATE(>=3)。
|
||
|
||
### 9.1 值更新路径
|
||
|
||
`mms_s_value_update()` 是预留的值更新函数，通过 `mms_s_value_update_register()` 注册给外部。当数据中心信号变化时，上层调用此函数更新模型中的 DA 值，同时自动更新父 DO 的 `t`（时间戳）和 `q`（品质）。
|
||
|
||
---
|
||
|
||
## 10. 文件传输服务（[mms_s_file.cpp](src/protocol/libmms_s/src/mms_s_file.cpp)）
|
||
|
||
提供 MMS 文件传输基础能力：
|
||
- 设置文件存储根目录 `IedServer_setFilestoreBasepath()`
|
||
- 访问控制：禁止重命名、禁止删除 `IEDSERVER.BIN`
|
||
- 连接事件日志
|
||
|
||
---
|
||
|
||
## 11. 后台运行线程
|
||
|
||
```cpp
|
||
LOCAL void *mms_s_run_task(void *parameter)
|
||
{
|
||
while(g_running) {
|
||
IedServer_lockDataModel(gp_iedServer);
|
||
IedServer_unlockDataModel(gp_iedServer);
|
||
Thread_sleep(100); // 100ms 周期
|
||
}
|
||
IedServer_stop(gp_iedServer);
|
||
IedServer_destroy(gp_iedServer);
|
||
IedModel_destroy(iedModel);
|
||
}
|
||
```
|
||
|
||
线程负责保护 IedServer 生命周期，通过 lock/unlock 持有模型锁保持服务活跃。收到 SIGINT 后 `g_running=0`，线程退出并销毁资源。
|
||
|
||
---
|
||
|
||
## 12. RCB 事件监听
|
||
|
||
`rcbEventHandler()` 监听客户端的报告控制块操作（[mms_s.cpp:48](src/protocol/libmms_s/src/mms_s.cpp#L48)）：
|
||
|
||
| 事件 | 含义 |
|
||
|------|------|
|
||
| `RCB_EVENT_ENABLE` | 客户端使能报告 |
|
||
| `RCB_EVENT_DISABLE` | 客户端关闭报告 |
|
||
| `RCB_EVENT_RESERVED` | 客户端预订 RCB |
|
||
| `RCB_EVENT_UNRESERVED` | 客户端释放预订 |
|
||
| `RCB_EVENT_GI` | 总召触发 |
|
||
| `RCB_EVENT_SET_PARAMETER` | 客户端设置 RCB 参数（如 TrgOps 等） |
|
||
| `RCB_EVENT_GET_PARAMETER` | 客户端获取 RCB 参数 |
|
||
|
||
**特殊处理**：当客户端设置 `TrgOps` 参数时，服务器强制追加 `dchg`（`rcb->trgOps |= 0x01`），确保数据变化一定能触发报告上送。
|
||
|
||
---
|
||
|
||
## 13. 对外 API 汇总
|
||
|
||
| API | 文件 | 说明 |
|
||
|-----|------|------|
|
||
| `mms_s_init(icd_path, port)` | mms_s.cpp | 完整初始化 MMS 服务器 |
|
||
| `mms_s_dbg_switch(on)` | mms_s.cpp | 调试开关 |
|
||
| `mms_s_get_icd_ptr()` | mms_s.cpp | 获取 ICD 数据 |
|
||
| `mms_s_get_ied_server_ptr()` | mms_s.cpp | 获取 IedServer |
|
||
| `mms_s_control_register(...)` | mms_s_control.cpp | 注册控制点 |
|
||
| `mms_s_setting_register(...)` | mms_s_setting.cpp | 注册定值 |
|
||
| `mms_s_param_register(...)` | mms_s_param.cpp | 注册参数（定值组） |
|
||
| `mms_s_file_path_set(path)` | mms_s_file.cpp | 设置文件根路径 |
|
||
| `mms_s_value_update_register(cb)` | mms_s_value.cpp | 注册值更新回调 |
|
||
| `mms_s_get_string_by_mms_type(...)` | mms_s.cpp | MMS 类型→字符串 |
|
||
| `mms_s_get_string_by_type(...)` | mms_s.cpp | 自定义类型→字符串 |
|
||
|
||
---
|
||
|
||
## 14. 已知问题
|
||
|
||
### 14.1 check_handler 未调用 cb_interlock
|
||
|
||
`mms_s_control.h` 中声明了 `mms_s_interlock_cb` 和 `mms_s_set_interlock_cb()`，但 `check_handler()` 中仅检查 ICD 中是否存在对应 DO，`cb_interlock` 未被实际调用。外部注册的联锁检查回调不会生效。
|
||
|
||
### 14.2 param_min_max_step_get 实现不一致
|
||
|
||
`mms_s_param.cpp` 的 `param_min_max_step_get()` 通过遍历 ModelNode 父子关系查找 minVal/maxVal/stepSize（向上找到 DataObject 再遍历 firstChild），而 `mms_s_setting.cpp` 的 `setting_min_max_step_get()` 是通过 parent->firstChild 直接遍历。两者逻辑不同，前者更复杂（向上一级再到 DO），可能是修正后的版本，但后者仍保留了旧逻辑。
|
||
|
||
### 14.3 mms_s_value_update 未使用 g_iec61850s_value_init_cb_map
|
||
|
||
`mms_s_value_update()` 使用 `g_iec61850s_value_update_cb_map`（按 DataAttributeType 索引），但表中大部分类型回调为 NULL，仅 BOOLEAN/INT32/INT32U/FLOAT32/Enum/VisString32/Unicode255/Timestamp 有实际实现。其他类型（如 INT8/INT16/INT64/FLOAT64 等）更新时会被跳过。
|