Возможности · Установка · Быстрый старт · Документация · Для разработчиков · Поддержать

ModbusReader — настольная программа для наладки и мониторинга приборов по протоколу Modbus RTU (RS-485). Она показывает все регистры прибора с именами, единицами измерения и подписями значений, строит графики в реальном времени, позволяет собрать пульт из виджетов, автоматизировать проверки макросами и прослушивать линию сниффером. Если прибора под рукой нет, программа может сама выступить в роли прибора.

Программа бесплатна, распространяется с открытым исходным кодом, имеет русский и английский интерфейс и обновляется автоматически — с подтверждения пользователя. Это бесплатная альтернатива Modbus Poll и Modbus Slave: мастер, эмулятор прибора и сниффер RS-485 в одной программе. Руководство, основы Modbus и примеры — на сайте modbusreader.ru.

In English: ModbusReader is a free, open-source Modbus RTU master and slave simulator for Windows — read and write registers over RS-485, live trends, an HMI-style dashboard, a bus scanner, a sniffer and Python macros. A free alternative to Modbus Poll / Modbus Slave, with an English UI. Documentation · Download

_{Демо-проект «термоконтроллер»: значения с единицами и перечислениями, живые графики, журнал обмена с разбором каждого кадра}

Возможности

Карта регистров

Все регистры прибора в одной таблице — с именами, единицами и состоянием каждого. Значения обновляются при каждом цикле опроса; запись — двойным щелчком.

• 24 типа данных: SHORT, UINT16, LONG, UINT32, FLOAT, DOUBLE, INT64, BCD, битовые слова, строки, BOOL…; порядок байт настраивается для каждого типа.
• Все четыре области Modbus: holding- и input-регистры, coils и discrete inputs (чтение FC 01–04, запись FC 05 и 06; эмулятор принимает ещё 15 и 16).
• Масштаб и перечисления: «573 → 57.3 %», «1 → Работа» — в таблице, графиках, дашборде и логгере.
• Статистика линии в углу окна: запросы, ответы, таймауты, ошибки CRC, время ответа.

Графики в реальном времени Любой регистр — на график одним щелчком. Крупное текущее значение, изменение за окно, мин / макс / среднее, окна 10 с · 30 с · 2 мин · 10 мин. Если связь пропала, линия гаснет и показывает, сколько данных нет.

Дашборд

14 видов виджетов: значения, стрелочные приборы, полосы, лампы, битовые слова, графики, кнопки, тумблеры, ползунки, списки, поля ввода, таймеры, условия и надписи. Виджеты расставляются свободно, с выравниванием по соседям, а провода между ними дают простую автоматику: «таймер → кнопка → запись в прибор», а «условие» пропускает импульс, только когда значение, например, выше порога. Несколько экранов в одном проекте.

Инструменты

Консоль. Журнал обмена с разбором каждого кадра и отправка сырых кадров — CRC16 считается сам.	Сниффер. Слушает линию через второй адаптер, не передавая ни байта: кто кого спросил, что ответил, где сбой CRC.
Сканер. Находит приборы на линии по адресам или живые регистры на одном приборе.	Логгер. Многочасовая запись в CSV, который сразу открывается в Excel; новый файл по достижении размера.
Макросы. Скрипты на Python: читают и пишут регистры по именам, собирают таблицу результатов, сохраняют её в CSV / Excel.	Эмулятор (Slave). Программа отвечает мастеру как прибор — по открытой карте — для проверки SCADA или контроллера без реального прибора.
Снимки. «Что изменилось?» — снимок всех значений и сравнение с текущими, с разницей.	Редактор карты. Карта регистров с нуля или импорт из CSV / Excel; перетаскивание строк, отмена и повтор.
Наблюдение (F6). Плавающее окно с выбранными регистрами — видно с любого экрана, можно закрепить поверх всех окон.	Обновления. Программа сама узнаёт о новой версии, показывает, что нового, и ставит её только по вашему «Обновить».

Оформление

Тёмная и светлая темы, 7 цветовых схем, 12 акцентов, 3 уровня контраста, выбор шрифта и его размера — с живым предпросмотром прямо в окне.

