Skip to content

doc(Modbu): add ModbusFactory documentation #6722

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 7, 2025
Merged

doc(Modbu): add ModbusFactory documentation #6722

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e2c0f49
chore: 更新依赖
ArgoZhang Sep 7, 2025
22568c3
doc: 更新文档
ArgoZhang Sep 7, 2025
1f4548e
doc: 更新文档
ArgoZhang Sep 7, 2025
31d017e
doc: 更新说明文档
ArgoZhang Sep 7, 2025
04242fb
chore: 更新路由配置文件
ArgoZhang Sep 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/BootstrapBlazor.Server/BootstrapBlazor.Server.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,10 +81,10 @@
<PackageReference Include="BootstrapBlazor.VideoPlayer" Version="9.0.3" />
<PackageReference Include="BootstrapBlazor.WinBox" Version="9.0.7" />
<PackageReference Include="Longbow.Logging" Version="9.0.1" />
<PackageReference Include="Longbow.Modbus" Version="9.0.0" />
<PackageReference Include="Longbow.Modbus" Version="9.0.2" />
<PackageReference Include="Longbow.Socket" Version="9.0.3" />
<PackageReference Include="Longbow.Tasks" Version="9.0.2" />
<PackageReference Include="Longbow.TcpSocket" Version="9.0.3" />
<PackageReference Include="Longbow.TcpSocket" Version="9.0.4" />
</ItemGroup>

<ItemGroup>
Expand Down
124 changes: 25 additions & 99 deletions src/BootstrapBlazor.Server/Components/Samples/Modbus/ModbusFactories.razor
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,119 +17,45 @@
[NotNull]
private IModbusFactory? ModbusFactory { get; set; }</Pre>

<Pre>var client = ModbusFactory.GetOrCreateTcpMaster("bb", options =>
{
options.LocalEndPoint = new IPEndPoint(IPAddress.Loopback, 0);
});</Pre>
<p class="code-label">3. 通过工厂获得相对应协议 <code>IModbusClient</code> 实例</p>

<p class="code-label">3. 使用方法</p>
<p>Modbus 可以通过不同的物理介质传输，主要有以下几种方式：</p>

<ul class="ul-demo">
<li>通过 <code>ITcpSocketClient</code> 实例方法 <code>ConnectAsync</code> 连接远端节点</li>
<li>通过 <code>ITcpSocketClient</code> 实例方法 <code>SendAsync</code> 发送协议数据</li>
<li>通过 <code>ITcpSocketClient</code> 实例方法 <code>Close</code> 关闭连接</li>
<li>通过 <code>ITcpSocketClient</code> 实例方法 <code>SetDataHandler</code> 方法设置数据处理器</li>
<li>通过 <code>ITcpSocketClient</code> 实例属性 <code>ReceivedCallBack</code> 方法设置接收数据处理器（注意：此回调未做任何数据处理为原始数据）</li>
<li><code>Modbus RTU (Remote Terminal Unit)</code>: 采用二进制编码，使用紧凑的二进制表示数据，效率高，是最常用的串行通信模式。通常基于 <code>RS-485</code>（支持多设备）或 <code>RS-232</code>（点对点）物理层，CRC 校验确保数据完整性。</li>
<li><code>Modbus TCP/IP</code>: 运行于以太网上，使用 <code>TCP/IP</code> 协议，默认端口 <code>502</code>。它在 Modbus RTU 协议基础上添加了 MBAP 报文头，并由于TCP本身是可靠连接的服务，因此去掉了 CRC 校验码。</li>
</ul>

<p class="code-label">4. 数据处理器</p>

<p>在我们实际应用中，建立套接字连接后就会进行数据通信，数据通信不会是杂乱无章的随机数据，在应用中都是有双方遵守的规约简称通讯协议，在通讯协议的约束下，发送方与接收方均根据通讯协议进行编码或解码工作，将数据有条不紊的传输</p>

<p>数据处理器设计初衷就是为了契合通讯协议大大简化我们开发逻辑，我们已通讯协议每次通讯电文均为 <b>4</b> 位定长举例说明，在实际的通讯过程中，我们接收到的通讯数据存在粘包或者分包的现象</p>
<p><code>IModbusFactory</code> 实例方法</p>

