This is a real scenario from qtcentre.org (thread 61749, “QT and Libmodbus”): a developer read QModMaster’s source code and wanted to build their own Qt GUI Modbus master application on top of libmodbus — targeting a Raspberry Pi. This page sketches the same architecture QModMaster uses, with a minimal but complete example: connect, read holding registers, and deliver the values to the GUI thread.

The architecture: GUI thread + blocking worker

libmodbus calls such as modbus_read_registers() are synchronous — they block until the reply arrives or the timeout fires. QModMaster-style applications therefore do all Modbus I/O in a worker thread and push results to the GUI through signals and slots. The one rule that matters: never call libmodbus from the GUI thread, or your interface will freeze on every poll.

Minimal example: connect → read → emit

One file, Qt5, C++17. The poller lives in a QThread; a QTimer in that same thread triggers each poll; results travel back via signals:

// Build with:  QT += widgets   and   LIBS += -lmodbus
// Debian / Raspberry Pi OS:  sudo apt install qtbase5-dev libmodbus-dev

#include <QCoreApplication>
#include <QThread>
#include <QTimer>
#include <QVector>
#include <QDebug>
#include <cerrno>
#include <modbus/modbus.h>

class ModbusPoller : public QObject {
    Q_OBJECT
public:
    explicit ModbusPoller(QObject *parent = nullptr) : QObject(parent) {}
    ~ModbusPoller() override {
        if (ctx) { modbus_close(ctx); modbus_free(ctx); }
    }

    bool openRtu(const char *device, int slaveId) {
        ctx = modbus_new_rtu(device, 9600, 'N', 8, 1);
        if (!ctx) return false;
        modbus_set_slave(ctx, slaveId);
        struct timeval timeout{2, 0};               // 2 s response timeout
        modbus_set_response_timeout(ctx, &timeout);
        if (modbus_connect(ctx) == -1) {
            qWarning() << "connect failed:" << modbus_strerror(errno);
            modbus_free(ctx);
            ctx = nullptr;
            return false;
        }
        return true;
    }

public slots:
    void poll() {                                   // runs in the worker thread
        uint16_t regs[10] = {};
        int rc = modbus_read_registers(ctx, 0, 10, regs); // 0-based PDU address
        if (rc == -1) {
            emit failed(QString::fromUtf8(modbus_strerror(errno)));
            return;
        }
        QVector<quint16> out;
        out.reserve(rc);
        for (int i = 0; i < rc; ++i) out.append(regs[i]);
        emit valuesReady(out);
    }

signals:
    void valuesReady(const QVector<quint16> &values);
    void failed(const QString &message);

private:
    modbus_t *ctx = nullptr;
};

int main(int argc, char *argv[]) {
    QCoreApplication app(argc, argv);

    auto *thread = new QThread;
    auto *poller = new ModbusPoller;
    poller->moveToThread(thread);

    auto *timer = new QTimer;          // no parent yet: move it before wiring
    timer->setInterval(1000);
    timer->moveToThread(thread);

    QObject::connect(thread, &QThread::started, [=]() {
        if (!poller->openRtu("/dev/ttyUSB0", 1)) {
            qWarning() << "could not open Modbus link";
            app.quit();
        }
    });
    QObject::connect(timer, &QTimer::timeout, poller, &ModbusPoller::poll);
    QObject::connect(thread, &QThread::started,
                     timer, static_cast<void (QTimer::*)()>(&QTimer::start));
    QObject::connect(poller, &ModbusPoller::valuesReady,
                     [](const QVector<quint16> &v) { qDebug() << "registers:" << v; });
    QObject::connect(poller, &ModbusPoller::failed,
                     [](const QString &m) { qWarning() << "poll failed:" << m; });
    QObject::connect(&app, &QCoreApplication::aboutToQuit, thread, &QThread::quit);
    QObject::connect(thread, &QThread::finished, poller, &QObject::deleteLater);
    QObject::connect(thread, &QThread::finished, timer, &QObject::deleteLater);
    QObject::connect(thread, &QThread::finished, thread, &QObject::deleteLater);

    thread->start();
    return app.exec();
}

// If everything lives in one .cpp file, add at the end:
// #include "main.moc"

For a TCP device instead of serial, swap modbus_new_rtu() for modbus_new_tcp("192.168.1.100", 502) — everything else stays identical.

Build notes

• Debian / Raspberry Pi OS / Ubuntu: sudo apt install qtbase5-dev libmodbus-dev
• .pro file: add QT += widgets and LIBS += -lmodbus
• Qt6: the same code works; install the Qt6 base dev package instead of qtbase5-dev and adjust the QT += line for your Qt6 setup
• Windows: build libmodbus first (see the libmodbus documentation), then link your Qt project against it the same way

Gotchas QModMaster already solved for you