Установка

Установщик всегда лежит по одной и той же ссылке — ModbusReader-Setup.exe; портативная версия — на странице Releases. Установленная программа сразу после запуска проверяет, нет ли версии новее, и предлагает обновиться.

Что нужно на компьютере: Windows 10 (версия 1809 и новее) или Windows 11, 64-битная. Python и все библиотеки уже внутри — ничего дополнительно ставить не нужно. Для работы с прибором — USB-адаптер RS-485 (его драйвер ставится отдельно, от производителя адаптера); интернет нужен только для обновлений.

	Установщик	Портативная версия
Файл	ModbusReader-Setup.exe	ModbusReader.exe
Куда	C:\Program Files (для всех пользователей) или только для себя	любая папка
Права администратора	для всех пользователей — да, только для себя — нет	не нужны
Ярлыки в «Пуске» и на рабочем столе	✓	—
.mbproj открывается двойным щелчком	✓	—
Удаление	через «Приложения»	удалением файла
Где настройки	%APPDATA%\ModbusReader	рядом с exe
Автообновление	✓	✓

Windows может предупредить «Система Windows защитила ваш компьютер» — программа пока не подписана платным сертификатом. Нажмите «Подробнее» → «Выполнить в любом случае». Это нужно только при первой установке: обновления программа скачивает сама.

Linux и macOS

Сборки лежат на той же странице Releases. О новой версии программа сообщает сама и открывает страницу выпуска; скачивать её нужно вручную.

Linux — ModbusReader-x86_64.AppImage, один файл, 64-битная система с glibc 2.35 и новее (Ubuntu 22.04+, Debian 12+, Fedora 36+ и т. п.):

chmod +x ModbusReader-x86_64.AppImage && ./ModbusReader-x86_64.AppImage

Чтобы программа видела последовательные порты (/dev/ttyUSB0, /dev/ttyACM0), пользователь должен состоять в группе dialout — один раз, затем перезайти в систему:

sudo usermod -aG dialout $USER

Если при запуске Qt пишет про платформу xcb, не хватает пакета libxcb-cursor0 (Debian/Ubuntu) или xcb-util-cursor (Fedora, Arch). Настройки хранятся в ~/.config/ModbusReader.

macOS — ModbusReader-macOS-arm64.zip, компьютеры на Apple Silicon (M1 и новее), macOS 12+. Распакуйте и перенесите ModbusReader.app в «Программы». Сборка не заверена Apple (это платно), поэтому первый запуск macOS заблокирует: откройте «Системные настройки» → «Конфиденциальность и безопасность» и нажмите «Всё равно открыть». Если macOS пишет, что программа «повреждена», снимите карантин:

xattr -dr com.apple.quarantine /Applications/ModbusReader.app

Порты адаптеров выглядят как /dev/cu.usbserial-…. Настройки хранятся в ~/Library/Application Support/ModbusReader.

Быстрый старт

1. Установите и запустите. При первом запуске сразу откроется демо-проект — термоконтроллер с картой регистров и готовым пультом. Вернуться к нему можно кнопкой «Демо-проект» на пустом экране карты.
2. Своя карта регистров: «Открыть карту», импорт из CSV / Excel или «Создать карту» в редакторе.
3. Подключение: щёлкните по параметрам связи в шапке (порт, скорость, чётность, адрес прибора) и нажмите «Подключить».
4. Работа с регистрами: правый щелчок по регистру — на график или в наблюдение, двойной щелчок по «Новому значению» — запись; инструменты — в панели слева, горячие клавиши — в «Настройки → Горячие клавиши».

Проект (.mbproj) хранит подключение, карту и все дашборды вместе — один файл на объект.

Для разработчиков

Запуск из исходников

Нужен Python 3.10+ (разработка ведётся на 3.12).

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python main.py

Linux / macOS: те же шаги (source .venv/bin/activate, python main.py). На Linux пользователь должен состоять в группе dialout для доступа к последовательным портам.

Чтобы демо-карта «ожила» без прибора, запустите вторую копию программы в режиме «Эмулятор (Slave)» на парном виртуальном COM-порту (например, com0com).

