1.. zephyr:code-sample:: modbus-tcp-server
2   :name: Modbus TCP server
3   :relevant-api: modbus bsd_sockets
4
5   Implement a Modbus TCP server exposing Modbus commands to control LEDs.
6
7Overview
8********
9
10This is a simple application demonstrating a Modbus TCP server implementation
11in Zephyr RTOS.
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.
18Additionally the board should have three LEDs.
19
20TCP 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
26Building and Running
27********************
28
29This sample can be found under
30:zephyr_file:`samples/subsys/modbus/tcp_server` in the Zephyr tree.
31
32The following commands build and flash TCP server sample.
33
34.. zephyr-app-commands::
35   :zephyr-app: samples/subsys/modbus/tcp_server
36   :board: frdm_k64f
37   :goals: build flash
38   :compact:
39
40On the client side, PC or laptop, the following command connects PyModbus
41to the TCP server.
42
43.. code-block:: console
44
45   # pymodbus.console tcp --host 192.0.2.1 --port 502
46
47The LEDs on the board are controlled by Modbus commands FC01, FC05, FC15.
48For example, to set LED0 on use FC01 command (write_coil).
49
50.. code-block:: console
51
52   > client.connect
53   > client.write_coil address=0 value=1 unit=1
54
55Client should confirm successful communication and LED0 should light.
56
57.. code-block:: console
58
59   {
60       "address": 0,
61       "value": true
62   }
63
64To set LED0 off but LED1 and LED2 on use FC15 command (write_coils).
65
66.. code-block:: console
67
68   > client.write_coils address=0 values=0,1,1 unit=1
69
70To read LED0, LED1, LED2 state FC05 command (read_coils) can be used.
71
72.. code-block:: console
73
74   > client.read_coils address=0 count=3 unit=1
75   {
76       "bits": [
77           false,
78           true,
79           true,
80           false,
81           false,
82           false,
83           false,
84           false
85       ]
86   }
87
88It is also possible to write and read the holding registers.
89This however does not involve any special interaction
90with the peripherals on the board yet.
91
92To write single holding registers use FC06 command (write_register),
93
94.. code-block:: console
95
96   > client.write_register address=0 value=42 unit=1
97
98or FC16 command (write_registers).
99
100.. code-block:: console
101
102   > client.write_registers address=0 values=42,42,42 unit=1
103
104To read holding registers use FC03 command (read_holding_registers).
105
106.. code-block:: console
107
108   > client.read_holding_registers address=0 count=3 unit=1
109   {
110       "registers": [
111           42,
112           42,
113           42
114       ]
115   }
116
117.. _`PyModbus`: https://github.com/riptideio/pymodbus
118