GuiRNG

Аннотация

GuiRNG - набор настольных приложений для работы с USB-модулем аппаратного генератора случайных чисел. Репозиторий содержит две Qt GUI-программы, общую библиотеку вспомогательных компонентов UnderKit, обёртку над libusb и служебный консольный пример для перечисления доступных устройств.

Содержание

1. Общие сведения
2. Функциональное назначение
3. Описание логической структуры
4. Используемые технические средства
5. Вызов и загрузка
6. Входные данные
7. Выходные данные

1. Общие сведения

Наименование программы: GuiRNG.

Обозначение проекта: репозиторий сборки и исходных текстов для приложений GuiRng и GuiRngBlocks.

Языки реализации:

• C++14 для основной логики, GUI и USB-обмена.
• Python для формирования версии и конфигурации пакета Conan.
• CMake для описания сборки.

Для функционирования проекта используются:

• Qt 5.15.16 (Widgets, PrintSupport).
• libusb 1.0.24.
• Boost 1.84.0.
• fmt 8.0.1.
• spdlog 1.9.2.
• Conan 2 как рекомендуемый способ поставки зависимостей.

Результатом сборки являются:

• GuiRng - основное GUI для получения выборки, анализа распределений и сохранения результатов.
• GuiRngBlocks - GUI для многоблочного статистического контроля.
• Тестовая консольная утилита из main.cpp, выводящая список USB-устройств.

2. Функциональное назначение

Программный комплекс предназначен для подключения к совместимому RNG-устройству по USB, управления режимами его работы, получения потока случайных данных и визуального контроля статистических характеристик.

Основные функции GuiRng:

• Выбор USB-устройства через стартовый диалог.
• Чтение сведений о модуле и отображение служебных параметров.
• Переключение режимов работы: MODE_WORK_FREQ, MODE_HIGH_FREQ, MODE_ASYNCHRO, MODE_TEST.
• Переключение источника потока: RANDOM или INTERVALS.
• Получение заданного числа байт из RNG-потока.
• Построение гистограммы и логарифмического представления распределения.
• Расчёт количества нулей и единиц, отношения дисбаланса, статистики Sn, P-value для Frequency Test и Block Frequency Test.
• Линейная аппроксимация логарифма гистограммы.
• Сохранение сырых данных в файл .rng и гистограммы в файл .hist.

Основные функции GuiRngBlocks:

• Пакетное получение нескольких блоков данных одинакового размера.
• Расчёт статистик по каждому блоку и накопление агрегированных метрик.
• Построение графика delta по номеру блока.
• Построение распределения P-value по десяти интервалам.
• Расчёт интегральных значений для Frequency Test, Block Frequency Test и проверки P-from-P.

Функциональные ограничения:

• Приложения рассчитаны на конкретный протокол модуля RNG и не являются универсальным USB-анализатором.
• Работа без совместимого устройства практически ограничена стадией выбора USB-устройства и перечисления доступных модулей.
• Часть вспомогательных модулей UnderKit носит общий или исторический характер и не участвует в критическом пути текущих GUI-приложений.

3. Описание логической структуры

Логическая структура решения разделена на четыре уровня.

Уровень 1. Пользовательские приложения:

• GuiRng - выбор устройства, получение одной выборки, построение гистограммы, аппроксимация и сохранение результатов.
• GuiRngBlocks - поочерёдное получение серии блоков и накопление статистики по блокам.

Уровень 2. Предметный адаптер устройства:

• RngDev в каталогах GuiRng и GuiRngBlocks реализует прикладной протокол обмена с RNG-модулем.
• Адаптер кодирует команды чтения и записи, запускает и останавливает поток, читает служебные счётчики и гистограммы, а также получает поток байтов для дальнейшей обработки.

Уровень 3. Транспортный слой:

• libusb_wrapper инкапсулирует инициализацию libusb, поиск устройств, открытие дескриптора, проверку endpoint-ов и bulk transfer.
• На этом уровне приложение работает с USB-командами и буферами.

Уровень 4. Общая вспомогательная библиотека:

• UnderKit поставляет логирование, таймеры, базовые потоки, сигналы, простые математические аппроксимации и набор служебных утилит.

UnderKit

Компоненты UnderKit:

