Skip to main content

industrial_protocols_kernel/sdk/
mod.rs

1// Copyright (c) 2026 erik <erik@erik.xyz> — https://erik.xyz
2//! # 协议 SDK — 6 个核心 Trait
3//!
4//! 所有工业协议通过实现这些 trait 接入微内核。
5//!
6//! ## Trait 列表
7//!
8//! | Trait | 用途 | 必须实现 |
9//! |-------|------|---------|
10//! | [`Protocol`] | 协议元数据(名称、版本、分类、变体) | 所有协议 |
11//! | [`ProtocolRead`] | 读取数据(单点、批量、范围) | 支持读取的协议 |
12//! | [`ProtocolWrite`] | 写入数据(单点、批量) | 支持写入的协议 |
13//! | [`ProtocolSubscribe`] | 订阅数据变更通知 | 支持推送的协议 |
14//! | [`ProtocolDiscover`] | 网络扫描发现设备 | 支持发现的协议 |
15//! | [`ProtocolHealth`] | 健康检查 | 建议实现 |
16//! | [`ProtocolDiagnostics`] | 诊断信息获取 | 建议实现 |
17//!
18//! ## 关联类型
19//!
20//! 每个协议的地址和值类型通过关联类型定义,编译期类型安全:
21//!
22//! - Modbus: `Address = u16`, `Value = u16`(寄存器地址和 16 位值)
23//! - OPC UA: `Address = String`, `Value = OPCUAValue`(NodeId 字符串和变体类型)
24//! - BACnet: `Address = String`, `Value = f32`(对象标识符和浮点值)
25
26pub mod types;
27
28use crate::bridge::Transport;
29use crate::connection::Connection;
30use crate::error::Result;
31pub use types::*;
32
33/// 协议基础 trait,所有协议必须实现。
34///
35/// 提供协议的元数据信息:名称、版本、分类、支持的变体。
36pub trait Protocol: Send + Sync {
37    /// 协议名称,如 `"modbus"`、`"opcua"`。用作注册表的键。
38    fn name(&self) -> &'static str;
39    /// 协议版本号。
40    fn version(&self) -> &'static str;
41    /// 协议所属分类。
42    fn category(&self) -> ProtocolCategory;
43    /// 支持的变体列表,如 Modbus 支持 `["tcp", "rtu", "ascii"]`。
44    fn supported_variants(&self) -> &'static [&'static str];
45}
46
47/// 读操作 trait。
48///
49/// 协议按需实现——只读传感器不需要实现 [`ProtocolWrite`]。
50pub trait ProtocolRead: Protocol {
51    /// 协议特有的地址类型。
52    type Address: AddressLike;
53    /// 协议特有的值类型。
54    type Value: ValueLike;
55    /// 从指定地址读取单个值。
56    fn read(&self, conn: &mut dyn Connection, addr: &Self::Address) -> Result<Self::Value>;
57    /// 批量读取多个地址的值。
58    fn read_batch(
59        &self,
60        conn: &mut dyn Connection,
61        addrs: &[Self::Address],
62    ) -> Result<Vec<Self::Value>>;
63    /// 从起始地址连续读取指定数量的值。
64    fn read_range(
65        &self,
66        conn: &mut dyn Connection,
67        start: &Self::Address,
68        count: u16,
69    ) -> Result<Vec<Self::Value>>;
70}
71
72/// 写操作 trait。
73pub trait ProtocolWrite: Protocol {
74    type Address: AddressLike;
75    type Value: ValueLike;
76    /// 向指定地址写入单个值。
77    fn write(
78        &self,
79        conn: &mut dyn Connection,
80        addr: &Self::Address,
81        value: &Self::Value,
82    ) -> Result<()>;
83    /// 批量写入多个地址的值。
84    fn write_batch(
85        &self,
86        conn: &mut dyn Connection,
87        items: &[(Self::Address, Self::Value)],
88    ) -> Result<()>;
89}
90
91/// 订阅操作 trait,用于支持数据推送的协议(如 MQTT、OPC UA)。
92pub trait ProtocolSubscribe: Protocol {
93    /// 订阅标识符类型。
94    type SubscriptionId: Clone + Send + Sync;
95    type Address: AddressLike;
96    /// 订阅指定地址的数据变更。
97    fn subscribe(
98        &self,
99        conn: &mut dyn Connection,
100        addrs: &[Self::Address],
101    ) -> Result<Self::SubscriptionId>;
102    /// 取消订阅。
103    fn unsubscribe(&self, conn: &mut dyn Connection, sub_id: &Self::SubscriptionId) -> Result<()>;
104    /// 轮询获取订阅更新。
105    fn poll(
106        &self,
107        conn: &mut dyn Connection,
108    ) -> Result<Vec<SubscriptionUpdate<Self::SubscriptionId>>>;
109}
110
111/// 设备发现 trait,不要求实现 [`Protocol`](因为发现可能发生在协议实例化之前)。
112pub trait ProtocolDiscover {
113    /// 通过网络发现设备。
114    fn discover(&self, transport: &mut dyn Transport) -> Result<Vec<DiscoveredDevice>>;
115}
116
117/// 健康检查 trait,用于检测设备连接状态和延迟。
118pub trait ProtocolHealth: Protocol {
119    /// 执行健康检查,返回设备状态和延迟信息。
120    fn health(&self, conn: &mut dyn Connection) -> Result<HealthStatus>;
121}
122
123/// 诊断信息 trait,用于获取设备运行统计和错误计数。
124pub trait ProtocolDiagnostics: Protocol {
125    /// 获取设备诊断报告。
126    fn diagnostics(&self, conn: &mut dyn Connection) -> Result<DiagnosticsReport>;
127}