Improve new_rtu and set_slave documentation (related to #276)

Stéphane Raimbault
1 parent 0e2f470a
Showing 2 changed files with 38 additions and 1 deletions
doc/modbus_new_rtu.txt
doc/modbus_set_slave.txt
@@ -15,7 +15,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
-The *modbus_new_rtu()* function shall allocate and initialize a modbus_t
+The *modbus_new_rtu()* function shall allocate and initialize a _modbus_t_
 structure to communicate in RTU mode on a serial line.
 The _device_ argument specifies the name of the serial port handled by the OS,
@@ -37,6 +37,9 @@ 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 linkmb:modbus_set_slave[3] and connect to the serial bus with
+linkmb:modbus_connect[3].
 RETURN VALUE
 ------------
@@ -62,6 +65,14 @@ if (ctx == NULL) {
     fprintf(stderr, "Unable to create the libmodbus context\n");
     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;
+}
 -------------------
 SEE ALSO
@@ -45,6 +45,32 @@ ERRORS
 The slave number is invalid.
+EXAMPLE
+-------
+[source,c]
+-------------------
+modbus_t *ctx;
+
+ctx = modbus_new_rtu("/dev/ttyUSB0", 115200, 'N', 8, 1);
+if (ctx == NULL) {
+    fprintf(stderr, "Unable to create the libmodbus context\n");
+    return -1;
+}
+
+rc = modbus_set_slave(ctx, YOUR_DEVICE_ID);
+if (rc == -1) {
+    fprintf(stderr, "Invalid slave ID\n");
+    modbus_free(ctx);
+    return -1;
+}
+
+if (modbus_connect(ctx) == -1) {
+    fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
+    modbus_free(ctx);
+    return -1;
+}
+-------------------
+
 AUTHORS
 -------
 The libmodbus documentation was written by Stéphane Raimbault