From bd2aec56508f0bd56a62d4057cbe918e4e771beb Mon Sep 17 00:00:00 2001
From: Stefan Schmidt <stefan.schmidt@huawei.com>
Date: Mon, 29 Aug 2022 19:48:31 +0200
Subject: [PATCH] docs: modbus: Add Modbus to supported technologies section

Description of the current status of Modbus integration in Oniro. Brief
context on Modbus itself before going into the details how to enable it
in Oniro and using the offered testing tools.

Closes: https://gitlab.eclipse.org/eclipse/oniro-core/docs/-/issues/11

Signed-off-by: Stefan Schmidt <stefan.schmidt@huawei.com>
---
 docs/index.rst                         |  1 +
 docs/supported-technologies/modbus.rst | 86 ++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 docs/supported-technologies/modbus.rst

diff --git a/docs/index.rst b/docs/index.rst
index 7baa6191..dee1f496 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,6 +36,7 @@ Build System Guide
 
    supported-technologies/openthread
    supported-technologies/containers
+   supported-technologies/modbus
 
 .. toctree::
    :caption: Supported Toolchains
diff --git a/docs/supported-technologies/modbus.rst b/docs/supported-technologies/modbus.rst
new file mode 100644
index 00000000..3f4198ad
--- /dev/null
+++ b/docs/supported-technologies/modbus.rst
@@ -0,0 +1,86 @@
+.. SPDX-FileCopyrightText: Huawei Inc.
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. include:: ../definitions.rst
+
+ModBus
+######
+
+`Modbus <https://modbus.org/>` is a communication protocol from the 1970s
+designed to support industrial use cases. Its main modes of operation are Modbus
+RTU (Remote Terminal Unit) and Modbus TCP. The RTU variant is mostly used over
+RS-485 serial ports, while the newer Modbus TCP variant allows for a communication
+over Ethernet for more flexibility.
+
+Besides its core industrial use cases in SCADA systems it also moved closer to
+the consumer when being integrated into homes e.g. in home heating systems and
+PV systems.
+
+|main_project_name| maintains support for Modbus in its Linux and Zephyr
+flavours. On the Linux side the user-space Modbus implementation `libmodbus
+<https://libmodbus.org/>` is used while on Zephyr the native `Modbus subsystem
+<https://docs.zephyrproject.org/latest/services/modbus/index.html>` is used.
+
+RTU and TCP operation modes are supported.
+
+Enabling Modbus in Oniro:
+*************************
+
+Modbus functionality is not enabled by default in the |main_project_name| and
+there is currently no Blueprint demonstrating its use cases. The basic integration
+is working none the less and Modbus can be enabled in the Linux images by adding
+libmodbus to the image you are building. This can be done by adding the
+following line to your `conf/local.conf` file:
+
+.. code-block::
+
+    IMAGE_INSTALL:append = " libmodbus"
+
+On Zephyr you would need to enable the `CONFIG_MODBUS` options for your modes of
+operations. The Zephyr upstream project does offer `samples for RTU as well as
+TCP operations modes in different roles
+<https://github.com/zephyrproject-rtos/zephyr/tree/main/samples/subsys/modbus>`
+
+Modbus-testing:
+***************
+
+The `libmodbus` library does not come with any examples on how to use it by
+default. To fill this gap and allow integrators and developers to have a
+head-start when developing an application using `libmodbus` we developed a small
+set of examples to demonstrate the usage. These examples can be found at our
+`modbus-testing repo <https://gitlab.eclipse.org/stefanschmidt/modbus-testing>`
+and included in the image by the following addition to your `conf/local.conf` file:
+
+.. code-block::
+
+    IMAGE_INSTALL:append = " libmodbus modbus-testing"
+
+To test Modbus RTU communication over an existing RS-485 serial port (e.g.
+/dev/ttyUSB0) under Linux you can run a server as follows:
+
+.. code-block:: console
+
+    $ modbus-server /dev/ttyUSB0
+
+To execute the client side instead run the following command:
+
+.. code-block:: console
+
+    $ modbus-client /dev/ttyUSB0
+
+To run the same example for Modbus TCP instead of RTU adapt the parameters as
+shown below:
+
+.. code-block:: console
+
+    $ modbus-server -tcp
+
+.. code-block:: console
+
+    $ modbus-client -tcp SERVER_IP_ADDRESS_HERE
+
+Keep in mind that these examples have hard-coded values for many parts (e.g.
+device id, register values, etc) as they are only suited for demonstration
+purpose and as a head-start for your own development.
+
-- 
GitLab