Improve doc about slave ID in RTU

Stéphane Raimbault
1 parent 59d34d20
Showing 7 changed files with 52 additions and 21 deletions
docs/modbus_new_rtu.md
docs/modbus_read_bits.md
docs/modbus_read_input_bits.md
docs/modbus_read_input_registers.md
docs/modbus_read_registers.md
docs/modbus_set_slave.md
docs/modbus_write_and_read_registers.md
@@ -35,9 +35,24 @@ values are 5, 6, 7 and 8.
 The `stop_bits` argument specifies the bits of stop, the allowed values are 1
 and 2.
  
-Once the `modbus_t` structure is initialized, you must set the slave of your
-device with [modbus_set_slave](modbus_set_slave.md) and connect to the serial bus with
-[modbus_connect](modbus_connect.md).
+Once the `modbus_t` structure is initialized, you can connect to the serial bus
+with [modbus_connect](modbus_connect.md).
+
+In RTU, your program can act as server or client:
+
+- **server** is called *slave* in Modbus terminology, your program will expose
+  data to the network by processing and answering the requests of one of several
+  clients. It up to you to define the slave ID of your service with
+  [modbus_set_slave](modbus_set_slave.md), this ID should be used by the client
+  to communicate with your program.
+
+- **client** is called *master* in Modbus terminology, your program will send
+  requests to servers to read or write data from them. Before issuing the
+  requests, you should define the slave ID of the remote device with
+  [modbus_set_slave](modbus_set_slave.md). The slave ID is not an argument of
+  the read/write functions because it's very frequent to talk with only one
+  server so you can set it once and for all. The slave ID it not used in TCP
+  communications so this way the API is common to both.
  
 ## Return value
  
@@ -53,8 +68,16 @@ defined below.
  
 ## Example
  
+In this example, the program will open a serial communication on USB. All
+subsequent calls such as read or write of registers will be sent on the wire and
+the request will be visible to all connected devices. According to the Modbus
+protocol, only the master associated to slave ID 10 will process and answer your
+requests.
+
 ```c
+const int REMOTE_ID = 10;
 modbus_t *ctx;
+uint16_t tab_reg[10];
  
 ctx = modbus_new_rtu("/dev/ttyUSB0", 115200, 'N', 8, 1);
 if (ctx == NULL) {
@@ -62,13 +85,16 @@ if (ctx == NULL) {
     return -1;
 }
  
-modbus_set_slave(ctx, YOUR_DEVICE_ID);
-
 if (modbus_connect(ctx) == -1) {
     fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
     modbus_free(ctx);
     return -1;
 }
+
+modbus_set_slave(ctx, REMOTE_ID);
+
+// Read 2 registers from address 0 of server ID 10.
+modbus_read_registers(ctx, 0, 2, tab_reg);
 ```
  
 ## See also
@@ -17,7 +17,7 @@ to the address `addr` of the remote device. The result of reading is stored in
 `dest` array as unsigned bytes (8 bits) set to `TRUE` or `FALSE`.
  
 You must take care to allocate enough memory to store the results in `dest`
-(at least `nb` * sizeof(uint8_t)).
+(at least `nb * sizeof(uint8_t)`).
  
 The function uses the Modbus function code 0x01 (read coil status).
  
@@ -17,7 +17,7 @@ bits to the address `addr` of the remote device.  The result of reading is store
 in `dest` array as unsigned bytes (8 bits) set to `TRUE` or `FALSE`.
  
 You must take care to allocate enough memory to store the results in `dest`
-(at least `nb` * sizeof(uint8_t)).
+(at least `nb * sizeof(uint8_t)`).
  
 The function uses the Modbus function code 0x02 (read input status).
  
@@ -17,7 +17,7 @@ input registers to address `addr` of the remote device. The result of the
 reading is stored in `dest` array as word values (16 bits).
  
 You must take care to allocate enough memory to store the results in `dest` (at
-least `nb` * sizeof(uint16_t)).
+least `nb * sizeof(uint16_t)`).
  
 The function uses the Modbus function code 0x04 (read input registers). The
 holding registers and input registers have different historical meaning, but
@@ -17,7 +17,7 @@ holding registers to the address `addr` of the remote device. The result of
 reading is stored in `dest` array as word values (16 bits).
  
 You must take care to allocate enough memory to store the results in `dest`
-(at least `nb` * sizeof(uint16_t)).
+(at least `nb * sizeof(uint16_t)`).
  
 The function uses the Modbus function code 0x03 (read holding registers).
  
@@ -15,17 +15,22 @@ int modbus_set_slave(modbus_t *ctx, int slave);
 The *modbus_set_slave()* function shall set the slave number in the libmodbus
 context.
  
-The behavior depends of network and the role of the device:
-
-*RTU*::
-Define the slave ID of the remote device to talk in master mode or set the
-internal slave ID in slave mode. According to the protocol, a Modbus device must
-only accept message holding its slave number or the special broadcast number.
-
-*TCP*::
-The slave number is only required in TCP if the message must reach a device on a
-serial network. Some not compliant devices or software (such as modpoll) uses
-the slave ID as unit identifier, that's incorrect (cf page 23 of Modbus
+It is usually only required to set the slave ID in **RTU**. The meaning of this
+ID will be different if your program acts as client (master) or server (slave).
+
+As **RTU client**, *modbus_set_slave()* sets the ID of the remote device you
+want to communicate. Be sure to set the slave ID before issuing any Modbus
+requests on the serial bus. If you communicate with several servers (slaves),
+you can set the slave ID of the remote device before each request.
+
+As **RTU server**, the slave ID allows the various clients to reach your
+service. You should use a free ID, once set, this ID should be known by the
+clients of the network. According to the protocol, a Modbus device must only
+accept message holding its slave number or the special broadcast number.
+
+In **TCP**, the slave number is only required if the message must reach a device
+on a serial network. Some not compliant devices or software (such as modpoll)
+uses the slave ID as unit identifier, that's incorrect (cf page 23 of Modbus
 Messaging Implementation Guide v1.0b) but without the slave value, the faulty
 remote device or software drops the requests! The special value
 `MODBUS_TCP_SLAVE` (0xFF) can be used in TCP mode to restore the default value.
@@ -23,7 +23,7 @@ to the address `read_addr` of the remote device. The result of reading is stored
 in `dest` array as word values (16 bits).
  
 You must take care to allocate enough memory to store the results in `dest`
-(at least `nb` * sizeof(uint16_t)).
+(at least `nb * sizeof(uint16_t)`).
  
 The function uses the Modbus function code 0x17 (write/read registers).