diff --git a/CHANGELOG.md b/CHANGELOG.md index a68b3d6..96312e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - New automatic documentation generation using docfx. +- Additional articles for the documentation. ### Changed diff --git a/docs/articles/getting-started.md b/docs/articles/getting-started.md index 8b3a794..676b032 100644 --- a/docs/articles/getting-started.md +++ b/docs/articles/getting-started.md @@ -1 +1,106 @@ -# Getting Started \ No newline at end of file +# Getting Started + +To begin, you need at least the [Common] package. + +In this package you'll find everything you need to implement you own client as the package contains the protocol implementations (`TCP`, `RTU` and `ASCII`). + +The [`ModbusClientBase`](~/api/AMWD.Protocols.Modbus.Common.Contracts.ModbusClientBase.yml) is the place, where most of the magic happens. +In this base client you have all known (and implemented) methods to request a device. + +The Protocol implementations are the other magic place to be, as there the request will be converted into bits and bytes, before they get transfered. + + +## Using a TCP client + +To use a TCP Modbus client, you need the [Common] package and the [TCP] package installed. + +```cs +using AMWD.Protocols.Modbus.Common; +using AMWD.Protocols.Modbus.Common.Contracts; +using AMWD.Protocols.Modbus.Common.Protocols; +using AMWD.Protocols.Modbus.Tcp; + +namespace ConsoleApp; + +internal class Program +{ + string hostname = "modbus-device.internal"; + int port = 502; + + byte unitId = 5; + ushort startAddress = 19000; + ushort count = 2; + + using var client = new ModbusTcpClient(hostname, port); + await client.ConnectAsync(CancellationToken.None); + + var holdingRegisters = await client.ReadHoldingRegistersAsync(unitId, startAddress, count); + float voltage = holdingRegisters.GetSingle(); + + Console.WriteLine($"The voltage of the device #{unitId} between L1 and N is {voltage:N2}V."); +} +``` + +This will automatically create a TCP client using the TCP protocol. +If you want to change the protocol sent over TCP, you can specify it: + +```cs +// [...] other code + +using var client = new ModbusTcpClient(hostname, port) +{ + Protocol = new RtuProtocol() +}; + +// [...] other code +``` + + +## Using a Serial client + +To use a Serial Modbus client, you need the [Common] package and the [Serial] package installed. + +```cs +using AMWD.Protocols.Modbus.Common; +using AMWD.Protocols.Modbus.Common.Contracts; +using AMWD.Protocols.Modbus.Common.Protocols; +using AMWD.Protocols.Modbus.Serial; + +namespace ConsoleApp; + +internal class Program +{ + string serialPort = "/dev/ttyUSB0"; + + byte unitId = 5; + ushort startAddress = 19000; + ushort count = 2; + + using var client = new ModbusSerialClient(serialPort); + await client.ConnectAsync(CancellationToken.None); + + var holdingRegisters = await client.ReadHoldingRegistersAsync(unitId, startAddress, count); + float voltage = holdingRegisters.GetSingle(); + + Console.WriteLine($"The voltage of the device #{unitId} between L1 and N is {voltage:N2}V."); +} +``` + +This will automatically create a Serial client using the RTU protocol. +If you want to change the protocol sent over serial line, you can specify it: + +```cs +// [...] other code + +using var client = new ModbusSerialClient(serialPort) +{ + Protocol = new AsciiProtocol() +}; + +// [...] other code +``` + + +[Common]: https://www.nuget.org/packages/AMWD.Protocols.Modbus.Common +[Serial]: https://www.nuget.org/packages/AMWD.Protocols.Modbus.Serial +[TCP]: https://www.nuget.org/packages/AMWD.Protocols.Modbus.Tcp \ No newline at end of file diff --git a/docs/articles/introduction.md b/docs/articles/introduction.md index f6ecaa6..7998ab1 100644 --- a/docs/articles/introduction.md +++ b/docs/articles/introduction.md @@ -1 +1,20 @@ -# Introduction \ No newline at end of file +# Introduction + +During my training, I came into contact with the Modbus protocol. +The implementation I developed at that time was very cumbersome and rigid. +There were huge inheritance hierarchies and the design was very confusing. + +In 2018, I wanted to do better and completely redesigned the library. +After changing companies, this library could be integrated and tested under real-world conditions. +This quickly led to new challenges and some specific requirements were implemented. +This was the first time that both TCP and the RTU protocol were fully implemented. + +However, the structure of the library also revealed problems and was too rigid for the requirements. +Therefore, in 2024, there was a new development from scratch, which now exists and has already been tested by some eager people – THANK YOU SO MUCH! + +The focus is, of course, on the development of the protocol and the clients. However, a server implementation (TCP/RTU) is also available. + +For detailed changes of the current development, see the [CHANGELOG]. + + +[CHANGELOG]: https://github.com/AM-WD/AMWD.Protocols.Modbus/blob/main/CHANGELOG.md \ No newline at end of file diff --git a/docs/articles/toc.yml b/docs/articles/toc.yml index d3663b9..3f8fd08 100644 --- a/docs/articles/toc.yml +++ b/docs/articles/toc.yml @@ -1,4 +1,8 @@ - name: Introduction href: introduction.md - name: Getting Started - href: getting-started.md \ No newline at end of file + href: getting-started.md +- name: GitHub + href: https://github.com/AM-WD/AMWD.Protocols.Modbus +- name: NuGet + href: https://www.nuget.org/packages?q=AMWD.Protocols.Modbus \ No newline at end of file