docs/modbus_report_slave_id.md

   1 # modbus_report_slave_id
   2
   3 ## Name
   4
   5 modbus_report_slave_id - returns a description of the controller
   6
   7 ## Synopsis
   8
   9 ```c
  10 int modbus_report_slave_id(modbus_t *ctx, int max_dest, uint8_t *dest);
  11 ```
  12
  13 ## Description
  14
  15 The *modbus_report_slave_id()* function shall send a request to the controller
  16 to obtain a description of the controller.
  17
  18 The response stored in `dest` contains:
  19
  20 - the slave ID, this unique ID is in reality not unique at all so it's not
  21   possible to depend on it to know how the information are packed in the
  22   response.
  23 - the run indicator status (0x00 = OFF, 0xFF = ON)
  24 - additional data specific to each controller. For example, libmodbus returns
  25   the version of the library as a string.
  26
  27 The function writes at most `max_dest` bytes from the response to `dest` so
  28 you must ensure that `dest` is large enough.
  29
  30 ## Return value
  31
  32 The function shall return the number of read data if successful.
  33
  34 If the output was truncated due to the `max_dest` limit then the return value is
  35 the number of bytes which would have been written to `dest` if enough space had
  36 been available. Thus, a return value greater than `max_dest` means that the
  37 response data was truncated.
  38
  39 Otherwise it shall return -1 and set errno.
  40
  41 ## Example
  42
  43 ```c
  44 uint8_t tab_bytes[MODBUS_MAX_PDU_LENGTH];
  45
  46 ...
  47
  48 rc = modbus_report_slave_id(ctx, MODBUS_MAX_PDU_LENGTH, tab_bytes);
  49 if (rc > 1) {
  50     printf("Run Status Indicator: %s\n", tab_bytes[1] ? "ON" : "OFF");
  51 }
  52 ```