1.. zephyr:code-sample:: modbus-gateway
2   :name: Modbus TCP-to-serial gateway
3   :relevant-api: modbus bsd_sockets
4
5   Implement a gateway between an Ethernet TCP-IP network and a Modbus serial line.
6
7Overview
8********
9
10This is a simple application demonstrating a gateway implementations between
11an Ethernet TCP-IP network and a Modbus serial line.
12
13Requirements
14************
15
16This sample has been tested with FRDM-K64F board,
17but it should work with any board or shield that has a network interface.
18
19Gateway example is running on an evaluation board and communicates
20with another board that has been prepared according to the instructions in
21:zephyr:code-sample:`modbus-rtu-server` sample. Client is running on 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
26In addition to the evaluation boards RS-485 shields may be used.
27The A+, B- lines of the RS-485 shields should be connected together.
28Alternatively UART RX,TX signals of two boards can be connected crosswise.
29
30Building and Running
31********************
32
33This sample can be found under
34:zephyr_file:`samples/subsys/modbus/tcp_gateway` in the Zephyr tree.
35
36The following commands build and flash gateway sample.
37
38.. zephyr-app-commands::
39   :zephyr-app: samples/subsys/modbus/tcp_gateway
40   :board: frdm_k64f
41   :goals: build flash
42   :compact:
43
44On the client side, PC or laptop, the following command connects PyModbus
45to the gateway.
46
47.. code-block:: console
48
49   # pymodbus.console tcp --host 192.0.2.1 --port 502
50
51The LEDs on the server board are controlled by Modbus commands FC01, FC05, FC15.
52For example, to set LED0 on use FC01 command (write_coil).
53
54.. code-block:: console
55
56   > client.connect
57   > client.write_coil address=0 value=1 slave=1
58
59Client should confirm successful communication and LED0 should light.
60
61.. code-block:: console
62
63   {
64       "address": 0,
65       "value": true
66   }
67
68To set LED0 off but LED1 and LED2 on use FC15 command (write_coils).
69
70.. code-block:: console
71
72   > client.write_coils address=0 values=0,1,1 slave=1
73
74To read LED0, LED1, LED2 state FC05 command (read_coils) can be used.
75
76.. code-block:: console
77
78   > client.read_coils address=0 count=3 slave=1
79   {
80       "bits": [
81           false,
82           true,
83           true,
84           false,
85           false,
86           false,
87           false,
88           false
89       ]
90   }
91
92It is also possible to write and read the holding registers.
93This however does not involve any special interaction
94with the peripherals on the board yet.
95
96To write single holding registers use FC06 command (write_register),
97
98.. code-block:: console
99
100   > client.write_register address=0 value=42 slave=1
101
102or FC16 command (write_registers).
103
104.. code-block:: console
105
106   > client.write_registers address=0 values=42,42,42 slave=1
107
108To read holding registers use FC03 command (read_holding_registers).
109
110.. code-block:: console
111
112   > client.read_holding_registers address=0 count=3 slave=1
113   {
114       "registers": [
115           42,
116           42,
117           42
118       ]
119   }
120
121.. _`PyModbus`: https://github.com/pymodbus-dev/pymodbus
122