Crate libmodbus

This is an 'hopefully' safe Rust interface for the libmodbus C library from http://libmodbus.org/.

libmodbus is a library to send/receive data with a device which respects the Modbus protocol. This library contains various backends to communicate over different networks (eg. serial in RTU mode or Ethernet in TCP/IPv6). The http://www.modbus.org site provides documentation about the protocol 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 documentation presents an overview of libmodbus concepts, describes how libmodbus abstracts Modbus communication with different hardware and platforms and provides a reference manual for the functions provided by the libmodbus library.

This project hosts the original libmodbus documentation, used here, as well.
Please have a look at: libmodbus/libmodbus.html

Contexts

The Modbus protocol contains many variants (eg. serial RTU or Ehternet TCP), to ease the implementation of a variant, the library was designed to use a backend for each variant.

libmodbus-rs provides traits and matching implementations for these variants. See ModbusRTU (trait), Modbus::new_rtu() (implementation) or ModbusTCP (trait).

The backends are also a convenient way to fulfill other requirements (eg. real-time operations). Each backend offers a specific function to create a new modbus_t context. The modbus_t context is an opaque structure containing all necessary information to establish a connection with others Modbus devices according to the selected variant.

You can choose the best context for your needs among:

• RTU Context
• TCP (IPv4) Context
• TCP PI (IPv4 and IPv6) Context

RTU Context

The RTU backend (Remote Terminal Unit) is used in serial communication and makes use of a compact, binary representation of the data for protocol communication. The RTU format follows the commands/data with a cyclic redundancy check checksum as an error check mechanism to ensure the reliability of data. Modbus RTU is the most common implementation available for Modbus. A Modbus RTU message must be transmitted continuously without inter-character hesitations (extract from Wikipedia, Modbus, http://en.wikipedia.org/wiki/Modbus (as of Mar. 13, 2011, 20:51 GMT).

The Modbus RTU framing calls a slave, a device/service which handle Modbus requests, and a master, a client which send requests. The communication is always initiated by the master.

Many Modbus devices can be connected together on the same physical link so before sending a message, you must set the slave (receiver) with modbus_set_slave(3). If you’re running a slave, its slave number will be used to filter received messages.

The libmodbus implementation of RTU isn’t time based as stated in original Modbus specification, instead all bytes are sent as fast as possible and a response or an indication is considered complete when all expected characters have been received. This implementation offers very fast communication but you must take care to set a response timeout of slaves less than response timeout of master (ortherwise other slaves may ignore master requests when one of the slave is not responding).

• Create a Modbus RTU context

  • new_rtu()

• Set the serial mode

  • rtu_get_serial_mode(), rtu_set_serial_mode(), rtu_get_rts(), rtu_set_rts(), rtu_set_custom_rts(), rtu_get_rts_delay(), rtu_set_rts_delay()

TCP (IPv4) Context

The TCP backend implements a Modbus variant used for communications over TCP/IPv4 networks. It does not require a checksum calculation as lower layer takes care of the same.

• Create a Modbus TCP context
  • new_tcp()

TCP PI (IPv4 and IPv6) Context

The TCP PI (Protocol Independent) backend implements a Modbus variant used for communications over TCP IPv4 and IPv6 networks. It does not require a checksum calculation as lower layer takes care of the same.

Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname resolution but it consumes about 1Kb of additional memory.

• Create a Modbus TCP context
  • new_tcp_pi()

Common

Common methods to modify or change the current modbus context. Some of these function are not nessesary in Rust (e.g. because the Drop trait and so on)

• Free libmodbus context
  • free() It should normaly not nessesary to call this function.
    Memory handling under Rust controlls the Drop trait in "the book" you'll find more information about.
• Set slave ID
  • set_slave()
• Enable debug mode
  • set_debug()
• Timeout settings

• get_byte_timeout() set_byte_timeout() get_response_timeout() set_response_timeout()

• Error recovery mod
  • set_error_recovery()
• Setter/getter of internal socket
  • set_socket() get_socket()
• Information about header
  • get_header_length()

Connection

Client

The Modbus protocol defines different data types and functions to read and write them from/to remote devices. The following functions are used by the clients to send Modbus requests:

• Read data
  • read_bits(), read_input_bits(), read_registers(), read_input_registers(), report_slave_id()
• Write data
  • write_bit(), write_register(), write_bits(), write_registers()
• Write and read data
  • write_and_read_registers()
• Raw requests
  • send_raw_request(), receive_confirmation()
• Reply an exception
  • reply_exception()

Server

The server is waiting for request from clients and must answer when it is concerned by the request.

In TCP , you must not use the usual connect() to establish the connection but a pair of accept/listen calls

• tcp_listen(), tcp_accept(), tcp_pi_listen(), tcp_pi_accept()

then the data can be received with

• receive()

and a response can be send with

• reply(), reply_exception()

To handle the mapping of your Modbus data, you must use a ModbusMapping struct: ModbusMapping::new()

Re-exports

pub use self::error::*;

Modules

error
prelude

Structs

Modbus	Safe interface for libmodbus
ModbusMapping	To handle the mapping of your Modbus data, you must use this struct
Timeout	Timeout struct

Enums

ErrorRecoveryMode
Exception	Modbus protocol exceptions
FunctionCode	Modbus function codes
RequestToSendMode
SerialMode

Traits

ModbusClient	The Modbus protocol defines different data types and functions to read and write them from/to remote devices. The following functions are used by the clients to send Modbus requests:
ModbusRTU	The RTU backend (Remote Terminal Unit) is used in serial communication and makes use of a compact, binary representation of the data for protocol communication. The RTU format follows the commands/data with a cyclic redundancy check checksum as an error check mechanism to ensure the reliability of data. Modbus RTU is the most common implementation available for Modbus. A Modbus RTU message must be transmitted continuously without inter-character hesitations (extract from Wikipedia, Modbus, http://en.wikipedia.org/wiki/Modbus (as of Mar. 13, 2011, 20:51 GMT).
ModbusServer	The server is waiting for request from clients and must answer when it is concerned by the request. The libmodbus offers the following functions to handle requests:
ModbusTCP	The TCP backend implements a Modbus variant used for communications over TCP/IPv4 networks. It does not require a checksum calculation as lower layer takes care of the same.
ModbusTCPPI	The TCP PI (Protocol Independent) backend implements a Modbus variant used for communications over TCP IPv4 and IPv6 networks. It does not require a checksum calculation as lower layer takes care of the same.

Functions

get_byte_from_bits	get_byte_from_bits - get the value from many bit
get_float_abcd	get_float_abcd - get a float value from 2 registers in ABCD byte order
get_float_badc	get_float_badc - get a float value from 2 registers in BADC byte order
get_float_cdab	get_float_cdab - get a float value from 2 registers in CDAB byte order
get_float_dcba	get_float_dcba - get a float value from 2 registers in DCBA byte order
set_bits_from_byte	set_bits_from_byte - set many bits from a single byte value
set_bits_from_bytes	set_bits_from_bytes - set many bits from an array of bytes
set_float_abcd	set_float_abcd - set a float value in 2 registers using ABCD byte order
set_float_badc	set_float_badc - set a float value in 2 registers using BADC byte order
set_float_cdab	set_float_cdab - set a float value in 2 registers using CDAB byte order
set_float_dcba	set_float_dcba - set a float value in 2 registers using DCBA byte order