#include <device.h>

Inheritance diagram for Modbus::Device:

Public Member Functions
NetLayer &	backend () const
	underlying backend

double	byteTimeout ()
	Get timeout between bytes. More...

bool	byteTimeout (Timeout &timeout)
	Get timeout between bytes. More...

virtual void	close ()
	Close a Modbus connection.

std::string	connection () const
	Returns the connection used. More...

bool	debug () const
	Return the debug flag.

	Device (Net net, const std::string &connection, const std::string &settings)
	Constructor. More...

	Device (const std::string &jsonfile, const std::string &key=std::string())
	constructor from a JSON file More...

	Device ()
	Default constructor. More...

int	flush ()
	Flush non-transmitted data. More...

double	indicationTimeout ()
	Get timeout used to wait for an indication (request received by a server) More...

bool	indicationTimeout (Timeout &timeout)
	Get timeout used to wait for an indication (request received by a server) More...

bool	isConnected () const
	Returns true if the device is connected; otherwise returns false. More...

virtual bool	isOpen () const
	Returns true if the device is open; otherwise returns false. More...

bool	isValid () const
	returns true if backend is set

Net	net () const
	Underlying layer used (backend) More...

virtual bool	open ()
	Establish a Modbus connection. More...

bool	recoveryLink () const
	Returns true if link recovery mode is set; otherwise returns false.

double	responseTimeout ()
	Get timeout for response. More...

bool	responseTimeout (Timeout &timeout)
	Get timeout for response. More...

RtuLayer &	rtu ()
	underlying RTU layer (backend) More...

int	sendRawMessage (Message *msg, bool prepareBefore=false)
	Send a request/response msg via the socket of the context() More...

int	sendRawMessage (Message &msg, bool prepareBefore=false)

bool	setBackend (Net net, const std::string &connection, const std::string &setting)
	Sets the backend for the net network. More...

bool	setByteTimeout (const double &timeout)
	Set timeout between bytes. More...

bool	setByteTimeout (const Timeout &timeout)
	Set timeout between bytes. More...

bool	setConfig (const std::string &jsonfile, const std::string &key=std::string())
	Set configuration from a JSON file. More...

bool	setDebug (bool debug=true)
	Set debug flag. More...

bool	setIndicationTimeout (const double &timeout)
	Set timeout for indication. More...

bool	setIndicationTimeout (const Timeout &timeout)
	Set timeout for indication. More...

virtual bool	setRecoveryLink (bool recovery=true)
	Set the link recovery mode after disconnection. More...

bool	setResponseTimeout (const double &timeout)
	Set timeout for response. More...

bool	setResponseTimeout (const Timeout &timeout)
	Set timeout for response. More...

std::string	settings () const
	Returns the connection settings. More...

TcpLayer &	tcp ()
	underlying TCP layer (backend) More...

virtual	~Device ()
	Destructor. More...

Static Public Member Functions
static std::string	lastError ()
	last error message More...

Detailed Description

Device connected to Modbus.

This class is the base class for Master and Slave. It groups together their common properties and methods.

Author: Pascal JEAN, aka epsilonrt

Copyright: GNU Lesser General Public License

Examples:: server/callback-server-json/main.cpp.

Constructor & Destructor Documentation

◆ Device() [1/3]

Modbus::Device::Device	(	Net	net,
		const std::string &	connection,
		const std::string &	settings
	)

Constructor.

Constructs a Modbus device for the net network.

For the Tcp backend :

connection specifies the host name or IP address of the host to connect to, eg. "192.168.0.5" , "::1" or "server.com". "*" value can be used to listen any addresses in server mode,
settings is the service name/port number to connect to. To use the default Modbus port use the string "502". On many Unix systems, it’s convenient to use a port number greater than or equal to 1024 because it’s not necessary to have administrator privileges.

For the Rtu backend :

connection specifies the name of the serial port handled by the OS, eg. "/dev/ttyS0" or "/dev/ttyUSB0",
settings specifies communication settings as a string in the format BBBBPS. BBBB specifies the baud rate of the communication, PS specifies the parity and the bits of stop, e.g. 38400E1 for 38400 baud with even parity and 1 stop.