• Timeouts: always set a response timeout (modbus_set_response_timeout) — without one, a dead slave hangs your worker thread.
• Slave ID: call modbus_set_slave() before modbus_connect(); the default unit ID is not always what your device expects.
• Address base: libmodbus uses 0-based PDU addresses — the “40001” in a device manual is address 0 here. See our register address offset guide for the full story.
• Error messages: modbus_strerror(errno) turns a failed call into a human-readable reason — log it, don’t swallow it.

Related Guides

• pymodbus vs QModMaster: Script or GUI?
• QModMaster vs mbpoll: GUI or Command Line?
• Modbus Register Address Offset Guide
• Download QModMaster

A Raspberry Pi makes an excellent always-on Modbus test station: it is cheap, silent, sips power, and runs a Debian-based Linux — which means the same source-build process as Ubuntu works here. Point it at PLCs, energy meters, and sensors over the network with Modbus TCP, or hang a USB-to-RS485 adapter off it for Modbus RTU. This guide covers the full setup: OS preparation, dependencies, compilation, both connection modes, and headless-operation tips.

Why a Pi Makes a Good Modbus Test Station

Field engineers and hobbyists often need a device that polls Modbus registers around the clock — for logging, for commissioning checks, or just to verify a new sensor talks before it goes into a panel. A Pi running QModMaster does this for a fraction of the cost of a laptop, and its GPIO/UART and USB ports give you both network and serial paths to your devices. QModMaster’s Scan feature (automatic register polling) is particularly handy here.

Step 1: Prepare the System

Start with a current Raspberry Pi OS (64-bit recommended), fully updated. Raspberry Pi OS is Debian-based, so the familiar apt workflow applies:

sudo apt update && sudo apt full-upgrade -y
sudo reboot

Step 2: Install Dependencies and Build

Install the compiler toolchain and the Qt 5 development packages QModMaster requires:

sudo apt install build-essential qtbase5-dev qt5-qmake libqt5serialport5-dev git

Package names may vary slightly by distro version — if apt cannot find one of these, run apt search qt5 and select the matching development package. Then fetch the stable source and build it, exactly as on Ubuntu/Debian:

cd ~
wget https://sourceforge.net/projects/qmodmaster/files/qmodmaster/qModMaster-code-0.5.2-3.zip/download -O qmodmaster-src.zip
unzip qmodmaster-src.zip
cd qmodmaster
qmake qmodmaster.pro
make -j$(nproc)

On a Pi 4 or Pi 5 the build takes a few minutes; on older models, be patient. When make finishes you get a qmodmaster binary you can launch with ./qmodmaster. See our full Ubuntu/Debian build guide for dependency details and common build-error fixes.

Mode 1: Modbus TCP Over the Network

The simplest deployment: the Pi sits on your LAN (wired Ethernet preferred for reliability) and QModMaster talks Modbus TCP directly to PLCs, drives, and gateways. In QModMaster, select Modbus TCP, enter the device’s IP address and port (default 502), set the unit ID, and start reading holding registers (function code 03) or input registers (04). Use the Scan feature to poll a register block continuously for logging or commissioning checks. Give the Pi a static IP or DHCP reservation so your test setup survives reboots.

Mode 2: Modbus RTU via USB-to-RS485 Adapter

For serial devices, plug a USB-to-RS485 adapter into the Pi and select the RTU interface in QModMaster. As on desktop Linux, your user needs serial-port access:

sudo usermod -aG dialout $USER
# log out and back in, then check:
ls /dev/ttyUSB*

Match the baud rate, parity, data bits, and stop bits to your device (9600 8-N-1 is the usual starting point), enable RTS control if your adapter needs it, and try reading a known register. If the port does not appear, check dmesg for the adapter’s USB enumeration — some adapters draw more current than the Pi’s USB ports comfortably supply, in which case a powered hub helps.

Running Headless: VNC and SSH Tips

QModMaster is a graphical Qt application, so on a headless Pi you need a display path. The easiest is VNC (enable it in raspi-config under Interface Options, then connect from your laptop and launch ./qmodmaster in the remote desktop). Alternatively, SSH with X forwarding (ssh -X pi@your-pi) can run the GUI on your local screen — workable over a fast LAN, sluggish over Wi-Fi. These are general remote-desktop approaches; pick whichever fits your network.

Frequently Asked Questions

Which Raspberry Pi models can run QModMaster?

Any Pi that runs a current Raspberry Pi OS with Qt 5 available should be able to build it — a Pi 4 or Pi 5 gives the smoothest experience. We have not tested every model, so treat very old boards (Pi Zero, Pi 1) as untested territory: the build may be slow but should still work in principle.

Is the Pi fast enough for Modbus polling?