<ul class="ul-demo">
<li><b>粘包</b>：比如我们期望收到 <b>1234</b> 四个字符，实际上我们接收到的是 <b>123412</b> 多出来的 <b>12</b> 其实是下一个数据包的内容，我们需要截取前 4 位数据作为一个数据包才能正确处理数据，这种相邻两个通讯数据包的粘连称为<b>粘包</b></li>
<li><b>分包</b>：比如我们期望收到 <b>1234</b> 四个字符，实际上我们可能分两次接收到，分别是 <b>12</b> 和 <b>34</b>，我们需要将两个数据包拼接成一个才能正确的处理数据。这种情况称为<b>分包</b></li>
<li>通过 <code>GetOrCreateTcpMaster</code> 方法得到 <code>IModbusTcpClient</code> 实例</li>
<li>通过 <code>GetOrCreateUdpMaster</code> 方法得到 <code>IModbusTcpClient</code> 实例</li>
Copy link

Copilot AI Sep 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The GetOrCreateUdpMaster method should return IModbusUdpClient, not IModbusTcpClient. UDP and TCP are different protocols and should have distinct client types.

Suggested change
<li>通过 <code>GetOrCreateUdpMaster</code> 方法得到 <code>IModbusTcpClient</code> 实例</li>
<li>通过 <code>GetOrCreateUdpMaster</code> 方法得到 <code>IModbusUdpClient</code> 实例</li>

Copilot uses AI. Check for mistakes.
<li>通过 <code>GetOrCreateRtuMaster</code> 方法得到 <code>IModbusRtuClient</code> 实例</li>
<li>通过 <code>GetOrCreateRtuOverTcpMaster</code> 方法得到 <code>IModbusTcpClient</code> 实例</li>
<li>通过 <code>GetOrCreateRtuOverUdpMaster</code> 方法得到 <code>IModbusTcpClient</code> 实例</li>
Copy link

Copilot AI Sep 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The GetOrCreateRtuOverUdpMaster method should return IModbusUdpClient, not IModbusTcpClient. This method uses UDP protocol and should have the corresponding client type.

Suggested change
<li>通过 <code>GetOrCreateRtuOverUdpMaster</code> 方法得到 <code>IModbusTcpClient</code> 实例</li>
<li>通过 <code>GetOrCreateRtuOverUdpMaster</code> 方法得到 <code>IModbusUdpClient</code> 实例</li>

Copilot uses AI. Check for mistakes.
Comment on lines +34 to +36
Copy link

Copilot AI Sep 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent indentation using tabs instead of spaces. The first line uses spaces while lines 35-36 use tabs. This should be consistent throughout the file.

Copilot uses AI. Check for mistakes.
</ul>

<p>我们内置了一些常用的数据处理类 <code>IDataPackageHandler</code> 接口为数据包处理接口，虚类 <code>DataPackageHandlerBase</code> 作为数据处理器基类已经内置了 <b>粘包</b> <b>分包</b> 的逻辑，继承此类后专注自己处理的业务即可</p>

<p>使用方法如下：</p>
<p>调用其对应的 <code>Remove</code> 方法即可从缓存中移除指定名称的 <code>IModbusClient</code> 实例。如</p>

<Pre>[Inject]
[NotNull]
private ITcpSocketFactory? TcpSocketFactory { get; set; }
<Pre>ModbusFactory.RemoveTcpMaster("test");</Pre>

private async Task CreateClient()
{
// 创建 ITcpSocketClient 实例
var client = TcpSocketFactory.GetOrCreate("localhost", 0);
<p class="code-label">4. 数据操作</p>

// 设置数据适配器 使用 FixLengthDataPackageHandler 数据处理器处理数据定长 4 的数据
var adapter = new DataPackageAdapter
{
DataPackageHandler = new FixLengthDataPackageHandler(4)
};
<p><code>Modbus</code> 数据类型共四种</p>

// 如果 client 不销毁切记使用 RemoveDataPackageAdapter 移除回调委托防止内存泄露
client.AddDataPackageAdapter(adapter, buffer =>
{
// buffer 即是接收到的数据
return ValueTask.CompletedTask;
});

// 连接远端节点 连接成功后自动开始接收数据
var connected = await client.ConnectAsync("192.168.10.100", 6688);
}
</Pre>
<ul class="ul-demo">
<li>线圈 (Coils) 可读可写 数字量输出，如开关状态</li>
<li>离散输入 (Discrete Inputs) 只读 数字量输出，如开关状态</li>
<li>输入寄存器 (Input Registers) 只读 模拟量输入，如温度、压力传感器数据</li>
<li>保持寄存器 (Holding Registers) 可读可写 模拟量输出，如设定值、控制参数</li>
</ul>

