diff --git a/docs/index.rst b/docs/index.rst index 7baa619115299af171b736bf85ca0c4022239c2a..dee1f4960dc09286724d3c9aa7160b9cb658ec8e 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 0000000000000000000000000000000000000000..290873fdf203b9788537ac5b7eb33103806b505a --- /dev/null +++ b/docs/supported-technologies/modbus.rst @@ -0,0 +1,92 @@ +.. 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 (Supervisory control and data +acquisition) 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. + +.. note:: + + Modbus support in the |main_project_name| exists purely for interoperability + purpose with existing systems. For new products without this requirement we + do not recommend using Modbus. + +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. + diff --git a/meta-oniro-core/recipes-connectivity/modbus/modbus-testing_git.bb b/meta-oniro-core/recipes-connectivity/modbus/modbus-testing_git.bb new file mode 100644 index 0000000000000000000000000000000000000000..f5f1fabae979905fff3acd87e9aa37c1c0c1b862 --- /dev/null +++ b/meta-oniro-core/recipes-connectivity/modbus/modbus-testing_git.bb @@ -0,0 +1,18 @@ +# SPDX-FileCopyrightText: Huawei Inc. +# +# SPDX-License-Identifier: Apache-2.0 + +SUMMARY = "Libmodbus testing examples" +SECTION = "net" +LICENSE = "Apache-2.0" +LIC_FILES_CHKSUM = "file://LICENSE;md5=ef3dabb8f39493f4ea410bebc1d01755 \ + " +DEPENDS = "libmodbus" +SRCREV = "06daf9b6159167fe22c87603e8926ff63df5ce8d" +PV = "0.0+git${SRCPV}" + +SRC_URI = "git://gitlab.eclipse.org/eclipse/oniro-blueprints/energy-gateway/modbus-testing.git;protocol=https;branch=main" + +S = "${WORKDIR}/git" + +inherit meson pkgconfig