libmodbus Chinese manual

Features

libmodbus is a fast, cross-platform Modbus library.

Description

libmodbus is a library for sending/receiving data with devices using the Modbus protocol. The library includes various backends for communication over different networks (e.g., serial port in RTU mode or Ethernet in TCP/IPv6).

The protocol specification document can be found at http://www.modbus.org/specs.php.

libmodbus provides an abstraction of the lower communication layers and offers the same API on all supported platforms.

This document introduces the concept of libmodbus, describes how libmodbus implements Modbus communication across different hardware and platforms, and provides a reference manual for the functions provided by the libmodbus library.

Contexts

The RTU backend (Remote Terminal Unit) is used for serial port communication and employs a compact binary representation of data for protocol communication. The RTU format follows command/data, with CRC (cyclic redundancy check) as an error checking mechanism to ensure data reliability. Modbus RTU is the most commonly used implementation for Modbus. Modbus RTU messages must be sent continuously without character spacing (extracted from Wikipedia, Modbus, http://en.wikipedia.org/wiki/Modbus as of March 13, 2011, 20:51 GMT).

The Modbus RTU framework involves a slave, a device/server that processes Modbus requests, and a client (master) that sends requests. Communication is always initiated by the master server.

Many Modbus devices can be connected together on the same physical link (bus structure), so before sending messages, the slave (receiving device) ID must be set using modbus_set_slave. If you are running a slave, its slave number will be used to filter received messages.

Creating a Modbus RTU Environment

The initial RTU environment pointer modbus_t *modbus_new_rtu(const char *device, int baud, char parity, int data_bit, int stop_bit)

modbus_t *modbus_new_rtu(const char *device, int baud, char parity, int data_bit, int stop_bit);
 
 
//参考代码：
modbus_t *ctx;
 
ctx = modbus_new_rtu("/dev/ttyUSB0", 115200, 'N', 8, 1);
if (ctx == NULL) {
    fprintf(stderr, "Unable to create the libmodbus contextn");
    return -1;
}

This modbus_new_rtu() function generates and initializes a modbus structure to communicate in RTU mode over a serial line.

device specifies the name of the serial port handled by the OS, such as /dev/ttyS0 or /dev/ttyUSB0. On Windows systems, if the COM port number is greater than 9, it must be prefixed with ., such as .COM10., referring to http://msdn.microsoft.com/en-us/library/aa365247(v=vs.85).aspx

baud: specifies the baud rate of the connection, such as 9600, 19200, 57600, 115200, etc.

parity: represents the parity bit, with the following values:

N (no parity)

E (even parity)

O (odd parity)

data_bit: specifies the number of data bits, with allowed values of 5, 6, 7, and 8.

stop_bit: specifies the number of stop bits, with allowed values of 1 and 2.

Return: If the establishment is successful, the modbus_new_rtu() function will return a pointer to the modbus_t structure. Otherwise, it will return NULL and set errno to An invalid argument was given.

Set serial port mode

Get current serial port mode: int modbus_rtu_get_serial_mode(modbus_t *ctx);

int modbus_rtu_get_serial_mode (modbus_t *ctx);

Return: If successful, the function should returnMODBUS_RTU_RS232 orMODBUS_RTU_RS485. Otherwise, it will return -1 and set errno to "The current libmodbus backend is not RTU."

This is only used in RTU environments.

Set serial port mode:int modbus_rtu_set_serial_mode(modbus_t *ctx, intmode);

int modbus_rtu_set_serial_mode(modbus_t *ctx, int mode);

mode: Fill in MODBUS_RTU_RS232 or MODBUS_RTU_RS485

Return value: If successful, the function should return 0. Otherwise, it will return -1 and set errno to one of the values defined below.

EINVAL The current libmodbus backend is not RTU.

ENOTSUP The function is not supported on your platform.

If the call to ioctl() fails, the error code of ioctl will be returned.

In RTU environment, the current RTS mode can be obtained by calling int modbus_rtu_get_rts(modbus_t *ctx)(added in version 3.1.4)).

int modbus_rtu_get_rts (modbus_t *ctx);

The mode used to send requests in the current ctx environment can be obtained.

Return value:

   MODBUS_RTU_RTS_NONE

   MODBUS_RTU_RTS_UP

   MODBUS_RTU_RTS_DOWN

   -1，即调用失败，并设置EINVAL为The libmodbus backend is not RTU.

In RTU environment, the set RTS mode can be obtained by calling int modbus_rtu_set_rts(modbus_t *ctx, intmode)(added in version 3.1.4)).

int modbus_rtu_set_rts(modbus_t *ctx, int mode);
 
//例子：启动有正极性的RTS模式
modbus_t *ctx;
uint16_t tab_reg[10];
 
ctx = modbus_new_rtu("/dev/ttyS0", 115200, 'N', 8, 1);
modbus_set_slave(ctx, 1);
modbus_rtu_set_serial_mode(ctx, MODBUS_RTU_RS485);
modbus_rtu_set_rts(ctx, MODBUS_RTU_RTS_UP);
 
if (modbus_connect(ctx) == -1) {
    fprintf(stderr, "Connexion failed: %sn", modbus_strerror(errno));
    modbus_free(ctx);
    return -1;
}
 
rc = modbus_read_registers(ctx, 0, 7, tab_reg);
if (rc == -1) {
    fprintf(stderr, "%sn", modbus_strerror(errno));
    return -1;
}
 
modbus_close(ctx);
modbus_free(ctx);

The set send request mode is used for communication on the RS485 serial bus. The default mode is MODBUS_RTU_RTS_NONE, and no signal will be sent before data is written to the line.

To enable RTS mode, MODBUS_RTU_RTS_UP or MODBUS_RTU_RTS_DOWN must be used. These modes enable RTS mode and set the polarity simultaneously. When using MODBUS_RTU_RTS_UP, set the RTS flag to enabled and perform an ioctl call. Then, after a delay of 1 millisecond, write data to the bus, and set the RTS flag to disabled for another ioctl call, followed by another delay of 1 millisecond. The MODBUS_RTU_RTS_DOWN mode is similar, but uses the opposite RTS flag bit.

If successful, the function should return 0. Otherwise, it will return -1 and errno will be set to "The libmodbus backend isn’t RTU or the mode given in argument is invalid.".

Custom RTS Implementation int modbus_rtu_set_custom_rts(modbus_t *ctx, void (set_rts) (modbus_t ctx, int on))(Added in version 3.1.4)

int modbus_rtu_set_custom_rts(modbus_t *ctx, void (set_rts) (modbus_t ctx, int on));

Sets the custom function to be called for setting the RST PIN before and after transmission. By default, the internal function that switches the RTS PIN using IOCTL calls is set.

Note that this function follows the RTS mode and must be called with the values MODBUS_RTU_RTS_UP or MODBUS_RTU_RTS_DOWN.

Return: If successful, the modbus_rtu_set_custom_rts() function should return 0. Otherwise, it will return -1 and set errno to The libmodbus backend is not RTU