<p>内置数据处理器</p>
<p>对应 <code>IModbusClient</code> 实例方法如下</p>

<ul class="ul-demo">
<li><code>FixLengthDataPackageHandler</code> <b>固定长度数据处理器</b> 即每个通讯包都是固定长度</li>
<li><code>DelimiterDataPackageHandler</code> <b>分隔符数据处理器</b> 即通讯包以特定一个或一组字节分割</li>
<li>线圈 (Coils) <code>ReadCoilsAsync</code> <code>WriteCoilAsync</code> <code>WriteMultipleCoilsAsync</code></li>
<li>离散输入 (Discrete Inputs) <code>ReadInputsAsync</code></li>
<li>输入寄存器 (Input Registers) <code>ReadInputRegistersAsync</code></li>
<li>保持寄存器 (Holding Registers) <code>ReadHoldingRegistersAsync</code> <code>WriteRegisterAsync</code> <code>WriteMultipleRegistersAsync</code></li>
</ul>

<p class="code-label">5. 数据适配器</p>

<p>在我们实际应用中，接收到数据包后（已经过数据处理器）大多情况下是需要将电文转化为应用中的具体数据类型 <code>Class</code> 或 <code>Struct</code>。将原始数据包转化为类或者结构体的过程由我们的数据适配器来实现</p>

<p>数据适配器设计思路如下</p>

<ol class="ul-demo">
<li>使用 <code>DataTypeConverterAttribute</code> 标签约定通讯数据使用那个转换类型进行转换 指定类型需继承 <code>IDataConverter</code>
接口
</li>
<li>使用 <code>DataPropertyConverterAttribute</code> 标签约定如何转换数据类型 （Property） 属性值</li>
</ol>

<Pre>[DataTypeConverter(Type = typeof(DataConverter&lt;MockEntity&gt;))]
class MockEntity
{
[DataPropertyConverter(Type = typeof(byte[]), Offset = 0, Length = 5)]
public byte[]? Header { get; set; }

[DataPropertyConverter(Type = typeof(byte[]), Offset = 5, Length = 2)]
public byte[]? Body { get; set; }

[DataPropertyConverter(Type = typeof(Foo), Offset = 7, Length = 1, ConverterType = typeof(FooConverter), ConverterParameters = ["test"])]
public string? Value1 { get; set; }
}</Pre>

<Pre>class FooConverter(string name) : IDataPropertyConverter
{
public object? Convert(ReadOnlyMemory&lt;byte&gt; data)
{
return new Foo() { Id = data.Span[0], Name = name };
}
}</Pre>

<p class="code-label">针对第三方程序集的数据类型解决方案如下：</p>
<p>使用 <code></code></p>

<Pre>builder.Services.ConfigureDataConverters(options =>
{
options.AddTypeConverter&lt;MockEntity&gt;();
options.AddPropertyConverter&lt;MockEntity&gt;(entity =&gt; entity.Header, new DataPropertyConverterAttribute()
{
Offset = 0,
Length = 5
});
options.AddPropertyConverter&lt;MockEntity&gt;(entity =&gt; entity.Body, new DataPropertyConverterAttribute()
{
Offset = 5,
Length = 2
});
});
</Pre>
2 changes: 1 addition & 1 deletion src/BootstrapBlazor.Server/Components/Samples/Modbus/ModbusFactories.razor.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,5 @@ namespace BootstrapBlazor.Server.Components.Samples.Modbus;
/// </summary>
public partial class ModbusFactories
{

}
3 changes: 2 additions & 1 deletion src/BootstrapBlazor.Server/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,8 @@
"toolbar": "Toolbars",
"opc-da": "OpcDa",
"navbar": "Navbars",
"task-board": "TaskBoard"
"task-board": "TaskBoard",
"modbus-factory": "Modbus\\ModbusFactories"
},
"video": {
"table": "BV1ap4y1x7Qn?p=1",
Expand Down
Loading