Easily. Modbus RTU at 9600–115200 baud and Modbus TCP polling are trivial workloads; the Pi’s bottleneck, if any, is compiling Qt code (a one-time cost), not running QModMaster. Continuous Scan polling runs for days without breaking a sweat.

My USB-RS485 adapter isn’t detected on the Pi. What now?

First check dmesg | tail after plugging it in — you should see a new /dev/ttyUSB0. If nothing appears, the adapter may be underpowered: try a powered USB hub. If the device node exists but QModMaster can’t open it, confirm your user is in the dialout group and you have logged out and back in.

Can the Pi run QModMaster 24/7 as a logger?

The hardware can, but QModMaster itself is an interactive GUI tool, not a headless logging daemon — it is best suited to commissioning, testing, and interactive polling sessions via VNC. For unattended 24/7 data logging, pair it with (or graduate to) a script-based Modbus client; use the Pi + QModMaster combination for everything where you want to see the registers live.

Related Guides

• Install QModMaster on Ubuntu/Debian (Build from Source)
• QModMaster Tutorial: Your First Modbus Request
• USB-to-RS485 Adapter Buying Guide
• Download QModMaster

Option 1: Run the Windows Version in a Virtual Machine (Recommended)

The most dependable route is also the simplest: install a Windows VM and run the official Windows build of QModMaster inside it. On Apple Silicon Macs, UTM (free, open source) runs Windows 11 on ARM well; on Intel Macs you can also use Parallels Desktop or other VM software. Download the portable QModMaster .zip from our download page, unzip it in the VM, and it just works — no installation needed.

If you need Modbus RTU through a USB-to-RS485 adapter, the key step is USB passthrough: attach the adapter to the VM (in UTM this is done under the VM’s USB device settings) so Windows sees it as a COM port. Modbus TCP needs no passthrough at all — the VM shares your Mac’s network, so just point QModMaster at the device’s IP address. See our USB-to-RS485 adapter recommendations if you still need hardware.

Option 2: Wine or CrossOver

QModMaster is a fairly simple Qt application, so in principle it should run under Wine (or the commercial CrossOver). In practice, serial-port handling under Wine can be flaky: USB-to-RS485 adapters may not map cleanly to Wine’s virtual COM ports, and behavior varies between Wine versions. Treat this as a “try it and see” option for Modbus TCP — it may work for you, but it is not guaranteed, and we have not verified a stable Wine setup ourselves.

Option 3: Compile the Source on Your Mac

Because QModMaster is open source (LGPLv3) and Qt-based, building it natively on macOS is theoretically possible: install Qt 5 (for example via Homebrew’s qt@5), then run qmake && make against the source from SourceForge. We have not verified this ourselves — Qt 5 on recent macOS versions (especially Apple Silicon) can be troublesome, and the upstream project never tested a Mac build. Consider this a project for experienced users, not a supported path.

Option 4: Use a Native macOS Modbus Tool

If you need a tool that simply works on a Mac today, the pragmatic move is to search for a native macOS Modbus master application instead of forcing QModMaster into an environment it was never built for. Look for tools that explicitly advertise macOS support and cover the features you need (RTU over USB adapters, TCP, and the function codes your devices use). A VM running QModMaster remains the closest experience if you specifically want QModMaster’s interface.

What We Don’t Recommend

Do not install a Hackintosh or patch macOS to run Windows-only software — the maintenance cost dwarfs any benefit for a free utility. Likewise, avoid random “QModMaster Mac cracked .dmg” downloads from file-sharing sites; there is no legitimate macOS build to crack, so those files are at best mislabeled and at worst malware.

Frequently Asked Questions

Is there a QModMaster.dmg for Mac?

No. The upstream project never released a macOS build — only a Windows portable .zip and source code. Any .dmg claiming to be QModMaster is unofficial and should be treated with suspicion.

Can I run the Windows QModMaster .exe on a Mac?

Yes — inside a Windows virtual machine (UTM or Parallels are the common choices), where the official Windows build runs normally. Wine or CrossOver may also work, but that path is not guaranteed, especially for USB serial adapters.

Will my USB-to-RS485 adapter work in a VM?

Usually, yes: attach the adapter to the VM via USB passthrough and Windows will enumerate it as a COM port that QModMaster can open. We have not tested every adapter, so if RTU is mission-critical, verify with your specific hardware before depending on it.

Does Wine run QModMaster reliably?

We have not verified a stable Wine configuration ourselves. Modbus TCP is more likely to work than RTU over USB adapters, since serial-port mapping under Wine is the fragile part. If reliability matters, use a VM instead.

Related Guides

• Install QModMaster on Ubuntu/Debian (Build from Source)
• QModMaster Tutorial: Your First Modbus Request
• QModMaster User Manual (Function Codes & Reference)
• Download QModMaster