According to Modbus RTU specifications :
- the possible combinations for PS are E1, O1 and N2.
- the number of bits of data must be 8, also there is no possibility to change this setting

An exception std::invalid_argument is thrown if one of the parameters is incorrect.

◆ Device() [2/3]

Modbus::Device::Device	(	const std::string &	jsonfile,
		const std::string &	key = `std::string()`
	)

explicit

constructor from a JSON file

The file describes the configuration to apply, its format is as follows:

{
  "modbuspp-device": {
    "mode": "tcp",
    "connection": "localhost",
    "settings": "1502",
    "recovery-link": true,
    "debug": true,
    "response-timeout": 500,
    "byte-timeout": 500
  }
}

Only the first 3 elements are mandatory : mode, connection and settings, the others are optional. In this example "modbuspp-device" is the key to the JSON object that should be used. If the key provided is empty, the file contains only one object corresponding to the configuration.

Parameters

jsonfile	JSON file path
key	name of the object key in the JSON file corresponding to the configuration to be applied

◆ Device() [3/3]

Modbus::Device::Device ( )

Default constructor.

object cannot be used without calling setBackend() or setConfig()

◆ ~Device()

virtual Modbus::Device::~Device ( )

virtual

Destructor.

The destructor closes the connection if it is open and releases all affected resources.

Member Function Documentation

◆ byteTimeout() [1/2]

double Modbus::Device::byteTimeout ( )

Get timeout between bytes.

Returns: timeout between bytes in seconds.

See also: setByteTimeout()

◆ byteTimeout() [2/2]

bool Modbus::Device::byteTimeout ( Timeout & timeout )

Get timeout between bytes.

This function shall store the timeout interval between two consecutive bytes of the same message in the timeout argument.

Parameters

timeout reference on the variable that will contain the timeout value

Returns: true if successful.

See also: setByteTimeout()

◆ connection()

std::string Modbus::Device::connection ( ) const

Returns the connection used.

Serial port or host depending on the backend.

For the Tcp backend :

connection specifies the host name or IP address of the host to connect to, eg. "192.168.0.5" , "::1" or "server.com".

For the Rtu backend :

connection specifies the name of the serial port handled by the OS, eg. "/dev/ttyS0" or "/dev/ttyUSB0",

Examples:: master/read-coils/main.cpp, master/read-holding-data/main.cpp, master/read-input-registers/main.cpp, master/report-slave-id/main.cpp, master/rw-holding-json/main.cpp, master/write-holding-data/main.cpp, router/router-json/main.cpp, router/router-simple/main.cpp, server/callback-server-json/main.cpp, server/clock-server-json/main.cpp, server/clock-server/main.cpp, and server/simple-server-json/main.cpp.

◆ flush()

int Modbus::Device::flush ( )

Flush non-transmitted data.

This function shall discard data received but not read to the socket or file descriptor associated to this connection.

Returns: 0 or the number of flushed bytes if successful. Otherwise it shall return -1 and set errno.

◆ indicationTimeout() [1/2]

double Modbus::Device::indicationTimeout ( )

Get timeout used to wait for an indication (request received by a server)

This function shall return the timeout interval used to wait for an indication in timeout. Indication is the term used by the Modbus protocol to designate a request received by the server.

The default value is zero, it means the server will wait forever.

Returns: timeout for indication in seconds.

See also: setIndicationTimeout()

◆ indicationTimeout() [2/2]

bool Modbus::Device::indicationTimeout ( Timeout & timeout )

Get timeout used to wait for an indication (request received by a server)

This function shall return the timeout interval used to wait for an indication in timeout. Indication is the term used by the Modbus protocol to designate a request received by the server.

The default value is zero, it means the server will wait forever.

Parameters

timeout reference on the variable that will contain the timeout value

Returns: true if successful.

See also: setIndicationTimeout()

◆ isConnected()

bool Modbus::Device::isConnected ( ) const

Returns true if the device is connected; otherwise returns false.

