QModbusDevice Class

The QModbusDevice class is the base class for Modbus classes, QModbusServer and QModbusClient. More...

Header: #include <QModbusDevice>
CMake: find_package(Qt6 REQUIRED COMPONENTS SerialBus)
target_link_libraries(mytarget PRIVATE Qt6::SerialBus)
qmake: QT += serialbus
Inherits: QObject
Inherited By:

QModbusClient and QModbusServer

Public Types

enum ConnectionParameter { SerialPortNameParameter, SerialParityParameter, SerialBaudRateParameter, SerialDataBitsParameter, SerialStopBitsParameter, …, NetworkAddressParameter }
enum Error { NoError, ReadError, WriteError, ConnectionError, ConfigurationError, …, InvalidResponseError }
(since 6.0) enum IntermediateError { ResponseCrcError, ResponseRequestMismatch }
enum State { UnconnectedState, ConnectingState, ConnectedState, ClosingState }

Public Functions

QModbusDevice(QObject *parent = nullptr)
virtual ~QModbusDevice()
bool connectDevice()
QVariant connectionParameter(QModbusDevice::ConnectionParameter parameter) const
QIODevice *device() const
void disconnectDevice()
QModbusDevice::Error error() const
QString errorString() const
void setConnectionParameter(QModbusDevice::ConnectionParameter parameter, const QVariant &value)
QModbusDevice::State state() const

Signals

void errorOccurred(QModbusDevice::Error error)
void stateChanged(QModbusDevice::State state)

Protected Functions

virtual void close() = 0
virtual bool open() = 0
void setError(const QString &errorText, QModbusDevice::Error error)
void setState(QModbusDevice::State newState)

Detailed Description

Member Type Documentation

enum QModbusDevice::ConnectionParameter

This enum describes the possible values that can be set for a Modbus device connection.

The general purpose value (and the associated types) are:

ConstantValueDescription
QModbusDevice::SerialPortNameParameter0This parameter holds the serial port used for device communication, e.g. COM1. QString
QModbusDevice::SerialParityParameter1This parameter holds the parity checking mode. QSerialPort::Parity
QModbusDevice::SerialBaudRateParameter2This parameter holds the data baud rate for the communication. QSerialPort::BaudRate
QModbusDevice::SerialDataBitsParameter3This parameter holds the data bits in a frame. QSerialPort::DataBits
QModbusDevice::SerialStopBitsParameter4This parameter holds the number of stop bits in a frame. QSerialPort::StopBits
QModbusDevice::NetworkPortParameter5This parameter holds the network port. int
QModbusDevice::NetworkAddressParameter6This parameter holds the host address for network communication. QString

enum QModbusDevice::Error

This enum describes all the possible error conditions.

ConstantValueDescription
QModbusDevice::NoError0No errors have occurred.
QModbusDevice::ReadError1An error occurred during a read operation.
QModbusDevice::WriteError2An error occurred during a write operation.
QModbusDevice::ConnectionError3An error occurred when attempting to open the backend.
QModbusDevice::ConfigurationError4An error occurred when attempting to set a configuration parameter.
QModbusDevice::TimeoutError5A timeout occurred during I/O. An I/O operation did not finish within a given time frame.
QModbusDevice::ProtocolError6A Modbus specific protocol error occurred.
QModbusDevice::ReplyAbortedError7The reply was aborted due to a disconnection of the device.
QModbusDevice::UnknownError8An unknown error occurred.
QModbusDevice::InvalidResponseError (since Qt 6.4)9An error occurred while parsing the response, or the FunctionCode is not supported by the current implementation. In the latter case custom Modbus client implementation can override the processResponse() and processPrivateResponse() methods to provide support for needed functions.

[since 6.0] enum QModbusDevice::IntermediateError

This enum describes possible errors that can happen during a full send and receive cycle for a Modbus reply.

ConstantValueDescription
QModbusDevice::ResponseCrcError0A Modbus response with a wrong CRC was received.
QModbusDevice::ResponseRequestMismatch1A Modbus response was received but did not match the open request, probably due to the PDU's function code not matching.

If any of the above intermediate errors occurred, the frame is likely resent until the maximum number of retries has been reached.