QModMaster runs fine on Linux — it is written in Qt, after all — but there is no official .deb package, no PPA, and no Flatpak. On Ubuntu and Debian you install it by compiling the source yourself. The whole process takes about ten minutes once the dependencies are in place, and this guide walks you through every step: dependencies, source code, the qmake && make build, and the one serial-port permission gotcha that trips up almost everyone.

Why There Is No .deb Package

The upstream QModMaster project publishes only two things: a portable Windows .zip and the source code (via SourceForge). The project never shipped Linux binaries or distribution packages, so any .deb you find elsewhere is either unofficial or outdated. Building from source also guarantees you get the current stable release — v0.5.2 — rather than whatever happens to sit in a third-party repo.

Step 1: Install the Build Dependencies

Open a terminal and install the compiler toolchain plus the Qt 5 development packages QModMaster needs (notably QtSerialPort, which is not part of the default Qt install):

sudo apt update
sudo apt install build-essential qtbase5-dev qt5-qmake libqt5serialport5-dev git

Package names may vary slightly by distro version — on older releases the meta-package may be called qt5-default, and on Debian derivatives the same names above generally apply. If apt reports that a package has no installation candidate, search for it with apt search qt5 and pick the matching development package.

Step 2: Get the Source Code

Download the stable source archive from the official SourceForge files page — the file you want is qModMaster-code-0.5.2-3.zip:

mkdir -p ~/src && cd ~/src
wget https://sourceforge.net/projects/qmodmaster/files/qmodmaster/qModMaster-code-0.5.2-3.zip/download -O qmodmaster-src.zip
unzip qmodmaster-src.zip
cd qmodmaster

Alternatively, grab the code with Git if you prefer to track upstream changes:

git clone https://git.code.sf.net/p/qmodmaster/code qmodmaster
cd qmodmaster

Step 3: Build with qmake and make

QModMaster is a classic Qt .pro project, so the build is the standard two-command sequence:

qmake qmodmaster.pro
make -j$(nproc)

The -j$(nproc) flag just uses all your CPU cores to speed up compilation. When make finishes without errors you will find a fresh qmodmaster binary in the build directory.

Step 4: Run QModMaster

./qmodmaster

The main window should open and show the Modbus request grid and the Bus Monitor. For a quick smoke test, switch the interface to Modbus TCP, point it at a test device (or a local Modbus slave simulator), and try reading holding registers with function code 03. If you plan to use it regularly, create a desktop shortcut or a .desktop launcher pointing at the binary.

Step 5: Fix Serial Port Permissions (RTU Users)

If you use Modbus RTU over a USB-to-RS485 adapter, Linux will normally deny QModMaster access to /dev/ttyUSB0 with a permission error. The fix is to add your user to the dialout group:

sudo usermod -aG dialout $USER

Log out and back in (or reboot) for the group change to take effect, then confirm with groups. After that, the serial port appears in QModMaster’s port drop-down without needing sudo — do not run QModMaster as root, it is unnecessary and bad practice.

Common Build Errors and Fixes

“Project ERROR: Unknown module(s) in QT: serialport” — the QtSerialPort development files are missing. Install libqt5serialport5-dev and re-run qmake.

“qmake: command not found” — the Qt build tools are not installed or not on your PATH. Install qt5-qmake (and qtbase5-dev), then open a fresh terminal.

“cannot find -lGL” during linking — a common Qt build issue when the OpenGL development files are missing. Install libgl1-mesa-dev and run make again. These are generic Qt build problems, not QModMaster bugs, and the fixes above cover the vast majority of cases.

Frequently Asked Questions

Is QModMaster available for Linux?

Yes, but only as source code — there is no official .deb, RPM, or Flatpak. Compile it yourself with qmake && make following the steps above and you get the full stable release (v0.5.2) with RTU, TCP, Bus Monitor, and all supported function codes.

Which Qt version does QModMaster need to build?

QModMaster is a Qt 5 project, so install the Qt 5 development packages (qtbase5-dev, qt5-qmake, libqt5serialport5-dev). Package names may vary slightly by distro version; if you only have Qt 6 available, expect build issues, since the project predates Qt 6.

Why does QModMaster report “permission denied” on /dev/ttyUSB0?

Your user is not in the dialout group, which owns serial devices on Ubuntu/Debian. Run sudo usermod -aG dialout $USER, log out and back in, and the port will open without root privileges.

Can I build QModMaster on Fedora, Arch, or other distros?

The same source code builds on any distro with Qt 5 — only the dependency package names change (for example qt5-qtbase-devel and qt5-qtserialport-devel on Fedora-style systems). The qmake && make steps and the dialout-group permission fix apply everywhere.

Related Guides

• QModMaster Tutorial: Your First Modbus Request
• QModMaster User Manual (Function Codes & Reference)
• USB-to-RS485 Adapter Buying Guide
• Download QModMaster