• quanlogger.* - обёртка над spdlog; используется при старте приложений, в USB-слое и в адаптере RngDev.
• times.hpp - простой секундомер в миллисекундах; применяется для оценки времени чтения потока и вычисления скорости.
• linearfit.* - линейная аппроксимация методом наименьших квадратов; используется в GuiRng при выравнивании логарифма гистограммы.

Особенности прикладной логики

GuiRng и GuiRngBlocks используют общий принцип старта:

• Приложение создаёт WelcomeDialog.
• Пользователь выбирает USB-устройство.
• libusb_wrapper открывает устройство.
• RngDev проверяет обязательные endpoint-ы и начинает обмен командами.
• Главное окно выполняет периодический опрос устройства таймером QTimer.

В GuiRng основная асинхронность реализована через WaitThread, который ожидает завершения фоновой операции получения выборки и обновляет прогресс-бар. В GuiRngBlocks используется собственный ExecThread на базе QThread, который поочерёдно читает несколько блоков и после каждого блока отправляет промежуточные статистики в GUI.

4. Используемые технические средства

Для штатной работы требуются:

• Персональный компьютер с поддерживаемой версией Qt 5.
• Совместимое USB-устройство RNG с ожидаемым протоколом команд.
• Компилятор с поддержкой C++14.
• CMake 3.16 или выше.
• Conan 2 для разрешения внешних зависимостей.

Особенности платформенной конфигурации:

• Корневой CMakeLists.txt не содержит локальных macOS-путей и пригоден для публикации в удалённый репозиторий.
• Для Windows предусмотрен профиль conan/profiles/windows и подключение QWindowsIntegrationPlugin.
• На Unix-подобных системах дополнительно линкуется pthread.

5. Вызов и загрузка

Рекомендуемая последовательность сборки через Conan и CMake:

conan install . --output-folder=build --build=missing -s build_type=Release
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Если зависимости подготовлены вручную, допускается конфигурирование стандартным вызовом CMake при условии, что fmt, spdlog, Boost, Qt5 и libusb доступны через CMAKE_PREFIX_PATH или системные пути поиска.

После сборки запускается один из исполняемых файлов:

./GuiRng
./GuiRngBlocks

Фактический путь к бинарным файлам зависит от используемого генератора CMake и настроек Conan layout.

Порядок запуска:

1. Запустить одно из GUI-приложений.
2. В стартовом окне выбрать устройство из списка найденных USB-модулей.
3. Подтвердить выбор и дождаться открытия главного окна.
4. Задать режим работы и источник данных.
5. Для GuiRng указать объём выборки в байтах и начать чтение.
6. Для GuiRngBlocks указать размер блока и число блоков, затем начать цикл статистического контроля.

6. Входные данные

Входные данные формируются из трёх источников:

• USB-устройство, выбранное пользователем в стартовом диалоге.
• Параметры режима, задаваемые элементами GUI.
• Количественные параметры эксперимента, вводимые вручную в поля окна.

В приложении GuiRng входными параметрами являются:

• Выбранный режим работы модуля.
• Выбранный источник данных.
• Номер слота.
• Размер считываемой выборки в байтах.
• Флаги отображения гистограммы, аппроксимации и графика частоты импульсов.
• Ручные коэффициенты аппроксимации K и B, если пользователь корректирует их вручную.

В приложении GuiRngBlocks входными параметрами являются:

• Выбранный режим работы модуля.
• Выбранный источник данных.
• Номер слота.
• Размер одного блока в байтах.
• Количество блоков в серии.

7. Выходные данные

Во время работы приложения формируют следующие выходные данные:

• Информация о модуле и его прошивке.
• Скорость USB-передачи.
• Частота импульсов.
• Счётчик переполнений буфера.
• Расчётные статистики по единицам и нулям.
• Значения Sn, ratio, P-value и производных критериев.
• Графики распределений и промежуточных статистик.

Дополнительные выходные данные GuiRng:

• Файл *.rng с сырым бинарным потоком.
• Файл *.hist с сохранённой гистограммой в текстовом виде.

Дополнительные выходные данные GuiRngBlocks:

• График изменения delta по номеру блока.
• Столбчатое распределение P-value по десяти интервалам.