QModbusServer Class
QModbusServer 类是用于接收和处理 Modbus 请求的接口。更多内容...
| 头文件： | #include <QModbusServer> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS SerialBus) target_link_libraries(mytarget PRIVATE Qt6::SerialBus) |
| qmake： | QT += serialbus |
| 继承自： | QModbusDevice |
| 继承自： |
公共类型
| enum | Option { DiagnosticRegister, ExceptionStatusOffset, DeviceBusy, AsciiInputDelimiter, ListenOnlyMode, …, UserOption } |
公共函数
| QModbusServer(QObject *parent = nullptr) | |
| bool | data(QModbusDataUnit *newData) const |
| bool | data(QModbusDataUnit::RegisterType table, quint16 address, quint16 *data) const |
| virtual bool | processesBroadcast() const |
| int | serverAddress() const |
| bool | setData(const QModbusDataUnit &newData) |
| bool | setData(QModbusDataUnit::RegisterType table, quint16 address, quint16 data) |
| virtual bool | setMap(const QModbusDataUnitMap &map) |
| void | setServerAddress(int serverAddress) |
| virtual bool | setValue(int option, const QVariant &newValue) |
| virtual QVariant | value(int option) const |
信号
| void | dataWritten(QModbusDataUnit::RegisterType table, int address, int size) |
受保护函数
| virtual QModbusResponse | processPrivateRequest(const QModbusPdu &request) |
| virtual QModbusResponse | processRequest(const QModbusPdu &request) |
| virtual bool | readData(QModbusDataUnit *newData) const |
| virtual bool | writeData(const QModbusDataUnit &newData) |
详细说明
Modbus 网络中可以存在多个 Modbus 服务器。Modbus 服务器由 Modbus 客户端（由 `QModbusClient` 表示）进行读写操作。`QModbusServer` 与 Modbus 后端进行通信，为用户提供了一个便捷的 API。
成员类型文档
enum QModbusServer::Option
每个 Modbus 服务器都关联着一组值，每个值都有其对应的选项。
通用选项（及其关联类型）如下：
| 常量 | 值 | 描述 |
|---|---|---|
QModbusServer::DiagnosticRegister | 0 | 服务器的诊断寄存器。quint16 |
QModbusServer::ExceptionStatusOffset | 1 | 服务器的异常状态字节偏移量。quint16 |
QModbusServer::DeviceBusy | 2 | 用于指示服务器正在处理长时间运行的程序命令的标志。quint16 |
QModbusServer::AsciiInputDelimiter | 3 | Modbus ASCII 消息结束分隔符。char |
QModbusServer::ListenOnlyMode | 4 | 用于设置服务器仅监听模式的标志。此功能通常仅由 Modbus 串行设备支持。bool |
QModbusServer::ServerIdentifier | 5 | 服务器的标识符，而非服务器地址。quint8 |
QModbusServer::RunIndicatorStatus | 6 | 服务器的运行指示符。quint8 |
QModbusServer::AdditionalData | 7 | 服务器的附加数据。QByteArray |
QModbusServer::DeviceIdentification | 8 | 服务器的物理和功能描述。QModbusDeviceIdentification |
用户选项：
| 常量 | 值 | 描述 |
|---|---|---|
QModbusServer::UserOption | 0x100 | 可用于特定用户用途的首个选项。 |
对于用户选项，应由开发人员决定使用哪些类型，并确保组件在访问和设置值时使用正确的类型。
成员函数文档
[explicit] QModbusServer::QModbusServer(QObject *parent = nullptr)
根据指定的parent 构建一个Modbus服务器。
bool QModbusServer::data(QModbusDataUnit *newData) const
返回由newData 指定的寄存器范围内的值。
newData 必须提供有效的寄存器类型、起始地址和值计数。返回的newData 将包含与给定范围关联的寄存器值。
如果 `newData ` 包含有效的寄存器类型但起始地址为负数，则返回整个寄存器映射，且 `newData ` 会按适当大小进行调整。
另请参阅 setData()。
bool QModbusServer::data(QModbusDataUnit::RegisterType table, quint16 address, quint16 *data) const
读取存储在Modbus服务器中的数据。Modbus服务器包含四个表（table ），每个表都有一个唯一的address 字段，用于从目标字段读取data 。有关不同表的更多信息，请参阅QModbusDataUnit::RegisterType 。如果地址超出映射范围，或者寄存器类型甚至未被定义，则返回false 。
另请参阅 QModbusDataUnit::RegisterType 和setData()。
[signal] void QModbusServer::dataWritten(QModbusDataUnit::RegisterType table, int address, int size)
当 Modbus 客户端向 Modbus 服务器写入一个或多个数据字段时，会发出此信号。该信号包含有关已写入字段的信息：
- 已写入的寄存器类型（table ），
- address 第一个被写入字段的寄存器类型，
- 以及从address 开始写入的连续字段的size 。
当待写入字段因数值未发生变化而保持不变时，该信号不会被触发。
[virtual protected] QModbusResponse QModbusServer::processPrivateRequest(const QModbusPdu &request)
该函数应由自定义 Modbus 服务器实现。如果给定的request 不是标准 Modbus 请求，则由processRequest() 调用该函数。
重写此函数可处理《Modbus应用协议规范1.1b》中未指定的其他函数代码和子函数代码。重写实现应再次调用此函数，以确保对于自定义Modbus实现无法处理的所有未知函数代码，均返回异常响应。
此默认实现将返回一个QModbusExceptionResponse ，其中request 的函数代码和错误代码均设置为“非法函数”。
另请参阅 processRequest()。
[virtual protected] QModbusResponse QModbusServer::processRequest(const QModbusPdu &request)
处理一个 Modbus 客户端请求request 并返回一个 Modbus 响应。该函数根据请求的性质，返回QModbusResponse 或QModbusExceptionResponse 。
该函数的默认实现处理《Modbus应用协议规范1.1b》中定义的所有标准Modbus功能码。规范中未包含的所有其他Modbus功能码将转发至processPrivateRequest()。
可以通过重新实现此函数来覆盖对标准 Modbus 功能码请求的默认处理。 重写后的实现必须处理相关请求类型，并返回相应的QModbusResponse 。常见的重写原因包括：过滤用于获取数据值的功能码请求以限制读/写访问，以及过滤特定实现中不需要的功能码（例如以太网上的串行线诊断或 Modbus Plus 传输层中的功能码）。所有其他类型的请求都应转发给此默认实现。
注意： 不应通过重写此 函数来为非标准的Modbus请求类型提供自定义实现。
另请参阅 processPrivateRequest()。
[virtual] bool QModbusServer::processesBroadcast() const
如果传输层需要处理广播，子类应实现此函数。此时，如果当前处理的请求是广播请求，该实现应返回true ；否则应返回false 。默认实现始终返回false 。
注意： 此函数的返回值 仅在processRequest() 或processPrivateRequest() 内部才有意义；否则，它只能表明最后处理的请求是一个广播请求。
[virtual protected] bool QModbusServer::readData(QModbusDataUnit *newData) const
读取由newData 指定的寄存器范围内的值，并将数据写回newData 。若操作成功，则返回true ；若newData 为0 ，或newData 范围超出映射范围，或registerType()不存在，则返回false 。
int QModbusServer::serverAddress() const
返回此 Modbus 服务器实例的地址。
另请参阅 setServerAddress()。
bool QModbusServer::setData(const QModbusDataUnit &newData)
将newData 写入Modbus服务器映射表。如果newData 的范围超出映射表范围，则返回false 。
若调用成功，则触发dataWritten() 信号。请注意，当目标寄存器未发生变化时，该信号不会被触发。这种情况可能发生在newData 的值与寄存器中的值完全相同时。尽管如此，在此类情况下该函数仍会返回true 。
另请参阅 data()。
bool QModbusServer::setData(QModbusDataUnit::RegisterType table, quint16 address, quint16 data)
将数据写入Modbus服务器。一个Modbus服务器包含四个表（table ），每个表都有一个唯一的address 字段，用于将data 写入目标字段。如果地址超出映射范围，则返回false 。
若调用成功，将触发dataWritten() 信号。请注意，当data 未发生变化时，该信号不会触发。尽管如此，在此类情况下该函数仍会返回true 。
另请参阅 QModbusDataUnit::RegisterType 、data() 和dataWritten()。
[virtual] bool QModbusServer::setMap(const QModbusDataUnitMap &map)
为来自其他ModBus客户端的请求设置注册映射结构，使其指向map 。寄存器值初始化为零。成功时返回true ；否则返回false 。
如果在连接前未调用此函数，则会设置一个包含零个条目的默认寄存器。
注意：调用 此函数会丢弃之前设置的任何寄存器值。
void QModbusServer::setServerAddress(int serverAddress)
将此 Modbus 服务器实例的地址设置为serverAddress 。
另请参阅 serverAddress()。
[virtual] bool QModbusServer::setValue(int option, const QVariant &newValue)
为option 设置newValue ，成功时返回true ；否则返回false 。
注意：如果 该选项关联的类型为quint8 或quint16 ，而newValue 的类型更大，则数据将被截断，否则转换将失败。
| 键 | 描述 |
|---|---|
| QModbusServer::DiagnosticRegister | 将服务器诊断寄存器（采用设备特定编码）设置为newValue 。预设默认值为0x0000 。该寄存器的位值需参考设备特定文档。 |
| QModbusServer::ExceptionStatusOffset | 将服务器的异常状态字节偏移量设置为newValue ，该值是线圈（0x寄存器）中的绝对偏移地址。Modbus寄存器表以0x0000h 开头。默认预设值为0x0000 ，其使用与Modicon 984 CPU类似的异常状态线圈（线圈1-8）。如果线圈寄存器中包含存储和读取状态线圈所需的 8 位，则该函数返回 |
| QModbusServer::DeviceBusy | 设置一个标志，用于指示服务器正在处理一个长时间运行的程序命令。有效值为0x0000 （不忙）和0xffff （忙）。默认预设值为0x0000 。 |
| QModbusServer::AsciiInputDelimiter | newValue 将成为后续Modbus ASCII消息的消息结束分隔符。默认预设值为\n 。 |
| QModbusServer::ListenOnlyMode | 将服务器的“仅监听”状态设置为newValue 。如果“仅监听”模式设置为true ，则会监听消息但不会发送响应。默认预设值为false 。 |
| QModbusServer::ServerIdentifier | 将服务器的制造商标识符设置为newValue 。可能的值范围为0x00 到 0xff。默认预设值为0x0a 。 |
| QModbusServer::RunIndicatorStatus | 将服务器的运行指示器状态设置为newValue 。该数据由QModbusPdu::ReportServerId 功能代码用作附加信息。有效值为0x00 （OFF）和0xff （ON）。默认预设值为0xff （ON）。 |
| QModbusServer::AdditionalData | 将服务器的附加数据设置为newValue 。该数据将作为QModbusPdu::ReportServerId 功能码的补充信息使用。为符合响应消息的大小限制，数据最大大小不得超过 249 字节。预设默认值为Qt Modbus Server 。 |
| QModbusServer::DeviceIdentification | 设置服务器的物理和功能描述。默认情况下未设置任何附加设备标识数据。 |
| QModbusServer::UserOption | 将用户选项的值设置为newValue 。 注意：对于 用户选项，应由开发人员决定使用哪些类型，并确保组件在访问和设置值时使用正确的类型。 |
另请参阅 value()。
[virtual] QVariant QModbusServer::value(int option) const
若未设置该选项，则返回option 的值；否则返回无效的QVariant 。
| 选项 | 描述 |
|---|---|
| QModbusServer::DiagnosticRegister | 返回服务器的诊断寄存器值。诊断寄存器包含设备特定的内容，其中每个位都有特定的含义。 |
| QModbusServer::ExceptionStatusOffset | 返回线圈寄存器中异常状态字节位置的偏移地址。 |
| QModbusServer::DeviceBusy | 返回一个标志，用于指示服务器是否正在处理一个长时间运行的程序命令。 |
| QModbusServer::AsciiInputDelimiter | 返回 Modbus ASCII 消息的末尾分隔符。 |
| QModbusServer::ListenOnlyMode | 返回服务器的仅监听状态。此时会监听消息，但不会发送任何响应。 |
| QModbusServer::ServerIdentifier | 返回服务器的制造商标识码。该值可在0x00 至0xff的范围内取任意数值。 |
| QModbusServer::RunIndicatorStatus | 返回服务器的运行指示器状态。该数据由QModbusPdu::ReportServerId 功能代码用作附加信息。 |
| QModbusServer::AdditionalData | 返回服务器的附加数据。该数据用作QModbusPdu::ReportServerId 功能代码的补充信息。 |
| QModbusServer::DeviceIdentification | 返回服务器的物理和功能描述。 |
| QModbusServer::UserOption | 返回用户选项的值。 注意：对于 用户选项，应由开发人员决定使用哪些类型，并确保组件在访问和设置值时使用正确的类型。 |
另请参阅 setValue()。
[virtual protected] bool QModbusServer::writeData(const QModbusDataUnit &newData)
将newData 写入Modbus服务器映射。成功时返回true ，若newData 的范围超出映射范围或registerType()不存在，则返回false 。
注意：若子类 实现了与默认值不同的后端存储写入功能，则也需实现setMap() 和readData() 方法。同时，还需在函数实现内部触发dataWritten() 信号。
另请参阅 setMap()、readData() 和dataWritten()。
© 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.