in RTU mode, this function returns the same value as isOpen().

in TCP mode, this function returns true if a peer-to-peer TCP connection is currently established. Indeed, in server mode (slave), calling the open() function puts the Device in passive waiting mode, so that it is open but not connected. It is when a client connects that the function returns true.

See also: isOpen()

◆ isOpen()

virtual bool Modbus::Device::isOpen ( ) const

virtual

Returns true if the device is open; otherwise returns false.

See also: open()

Examples:: router/router-json/main.cpp, router/router-simple/main.cpp, server/callback-server-json/main.cpp, server/clock-server-json/main.cpp, server/clock-server/main.cpp, and server/simple-server-json/main.cpp.

◆ lastError()

static std::string Modbus::Device::lastError ( )

static

last error message

This function shall return the error message corresponding to the last error. This function must be called right after the instruction that triggered an error.

Examples:: master/read-coils/main.cpp, master/read-holding-data/main.cpp, master/read-input-registers/main.cpp, master/report-slave-id/main.cpp, master/rw-holding-json/main.cpp, and master/write-holding-data/main.cpp.

◆ net()

Net Modbus::Device::net ( ) const

Underlying layer used (backend)

This function allows to know the underlying layer used.

◆ open()

virtual bool Modbus::Device::open ( )

virtual

Establish a Modbus connection.

This function shall establish a connection to a Modbus server, a network or a bus

Returns: true if successful. Otherwise it shall return -1 and set errno.

Examples:: master/read-coils/main.cpp, master/read-holding-data/main.cpp, master/read-input-registers/main.cpp, master/report-slave-id/main.cpp, master/rw-holding-json/main.cpp, master/write-holding-data/main.cpp, router/router-json/main.cpp, router/router-simple/main.cpp, server/callback-server-json/main.cpp, server/clock-server-json/main.cpp, server/clock-server/main.cpp, and server/simple-server-json/main.cpp.

◆ responseTimeout() [1/2]

double Modbus::Device::responseTimeout ( )

Get timeout for response.

Returns: timeout for response in seconds.

See also: setResponseTimeout()

◆ responseTimeout() [2/2]

bool Modbus::Device::responseTimeout ( Timeout & timeout )

Get timeout for response.

This function shall return the timeout interval used to wait for a response in the timeout argument.

Parameters

timeout reference on the variable that will contain the timeout value

Returns: true if successful.

See also: setResponseTimeout()

◆ rtu()

RtuLayer& Modbus::Device::rtu ( )

underlying RTU layer (backend)

This function shall return the RTU layer if it is the layer used by the device. If it does not, a std::domain_error exception is thrown.

Examples:: router/router-simple/main.cpp.

◆ sendRawMessage() [1/2]

int Modbus::Device::sendRawMessage	(	Message *	msg,
		bool	prepareBefore = `false`
	)

Send a request/response msg via the socket of the context()

This function can be used to send message not handled by the library. The message is transmitted "raw", without any modification if prepareBefore is false, otherwise the message is modified to add a header (for TCP-IP) or a CRC (for RTU).

Returns: The function shall return the full message length, if successful. Otherwise it shall return -1 and set errno

Warning: This function is not supported in RTU mode on Windows™.

Examples:: server/callback-server-json/main.cpp.

◆ sendRawMessage() [2/2]