The list of intermediate errors can be inspected from the QModbusReply intermediate errors function.

This enum was introduced in Qt 6.0.

See also QModbusClient::numberOfRetries() and QModbusReply::intermediateErrors().

enum QModbusDevice::State

This enum describes all possible device states.

ConstantValueDescription
QModbusDevice::UnconnectedState0The device is disconnected.
QModbusDevice::ConnectingState1The device is being connected.
QModbusDevice::ConnectedState2The device is connected to the Modbus network.
QModbusDevice::ClosingState3The device is being closed.

Member Function Documentation

[explicit] QModbusDevice::QModbusDevice(QObject *parent = nullptr)

Constructs a Modbus device with the specified parent.

[virtual noexcept] QModbusDevice::~QModbusDevice()

Destroys the QModbusDevice instance

[pure virtual protected] void QModbusDevice::close()

This function is responsible for closing the Modbus connection. The implementation must ensure that the instance's state() is set to QModbusDevice::UnconnectedState.

See also disconnectDevice().

bool QModbusDevice::connectDevice()

Connects the device to the Modbus network. Returns true if the connection process was successfully initiated; otherwise false. Final connection success confirmation requires the state() changing to QModbusDevice::ConnectedState.

This function calls open() as part of its implementation.

See also open().

QVariant QModbusDevice::connectionParameter(QModbusDevice::ConnectionParameter parameter) const

Returns the value associated with the given connection parameter. The returned value can be empty.

By default the QModbusDevice is initialized with some common values. The serial port settings are even parity, a baud rate of 19200 bits per second, eight data bits and one stop bit. The network settings for the host address is set to local host and port to 502.

Note: For a serial connection to succeed, the SerialPortNameParameter needs to be set to a valid communication port. The information about valid serial ports can be obtained from QSerialPortInfo.

Note: If the device is already connected, the settings are taken into account after reconnecting the device.

See also setConnectionParameter() and ConnectionParameter.

QIODevice *QModbusDevice::device() const

Returns the underlying QIODevice used for ModBus communication or nullptr if the device was not yet fully initialized.

Note: Do not store a pointer to the underlying device, because it can be invalidated at any point in time.

void QModbusDevice::disconnectDevice()

Disconnects the device.

This function calls close() as part of its implementation.

QModbusDevice::Error QModbusDevice::error() const

Returns the error state of the device.

See also setError() and QModbusDevice::Error.

[signal] void QModbusDevice::errorOccurred(QModbusDevice::Error error)

This signal is emitted when an error of the type, error, occurs.

QString QModbusDevice::errorString() const

Returns descriptive error text for the device error.

See also QModbusDevice::Error.

[pure virtual protected] bool QModbusDevice::open()

This function is called by connectDevice(). Subclasses must provide an implementation that returns true on successful Modbus connection or connection initiation; otherwise returns false.

The implementation must ensure that the instance's state() is set to QModbusDevice::ConnectingState or QModbusDevice::ConnectedState upon success; otherwise QModbusDevice::UnconnectedState. Typically, QModbusDevice::ConnectingState is used when the connection process reports back asynchronously and QModbusDevice::ConnectedState in case of synchronous connect behavior.

See also connectDevice().

void QModbusDevice::setConnectionParameter(QModbusDevice::ConnectionParameter parameter, const QVariant &value)

Sets the value of parameter to value. If the parameter already exists, the previous value is overwritten. A active or running connection is not affected by such parameter changes.

See also ConnectionParameter and connectionParameter().

[protected] void QModbusDevice::setError(const QString &errorText, QModbusDevice::Error error)

Sets the error state of the device. ModBus device implementations must use this function in case of an error to set the error type and a descriptive errorText.

See also error() and QModbusDevice::Error.

[protected] void QModbusDevice::setState(QModbusDevice::State newState)

Sets the state of the device to newState. Modbus device implementations must use this function to update the device state.

See also state().

QModbusDevice::State QModbusDevice::state() const

Returns the current state of the device.

See also setState() and stateChanged().

[signal] void QModbusDevice::stateChanged(QModbusDevice::State state)

This signal is emitted every time the state of the device changes. The new state is represented by state.

See also setState() and state().