docs/modbus_new_rtu.md

   1 # modbus_new_rtu
   2
   3 ## Name
   4
   5 modbus_new_rtu - create a libmodbus context for RTU
   6
   7 ## Synopsis
   8
   9 ```c
  10 modbus_t *modbus_new_rtu(const char *device, int baud, char parity, int data_bit, int stop_bit);
  11 ```
  12
  13 ## Description
  14
  15 The *modbus_new_rtu()* function shall allocate and initialize a `modbus_t`
  16 structure to communicate in RTU mode on a serial line.
  17
  18 The `device` argument specifies the name of the serial port handled by the OS,
  19 eg. "/dev/ttyS0" or "/dev/ttyUSB0". On Windows, it's necessary to prepend COM
  20 name with "\\.\" for COM number greater than 9, eg. "\\\\.\\COM10". See
  21 http://msdn.microsoft.com/en-us/library/aa365247(v=vs.85).aspx for details
  22
  23 The `baud` argument specifies the baud rate of the communication, eg. 9600,
  24 19200, 57600, 115200, etc.
  25
  26 The `parity` argument can have one of the following values:
  27
  28 - `N` for none
  29 - `E` for even
  30 - `O` for odd
  31
  32 The `data_bits` argument specifies the number of bits of data, the allowed
  33 values are 5, 6, 7 and 8.
  34
  35 The `stop_bits` argument specifies the bits of stop, the allowed values are 1
  36 and 2.
  37
  38 Once the `modbus_t` structure is initialized, you can connect to the serial bus
  39 with [modbus_connect](modbus_connect.md).
  40
  41 In RTU, your program can act as server or client:
  42
  43 - **server** is called *slave* in Modbus terminology, your program will expose
  44   data to the network by processing and answering the requests of one of several
  45   clients. It up to you to define the slave ID of your service with
  46   [modbus_set_slave](modbus_set_slave.md), this ID should be used by the client
  47   to communicate with your program.
  48
  49 - **client** is called *master* in Modbus terminology, your program will send
  50   requests to servers to read or write data from them. Before issuing the
  51   requests, you should define the slave ID of the remote device with
  52   [modbus_set_slave](modbus_set_slave.md). The slave ID is not an argument of
  53   the read/write functions because it's very frequent to talk with only one
  54   server so you can set it once and for all. The slave ID it not used in TCP
  55   communications so this way the API is common to both.
  56
  57 ## Return value
  58
  59 The function shall return a pointer to a `modbus_t` structure if
  60 successful. Otherwise it shall return NULL and set errno to one of the values
  61 defined below.
  62
  63 ## Errors
  64
  65 - *EINVAL*, an invalid argument was given.
  66 - *ENOMEM*, out of memory. Possibly, the application hits its memory limit
  67     and/or whole system is running out of memory.
  68
  69 ## Example
  70
  71 In this example, the program will open a serial communication on USB. All
  72 subsequent calls such as read or write of registers will be sent on the wire and
  73 the request will be visible to all connected devices. According to the Modbus
  74 protocol, only the master associated to slave ID 10 will process and answer your
  75 requests.
  76
  77 ```c
  78 const int REMOTE_ID = 10;
  79 modbus_t *ctx;
  80 uint16_t tab_reg[10];
  81
  82 ctx = modbus_new_rtu("/dev/ttyUSB0", 115200, 'N', 8, 1);
  83 if (ctx == NULL) {
  84     fprintf(stderr, "Unable to create the libmodbus context\n");
  85     return -1;
  86 }
  87
  88 if (modbus_connect(ctx) == -1) {
  89     fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
  90     modbus_free(ctx);
  91     return -1;
  92 }
  93
  94 modbus_set_slave(ctx, REMOTE_ID);
  95
  96 // Read 2 registers from address 0 of server ID 10.
  97 modbus_read_registers(ctx, 0, 2, tab_reg);
  98 ```
  99
 100 ## See also
 101
 102 - [modbus_new_tcp](modbus_new_tcp.md)
 103 - [modbus_free](modbus_free.md)