Версии библиотек закреплены (requirements.txt): новая версия библиотеки может незаметно изменить поведение программы. Обновления раз в неделю предлагает Dependabot отдельным pull request, тесты проверяют их на Linux, и в сборку они попадают только после слияния. Сборка отказывается работать, если установленные версии отличаются от закреплённых.

Сборка exe и установщика

Нужен Inno Setup 6; PyInstaller и pytest — из requirements-dev.txt.

.venv\Scripts\pip install -r requirements-dev.txt
.venv\Scripts\python tools/build_installer.py --portable   # установщик + оба exe

tools/build_installer.py собирает программу папкой (ModbusReader_setup.spec), упаковывает её Inno Setup'ом (installer/ModbusReader.iss) в dist/ModbusReader-Setup.exe, а с --portable — ещё и одиночные ModbusReader.exe / ModbusReader_debug.exe (с консолью). Сведения о версии exe берутся из app/version.py; иконка и заставка — tools/make_icon.py, tools/make_splash.py.

Версии и выпуски

Версии календарные — ГГ.ММ.N: 26.10.0 — первый выпуск октября 2026 года, 26.10.1 — следующий в том же месяце. python tools/release.py вычисляет номер, записывает его в app/version.py и превращает раздел «Не выпущено» в CHANGELOG в раздел выпуска со ссылкой на него.

В репозитории один выпуск — всегда последний: новая версия заменяет в нём файлы ModbusReader-Setup.exe, ModbusReader.exe и ModbusReader_debug.exe и переносит его на свой тег vX.Y.Z (не pre-release). Теги всех версий остаются в истории, а выпуск — один. Скачанное программа сверяет с SHA-256, который GitHub считает при загрузке файла.

Картинки этого README — python tools/readme_shots.py: они рисуются из демо-проекта, а не с реального прибора.

Тесты

.venv\Scripts\python -m pytest

Около 900 тестов, полностью без экрана (QT_QPA_PLATFORM=offscreen ставится автоматически). Тесты никогда не читают и не пишут ваш настоящий app_settings.json.

Файлы, которые пишет программа

• app_settings.json — у установленной программы в %APPDATA%\ModbusReader; у портативной — рядом с exe (если папка только для чтения — тоже в %APPDATA%). Запись атомарная, с копией .bak и восстановлением при повреждении.
• modbusreader_errors.log — там же: трассировки непойманных ошибок.
• Скачанные обновления — %LOCALAPPDATA%\ModbusReader\updates; удаляются после установки.
• Копия демо-проекта — Документы\ModbusReader.

Устройство кода

main.py        точка входа
app/           настройки, тексты (RU/EN), команды, версия, пути
core/          Modbus и потоки, типы данных, форматы файлов, движки сканера,
               сниффера, эмулятора и макросов, модель дашборда, обновления
gui/           окно и всё на нём: страницы, диалоги, таблица, дашборд, графики, темы
tests/         тесты (pytest, без экрана)
tools/         сборка, выпуск, картинки README, демо-проект
installer/     установщик (Inno Setup)
examples/      демо-проект

ARCHITECTURE.md — карта модулей, стиль Descriptor+Registry, потоковая модель (COM-портом владеет один поток ModbusCore). История изменений — CHANGELOG.md.

Поддержать проект

ModbusReader бесплатен и таким останется. Если программа экономит вам время — можно поддержать разработку:

Не меньше помогают отзывы, сообщения об ошибках, предложения и карты регистров приборов — через Issues; вопросы по работе с программой — в Discussions. О найденных уязвимостях сообщайте по правилам SECURITY.md.

Лицензия

ModbusReader — свободная программа: её можно использовать (в том числе в работе), изучать, изменять и распространять на условиях GNU GPL версии 3 или (по вашему выбору) любой более поздней версии. Изменённые версии, которые вы распространяете, тоже должны быть открыты под GPL. Программа предоставляется без каких-либо гарантий. Лицензии сторонних компонентов — в THIRD_PARTY_LICENSES.md.

Текст уведомления

ModbusReader — Modbus RTU commissioning and monitoring
Copyright (C) 2026 Mercurrial

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.