Comando personalizado de Modbus
El ejemplo muestra cómo gestionar los códigos de función Modbus personalizados.
El ejemplo actúa tanto como cliente como servidor Modbus en una única aplicación. La conexión entre ambos se establece a través de Modbus TCP. Se utiliza para enviar y recibir solicitudes Modbus personalizadas y ajusta sus estados internos en función de la solicitud y la respuesta.
El objetivo principal del ejemplo es proporcionar código de demostración sobre cómo implementar un cliente o un servidor Modbus que gestione códigos de función Modbus personalizados.

Códigos de función Modbus definidos por el usuario
El protocolo Modbus admite códigos de función en los rangos 1 - 127 (0x01 - 0x7F HEX). La mayoría de los códigos de función están bien definidos y documentados públicamente. Sin embargo, hay dos rangos que pueden utilizarse para funciones definidas por el usuario. Estos son 65 - 72 (0x41 - 48 HEX) y 100 - 110 (0x64 - 0x6E HEX). El usuario puede seleccionar códigos de función de estos rangos y gestionarlos de forma personalizada.
Esta aplicación utiliza el código de función 65 (0x41 HEX) para implementar el comando CustomRead y el código de función 66 (0x42 HEX) para implementar el comando CustomWrite. En este ejemplo, los comandos personalizados se utilizan simplemente para leer y escribir en la Holding Registers.
Envío de comandos Modbus personalizados
Los comandos Modbus personalizados se envían mediante el método QModbusClient::sendRawRequest(). Este método requiere generar un objeto QModbusRequest con el código de función deseado y una lista de argumentos que se codificarán en un QByteArray:
QModbusDataUnit unit {
QModbusDataUnit::HoldingRegisters,
ui->startAddress->value(),
qMin(ui->numberOfRegisters->currentText().toUShort(),
quint16(10 - ui->startAddress->value())) // no superar las 10 entradas
};
for (qsizetype i = 0, total = unit.valueCount(); i < total;++i)
unit.setValue(i, m_model->m_registers[i + unit.startAddress()]);
const quint8 byteCount = quint8(unit.valueCount() * 2);
QModbusRequest writeRequest {
QModbusPdu::FunctionCode(ModbusClient::CustomWrite),
quint16(unit.startAddress()),
quint16(unit.valueCount()), byteCount, unit.values()
};El método QModbusClient::sendRawRequest() devuelve un objeto ` QModbusReply ` que se puede utilizar para comprobar si hay errores, como de costumbre:
if (auto *reply = m_client.sendRawRequest(writeRequest, ui->serverAddress->value())) {
if (!reply->isFinished()) {
connect(reply, &QModbusReply::finished, this, [this, reply]() {
if (reply->error() == QModbusDevice::ProtocolError) {
statusBar()->showMessage(tr("Write response error: %1 (Modbus exception: 0x%2)")
.arg(reply->errorString()).arg(reply->rawResult().exceptionCode(), -1, 16),
5000);
} else if (reply->error() != QModbusDevice::NoError) {
statusBar()->showMessage(tr("Write response error: %1 (code: 0x%2)").
arg(reply->errorString()).arg(reply->error(), -1, 16), 5000);
}
reply->deleteLater();
}
);
}
} else {
statusBar()->showMessage(tr("Write error: ") + m_client.errorString(), 5000);
}Servidor Modbus personalizado
El servidor personalizado se deriva de la clase ` QModbusTcpServer `. Sobrescribe el método ` QModbusServer::processPrivateRequest()`.
class ModbusServer : public QModbusTcpServer
{
Q_OBJECT
Q_DISABLE_COPY_MOVE(ModbusServer)
public:
ModbusServer(QObject *parent = nullptr);
private:
QModbusResponse processPrivateRequest(const QModbusPdu &request) override;
};La clase base del servidor llama al método processPrivateRequest() cuando se recibe un comando con un código de función personalizado.
La implementación personalizada gestiona el comando « CustomRead » generando un « QModbusResponse » con los valores de los registros solicitados:
if (ModbusClient::CustomRead == request.functionCode()) {
quint16 startAddress, count;
request.decodeData(&startAddress, &count);
QModbusDataUnit unit(QModbusDataUnit::HoldingRegisters, startAddress, count);
if (!data(&unit)) {
return QModbusExceptionResponse(request.functionCode(),
QModbusExceptionResponse::IllegalDataAddress);
}
return QModbusResponse(request.functionCode(), startAddress, quint8(count * 2), unit.values());
}La gestión del comando « CustomWrite » incluye extraer los nuevos valores del « QModbusPdu » recibido, realizar la actualización real de los valores y devolver un « QModbusResponse » con los registros que se han actualizado realmente:
if (ModbusClient::CustomWrite == request.functionCode()) {
quint8 byteCount;
quint16 startAddress, numberOfRegisters;
request.decodeData(&startAddress, &numberOfRegisters, &byteCount);
if (byteCount % 2 != 0) {
return QModbusExceptionResponse(request.functionCode(),
QModbusExceptionResponse::IllegalDataValue);
}
const QByteArray pduData = request.data().remove(0, WriteHeaderSize);
QDataStream stream(pduData);
QList<quint16> values;
for (int i = 0; i < numberOfRegisters; i++) {
quint16 tmp;
stream >> tmp;
values.append(tmp);
}
if (!writeData({QModbusDataUnit::HoldingRegisters, startAddress, values})) {
return QModbusExceptionResponse(request.functionCode(),
QModbusExceptionResponse::ServerDeviceFailure);
}
return QModbusResponse(request.functionCode(), startAddress, numberOfRegisters);
}Cliente Modbus personalizado
El cliente personalizado deriva de la clase ` QModbusTcpClient `. Sobrescribe el método ` QModbusClient::processPrivateResponse()`.
class ModbusClient : public QModbusTcpClient
{
Q_OBJECT
Q_DISABLE_COPY_MOVE(ModbusClient)
public:
ModbusClient(QObject *parent = nullptr);
static constexpr QModbusPdu::FunctionCode CustomRead {QModbusPdu::FunctionCode(0x41)};
static constexpr QModbusPdu::FunctionCode CustomWrite {QModbusPdu::FunctionCode(0x42)};
private:
bool processPrivateResponse(const QModbusResponse &response, QModbusDataUnit *data) override;
};La clase cliente base llama al método processPrivateResponse() para procesar las respuestas del servidor con códigos de función personalizados.
La implementación personalizada gestiona las respuestas con los códigos de función CustomRead y CustomWrite:
bool ModbusClient::processPrivateResponse(const QModbusResponse &response, QModbusDataUnit *data)
{
if (!response.isValid())
return QModbusClient::processPrivateResponse(response, data);
if (CustomRead == response.functionCode())
return collateBytes(response, data);
if (CustomWrite == response.functionCode())
return collateMultipleValues(response, data);
return QModbusClient::processPrivateResponse(response, data);
}La respuesta CustomRead se gestiona descodificando el QModbusPdu facilitado y extrayendo los valores de los registros solicitados:
static bool collateBytes(const QModbusPdu &response, QModbusDataUnit *data)
{
if (response.dataSize() < MinimumReadResponseSize)
return false;
quint16 address; quint8 byteCount;
response.decodeData(&address, &byteCount);
if (byteCount % 2 != 0)
return false;
if (data) {
QDataStream stream(response.data().remove(0, 3));
QList<quint16> values;
const quint8 itemCount = byteCount / 2;
for (int i = 0; i < itemCount; i++) {
quint16 tmp;
stream >> tmp;
values.append(tmp);
}
*data = {QModbusDataUnit::HoldingRegisters, address, values};
}
return true;
}La respuesta « CustomWrite » se gestiona simplemente validando los parámetros de la respuesta:
static bool collateMultipleValues(const QModbusPdu &response, QModbusDataUnit *data)
{
if (response.dataSize() != WriteResponseSize)
return false;
quint16 address, count;
response.decodeData(&address, &count);
if (count < 1 || count > 10)
return false;
if (data)
*data = {QModbusDataUnit::HoldingRegisters, address, count};
return true;
}Ejecución del ejemplo
Puedes ejecutar el ejemplo desde:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en Examples. Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecuta el comando « Qt: Open Qt examples » desde Command Palette y selecciona el ejemplo de la lista. Para obtener más información, consulta Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
Este ejemplo no se puede utilizar junto con otras aplicaciones. Una vez iniciado el ejemplo, solo puede intercambiar comandos Modbus personalizados dentro de la propia aplicación. Todas las interacciones entre el cliente y el servidor utilizan el protocolo Modbus TCP.
© 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.