QModbusDevice Class
QModbusDevice 类是 Modbus 类（QModbusServer 和QModbusClient ）的基类。更多内容...
| 头文件： | #include <QModbusDevice> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS SerialBus) target_link_libraries(mytarget PRIVATE Qt6::SerialBus) |
| qmake： | QT += serialbus |
| 继承自： | QObject |
| 继承自： |
公共类型
| 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 } |
公共函数
| 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 |
信号
| void | errorOccurred(QModbusDevice::Error error) |
| void | stateChanged(QModbusDevice::State state) |
受保护函数
| virtual void | close() = 0 |
| virtual bool | open() = 0 |
| void | setError(const QString &errorText, QModbusDevice::Error error) |
| void | setState(QModbusDevice::State newState) |
成员类型文档
enum QModbusDevice::ConnectionParameter
此枚举描述了Modbus设备连接可设置的可能值。
通用值（及其关联类型）如下：
| 常量 | 值 | 描述 |
|---|---|---|
QModbusDevice::SerialPortNameParameter | 0 | 此参数存储用于设备通信的串行端口，例如 COM1。QString |
QModbusDevice::SerialParityParameter | 1 | 此参数用于指定奇偶校验模式。QSerialPort::Parity |
QModbusDevice::SerialBaudRateParameter | 2 | 此参数用于指定通信的数据波特率。QSerialPort::BaudRate |
QModbusDevice::SerialDataBitsParameter | 3 | 该参数保存帧中的数据位。QSerialPort::DataBits |
QModbusDevice::SerialStopBitsParameter | 4 | 此参数保存帧中的停止位数。QSerialPort::StopBits |
QModbusDevice::NetworkPortParameter | 5 | 此参数保存网络端口。int |
QModbusDevice::NetworkAddressParameter | 6 | 该参数用于存储网络通信的主机地址。QString |
enum QModbusDevice::Error
该枚举描述了所有可能的错误情况。
| 常量 | 值 | 描述 |
|---|---|---|
QModbusDevice::NoError | 0 | 未发生任何错误。 |
QModbusDevice::ReadError | 1 | 读取操作期间发生错误。 |
QModbusDevice::WriteError | 2 | 写入操作期间发生错误。 |
QModbusDevice::ConnectionError | 3 | 尝试打开后端时发生错误。 |
QModbusDevice::ConfigurationError | 4 | 尝试设置配置参数时发生错误。 |
QModbusDevice::TimeoutError | 5 | I/O 期间发生超时。某项 I/O 操作未在规定时间内完成。 |
QModbusDevice::ProtocolError | 6 | 发生了一个 Modbus 特定协议错误。 |
QModbusDevice::ReplyAbortedError | 7 | 由于设备断开连接，响应被中止。 |
QModbusDevice::UnknownError | 8 | 发生未知错误。 |
QModbusDevice::InvalidResponseError (since Qt 6.4) | 9 | 在解析响应时发生错误，或者当前实现不支持FunctionCode 。在后一种情况下，自定义 Modbus 客户端实现可以重写processResponse() 和processPrivateResponse() 方法，以提供所需功能的支持。 |
[since 6.0] enum QModbusDevice::IntermediateError
该枚举描述了在 Modbus 响应的完整发送和接收周期中可能发生的错误。
| 常量 | 值 | 描述 |
|---|---|---|
QModbusDevice::ResponseCrcError | 0 | 收到 CRC 错误的 Modbus 响应。 |
QModbusDevice::ResponseRequestMismatch | 1 | 收到 Modbus 响应，但与打开的请求不匹配，这可能是由于 PDU 的功能代码不匹配所致。 |
如果发生了上述任何中间错误，该帧可能会一直存在，直到达到最大重试次数为止。
可通过QModbusReply 中间错误函数查看中间错误列表。
该枚举在 Qt 6.0 中引入。
另请参阅 QModbusClient::numberOfRetries() 和QModbusReply::intermediateErrors()。
enum QModbusDevice::State
此枚举描述了所有可能的设备状态。
| 常量 | 值 | 描述 |
|---|---|---|
QModbusDevice::UnconnectedState | 0 | 设备已断开连接。 |
QModbusDevice::ConnectingState | 1 | 设备正在连接中。 |
QModbusDevice::ConnectedState | 2 | 设备已连接到 Modbus 网络。 |
QModbusDevice::ClosingState | 3 | 设备正在关闭。 |
成员函数文档
[explicit] QModbusDevice::QModbusDevice(QObject *parent = nullptr)
根据指定的parent 构建一个Modbus设备。
[virtual noexcept] QModbusDevice::~QModbusDevice()
销毁QModbusDevice 实例
[pure virtual protected] void QModbusDevice::close()
该函数负责关闭 Modbus 连接。实现时必须确保该实例的state() 方法被设置为QModbusDevice::UnconnectedState 。
另请参阅 disconnectDevice()。
bool QModbusDevice::connectDevice()
将设备连接到Modbus网络。如果连接过程成功启动，则返回true ；否则返回false 。最终的连接成功确认需要将state()更改为QModbusDevice::ConnectedState 。
该函数在其实现过程中会调用open()。
另请参阅 open()。
QVariant QModbusDevice::connectionParameter(QModbusDevice::ConnectionParameter parameter) const
返回与给定连接parameter 关联的值。返回值可能为空。
默认情况下，QModbusDevice 会使用一些常见值进行初始化。串口设置为偶校验，波特率为 19200 比特/秒，8 个数据位和 1 个停止位。网络设置中，主机地址设为本地主机，端口设为 502。
注意：要使 串行连接成功，SerialPortNameParameter 必须设置为有效的通信端口。有关有效串行端口的信息可从QSerialPortInfo 获取。
注意：如果 设备已连接，则在重新连接设备后，这些设置才会生效。
另请参阅 setConnectionParameter() 和ConnectionParameter 。
QIODevice *QModbusDevice::device() const
返回用于ModBus通信的底层QIODevice 对象；如果设备尚未完全初始化，则返回nullptr 。
注意：请 勿存储指向底层设备的指针，因为该指针随时可能失效。
void QModbusDevice::disconnectDevice()
断开设备连接。
该函数在实现过程中会调用close()。
QModbusDevice::Error QModbusDevice::error() const
返回设备的错误状态。
另请参阅 setError() 和QModbusDevice::Error 。
[signal] void QModbusDevice::errorOccurred(QModbusDevice::Error error)
当发生类型为error 的错误时，会触发此信号。
QString QModbusDevice::errorString() const
返回设备错误的描述性错误文本。
另请参阅 QModbusDevice::Error 。
[pure virtual protected] bool QModbusDevice::open()
该函数由connectDevice()调用。子类必须提供一个实现，当Modbus连接成功或连接初始化成功时，该实现应返回true ；否则应返回false 。
该实现必须确保在成功时将实例的state() 设置为QModbusDevice::ConnectingState 或QModbusDevice::ConnectedState ；否则应设置为QModbusDevice::UnconnectedState 。通常，当连接过程异步返回结果时使用QModbusDevice::ConnectingState ，而同步连接行为则使用QModbusDevice::ConnectedState 。
另请参阅 connectDevice()。
void QModbusDevice::setConnectionParameter(QModbusDevice::ConnectionParameter parameter, const QVariant &value)
将parameter 的值设置为value 。如果parameter 已存在，则会覆盖其原有值。此类参数更改不会影响已建立或正在运行的连接。
另请参阅 ConnectionParameter 和connectionParameter()。
[protected] void QModbusDevice::setError(const QString &errorText, QModbusDevice::Error error)
设置设备的错误状态。ModBus 设备实现必须在发生错误时使用此函数，以设置错误类型（error ）和描述性错误代码（errorText ）。
另请参阅 error() 和QModbusDevice::Error 。
[protected] void QModbusDevice::setState(QModbusDevice::State newState)
将设备状态设置为newState 。Modbus设备实现必须使用此函数来更新设备状态。
另请参阅 state()。
QModbusDevice::State QModbusDevice::state() const
返回设备的当前状态。
另请参阅 setState() 和stateChanged()。
[signal] void QModbusDevice::stateChanged(QModbusDevice::State state)
每当设备状态发生变化时，都会发出此信号。新状态由state 表示。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
