1.. zephyr:code-sample:: modbus-rtu-server
2   :name: Modbus RTU server
3   :relevant-api: modbus
4
5   Implement a Modbus RTU server exposing Modbus commands to control LEDs.
6
7Overview
8********
9
10This is a simple application demonstrating a Modbus RTU server implementation
11in Zephyr RTOS.
12
13Requirements
14************
15
16This sample has been tested with the nRF52840-DK and FRDM-K64F boards,
17but it should work with any board that has a free UART interface or USB
18device controller. Additionally the board should have three LEDs.
19
20RTU server example is running on an evaluation board. Client is running
21on a PC or laptop.
22
23The description of this sample uses `PyModbus`_ (Pymodbus REPL).
24The user can of course try out other client implementations with this sample.
25
26Using RS-485 transceiver
27========================
28
29It is the default configuration of this sample.
30In addition to the evaluation board, an USB to RS-485 bus adapter and
31a RS-485 shield are required. The shield converts UART TX, RX signals to RS-485.
32An Arduino header compatible shield like `joy-it RS-485 shield for Arduino`_
33can be used. This example uses DE signal, which is controlled by pin D9
34on the JOY-IT shield. For other shields, ``de-gpios`` property must be adapted
35or removed in the application overlay file
36:zephyr_file:`samples/subsys/modbus/rtu_server/app.overlay`
37
38The USB to RS-485 adapter connects to the USB port of a computer.
39The two A+, B- lines should be connected to the RS-485 shield.
40
41Using CDC ACM UART
42==================
43
44Only an evaluation board with supported USB device controller is required.
45USB device port should be connected to the USB port of a computer.
46Although it is only a point to point connection and does not represent a bus,
47it can, apart from testing the server implementation, also be used practically
48for example to control relays or to read ADC values via USB connection without
49implementing custom USB class or driver.
50
51Building and Running
52********************
53
54This sample can be found under
55:zephyr_file:`samples/subsys/modbus/rtu_server` in the Zephyr tree.
56
57The following commands build and flash RTU server sample.
58
59.. zephyr-app-commands::
60   :zephyr-app: samples/subsys/modbus/rtu_server
61   :board: nrf52840dk/nrf52840
62   :goals: build flash
63   :compact:
64
65The following commands build and flash RTU server sample using CDC ACM UART.
66
67.. zephyr-app-commands::
68   :zephyr-app: samples/subsys/modbus/rtu_server
69   :board: nrf52840dk/nrf52840
70   :goals: build flash
71   :gen-args: -DDTC_OVERLAY_FILE=cdc-acm.overlay -DEXTRA_CONF_FILE=overlay-cdc-acm.conf
72   :compact:
73
74On the client side, PC or laptop, the following command connects PyModbus
75to the RTU server. If CDC ACM UART is used, ttyUSB should be replaced by a
76matching ttyACM device.
77
78.. code-block:: console
79
80   # pymodbus.console serial --port /dev/ttyUSB0 --baudrate 19200
81                             --bytesize 8 --parity N --stopbits 2
82
83The LEDs on the board are controlled by Modbus commands FC01, FC05, FC15.
84For example, to set LED0 on use FC01 command (write_coil).
85
86.. code-block:: console
87
88   > client.write_coil address=0 value=1 slave=1
89
90Client should confirm successful communication and LED0 should light.
91
92.. code-block:: console
93
94   {
95       "address": 0,
96       "value": true
97   }
98
99To set LED0 off but LED1 and LED2 on use FC15 command (write_coils).
100
101.. code-block:: console
102
103   > client.write_coils address=0 values=0,1,1 slave=1
104
105To read LED0, LED1, LED2 state FC05 command (read_coils) can be used.
106
107.. code-block:: console
108
109   > client.read_coils address=0 count=3 slave=1
110   {
111       "bits": [
112           false,
113           true,
114           true,
115           false,
116           false,
117           false,
118           false,
119           false
120       ]
121   }
122
123It is also possible to write and read the holding registers.
124This however does not involve any special interaction
125with the peripherals on the board yet.
126
127To write single holding registers use FC06 command (write_register),
128
129.. code-block:: console
130
131   > client.write_register address=0 value=42 slave=1
132
133or FC16 command (write_registers).
134
135.. code-block:: console
136
137   > client.write_registers address=0 values=42,42,42 slave=1
138
139To read holding registers use FC03 command (read_holding_registers).
140
141.. code-block:: console
142
143   > client.read_holding_registers address=0 count=3 slave=1
144   {
145       "registers": [
146           42,
147           42,
148           42
149       ]
150   }
151
152.. _`joy-it RS-485 shield for Arduino`: https://joy-it.net/en/products/ARD-RS485
153.. _`PyModbus`: https://github.com/pymodbus-dev/pymodbus
154