int Modbus::Device::sendRawMessage	(	Message &	msg,
		bool	prepareBefore = `false`
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ setBackend()

bool Modbus::Device::setBackend	(	Net	net,
		const std::string &	connection,
		const std::string &	setting
	)

Sets the backend for the net network.

This function does nothing if isValid() is true and returns false.

For the Tcp backend :

connection specifies the host name or IP address of the host to connect to, eg. "192.168.0.5" , "::1" or "server.com". "*" value can be used to listen any addresses in server mode,
settings is the service name/port number to connect to. To use the default Modbus port use the string "502". On many Unix systems, it’s convenient to use a port number greater than or equal to 1024 because it’s not necessary to have administrator privileges.

For the Rtu backend :

connection specifies the name of the serial port handled by the OS, eg. "/dev/ttyS0" or "/dev/ttyUSB0",
settings specifies communication settings as a string in the format BBBBPS. BBBB specifies the baud rate of the communication, PS specifies the parity and the bits of stop, e.g. 38400E1 for 38400 baud with even parity and 1 stop.

According to Modbus RTU specifications :
- the possible combinations for PS are E1, O1 and N2.
- the number of bits of data must be 8, also there is no possibility to change this setting

An exception std::invalid_argument is thrown if one of the parameters is incorrect.

Returns: true if successful.

Examples:: router/router-simple/main.cpp, and server/clock-server/main.cpp.

◆ setByteTimeout() [1/2]

bool Modbus::Device::setByteTimeout ( const double & timeout )

Set timeout between bytes.

This function shall set the timeout interval between two consecutive bytes of the same message. The timeout is an upper bound on the amount of time elapsed before select() returns, if the time elapsed is longer than the defined timeout, an ETIMEDOUT error will be raised by the function waiting for a response.

Parameters

timeout reference on the variable that will contain the new timeout in seconds.

Returns: true if successful.

See also: byteTimeout()

◆ setByteTimeout() [2/2]

bool Modbus::Device::setByteTimeout ( const Timeout & timeout )

Set timeout between bytes.

This function shall set the timeout interval between two consecutive bytes of the same message. The timeout is an upper bound on the amount of time elapsed before select() returns, if the time elapsed is longer than the defined timeout, an ETIMEDOUT error will be raised by the function waiting for a response.

Parameters

timeout reference on the variable that will contain the new timeout value

Returns: true if successful.

See also: byteTimeout()

◆ setConfig()

bool Modbus::Device::setConfig	(	const std::string &	jsonfile,
		const std::string &	key = `std::string()`
	)

Set configuration from a JSON file.

This function does nothing if isValid() is true and returns false.

The file describes the configuration to apply, its format is as follows:

{
  "modbuspp-device": {
    "mode": "tcp",
    "connection": "localhost",
    "settings": "1502",
    "recovery-link": true,
    "debug": true,
    "response-timeout": 500,
    "byte-timeout": 500
  }
}

Only the first 3 elements are mandatory : mode, connection and settings, the others are optional. In this example "modbuspp-device" is the key to the JSON object that should be used. If the key provided is empty, the file contains only one object corresponding to the configuration.

Parameters

jsonfile	JSON file path
key	name of the object key in the JSON file corresponding to the configuration to be applied

Returns: true if successful.

Examples:: router/router-json/main.cpp, server/callback-server-json/main.cpp, server/clock-server-json/main.cpp, and server/simple-server-json/main.cpp.

◆ setDebug()

bool Modbus::Device::setDebug ( bool debug = true )

Set debug flag.

This function function shall set the debug flag by using the argument flag. By default, the boolean flag is set to false. When the flag value is set to true, many verbose messages are displayed on stdout and stderr. For example, this flag is useful to display the bytes of the Modbus messages :

[00][14][00][00][00][06][12][03][00][6B][00][03]
Waiting for a confirmation...
<00><14><00><00><00><09><12><03><06><02><2B><00><00><00><00>

Returns: true if successful. Otherwise it shall return false and set errno.

Examples:: router/router-simple/main.cpp, and server/clock-server/main.cpp.

◆ setIndicationTimeout() [1/2]

bool Modbus::Device::setIndicationTimeout ( const double & timeout )

Set timeout for indication.

This function shall set the timeout interval used by a server to wait for a request from a client. If timeout is zero, this timeout will not be used at all. In this case, the server will wait forever.

Parameters

timeout reference on the variable that will contain the new timeout in seconds.

Returns: true if successful.

See also: indicationTimeout()

◆ setIndicationTimeout() [2/2]

bool Modbus::Device::setIndicationTimeout ( const Timeout & timeout )

Set timeout for indication.

This function shall set the timeout interval used by a server to wait for a request from a client. If timeout is zero, this timeout will not be used at all. In this case, the server will wait forever.

Parameters

timeout reference on the variable that will contain the new timeout value

Returns: true if successful.

See also: indicationTimeout()

◆ setRecoveryLink()

virtual bool Modbus::Device::setRecoveryLink ( bool recovery = true )

virtual

Set the link recovery mode after disconnection.

When is set, the library will attempt an immediate reconnection when the connection is reset by peer.

Returns: true if successful.

Reimplemented in Modbus::Master.

Examples:: router/router-simple/main.cpp, and server/clock-server/main.cpp.

◆ setResponseTimeout() [1/2]

bool Modbus::Device::setResponseTimeout ( const double & timeout )

Set timeout for response.

This function shall set the timeout interval used to wait for a response. When a byte timeout is set, if elapsed time for the first byte of response is longer than the given timeout, an ETIMEDOUT error will be raised by the function waiting for a response. When byte timeout is disabled, the full confirmation response must be received before expiration of the response timeout.

Parameters

timeout reference on the variable that will contain the new timeout in seconds.

Returns: true if successful.

See also: responseTimeout()

◆ setResponseTimeout() [2/2]

bool Modbus::Device::setResponseTimeout ( const Timeout & timeout )

Set timeout for response.

This function shall set the timeout interval used to wait for a response. When a byte timeout is set, if elapsed time for the first byte of response is longer than the given timeout, an ETIMEDOUT error will be raised by the function waiting for a response. When byte timeout is disabled, the full confirmation response must be received before expiration of the response timeout.

Parameters

timeout reference on the variable that will contain the new timeout value

Returns: true if successful.

See also: responseTimeout()

◆ settings()

std::string Modbus::Device::settings ( ) const

Returns the connection settings.

IP port or speed, parity and stop bit depending on the backend

For the Tcp backend :

settings is the service name/port number to connect to. To use the default Modbus port use the string "502". On many Unix systems, it’s convenient to use a port number greater than or equal to 1024 because it’s not necessary to have administrator privileges.

For the Rtu backend :

settings specifies communication settings as a string in the format BBBBPS. BBBB specifies the baud rate of the communication, PS specifies the parity and the bits of stop, e.g. 38400E1 for 38400 baud with even parity and 1 stop.

According to Modbus RTU specifications :
- the possible combinations for PS are E1, O1 and N2.
- the number of bits of data must be 8, also there is no possibility to change this setting

Examples:: master/read-coils/main.cpp, master/read-holding-data/main.cpp, master/read-input-registers/main.cpp, master/report-slave-id/main.cpp, master/rw-holding-json/main.cpp, master/write-holding-data/main.cpp, router/router-json/main.cpp, router/router-simple/main.cpp, server/callback-server-json/main.cpp, server/clock-server-json/main.cpp, server/clock-server/main.cpp, and server/simple-server-json/main.cpp.

◆ tcp()

TcpLayer& Modbus::Device::tcp ( )

underlying TCP layer (backend)

This function shall return the TCP layer if it is the layer used by the device. If it does not, a std::domain_error exception is thrown.

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Device() [1/3]

◆ Device() [2/3]

◆ Device() [3/3]

◆ ~Device()

Member Function Documentation

◆ byteTimeout() [1/2]

◆ byteTimeout() [2/2]

◆ connection()

◆ flush()

◆ indicationTimeout() [1/2]

◆ indicationTimeout() [2/2]

◆ isConnected()

◆ isOpen()

◆ lastError()

◆ net()

◆ open()

◆ responseTimeout() [1/2]

◆ responseTimeout() [2/2]

◆ rtu()

◆ sendRawMessage() [1/2]

◆ sendRawMessage() [2/2]

◆ setBackend()

◆ setByteTimeout() [1/2]

◆ setByteTimeout() [2/2]

◆ setConfig()

◆ setDebug()

◆ setIndicationTimeout() [1/2]

◆ setIndicationTimeout() [2/2]

◆ setRecoveryLink()

◆ setResponseTimeout() [1/2]

◆ setResponseTimeout() [2/2]

◆ settings()

◆ tcp()