Telega KiCad

Telega

Структура проекта

Проект состоит из нескольких самостоятельных частей:

• Embedded - прошивка для STM32F3Discovery, протокол обмена, драйверы датчиков и прикладная логика МК.
• Python - GUI-приложение для ПК, слой связи с МК, сохранение данных и вспомогательные модули анализа.
• KiCad - файлы печатной платы. В рамках этого README описывается только наличие раздела, без разбора содержимого.
• Kompas3d - механические модели и сборки. Файлы CAD не анализируются подробно.
• Список комплектующих.csv - перечень компонентов проекта.

GUI-приложение для ПК

GUI находится в каталоге Python и запускается из Python/main.py. Приложение написано на PyQt5 и предназначено для работы с путеизмерительной тележкой через COM-порт: настройка подключения, запуск служебных стадий МК, отображение текущих показаний и сохранение результатов измерений.

Запуск

Рекомендуемый запуск из корня репозитория:

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

На Linux путь к интерпретатору виртуального окружения будет Python/.venv/bin/python.

Возможности приложения

• выбор директории сохранения и шаблона имени файлов;
• выбор и обновление списка COM-портов;
• запуск рукопожатия с МК после применения настроек;
• запуск набора статического буфера перед проездом;
• запуск и завершение измерительного проезда;
• отображение текущих значений Acc_X, Acc_Y, Acc_Z, Gyro_X, Gyro_Y, Gyro_Z и кода ДПП;
• сохранение данных статического буфера и проезда в CSV;
• вывод пользовательских сообщений, предупреждений и ошибок в журнале окна.

Типовой рабочий сценарий описан подробнее в Python/docs/USER_GUIDE.md.

Основные модули

• Python/main.py - точка входа, создание QApplication и главного окна.
• Python/gui/main_window.py - главное окно, координирующее интерфейс, сессию связи и переключение пользовательских стадий.
• Python/gui/program_stages - реализации стадий настройки, статического буфера и измерений, а также контракт главного окна, необходимый этим стадиям.
• Python/gui/ui/main_window.ui - Qt Designer-разметка интерфейса; рядом лежат графические ресурсы telega.png и update.png.
• Python/gui/com_port_settings.py и Python/gui/saving_params.py - работа с настройками COM-порта и параметрами сохранения.
• Python/gui/com_port_reader.py - мост между GUI и низкоуровневой сессией МК. Запускает отдельный процесс для обмена с устройством и прокидывает данные/события в GUI через Qt-сигналы.
• Python/telega_session/data_storage.py - потоковая запись пакетов TelegaData в CSV в дочерней сессии МК.
• Python/gui/data_visualization.py - обновление LCD-индикаторов текущими значениями телеметрии.
• Python/telega_session - проектный слой общения с тележкой: COM-порт, декодер протокола, контроллер команд и функция запуска сессии.
• Python/async_mc_controller - более общий асинхронный слой для источников байтов, декодирования, контроллера, шины сигналов, логирования и конфигурации.
• Python/app_config и Python/logger - конфигурация приложения на Pydantic и настройка логирования.
• Python/data_analys и Python/plotting - вспомогательные модули для постобработки, фильтрации, расчета траектории и построения графиков.

Поток данных

После применения настроек главное окно создаёт конфигурацию COM-порта и запускает ComPortReader. Низкоуровневая сессия работает в отдельном процессе через multiprocessing, читает байтовый поток с устройства, декодирует пакеты протокола и потоково сохраняет их в CSV. В GUI передаётся только последний пакет не чаще одного раза в 500 мс для обновления индикаторов; служебные события и ошибки передаются отдельной очередью. Главное окно задаёт путь CSV-файла и переключает доступные действия пользователя согласно текущей стадии работы.

Сохраняемые данные

Во время набора статического буфера создается файл вида:

{шаблонное_название}_static_init_{номер_проезда}.csv

Во время измерительного проезда создается файл вида:

{шаблонное_название}_measuring_{номер_проезда}.csv

CSV пишется в UTF-8 с полями:

PackageNum DppCode AccX AccY AccZ GyroX GyroY GyroZ Temp

Настройки приложения сохраняются в Python/app_config/settings.json; файл относится к локальным runtime-данным и не обязан храниться в репозитории.

Прошивка для STM32F3Discovery

Пользовательская часть прошивки расположена в Embedded/user и написана как C++-слой поверх STM32F30x Standard Peripheral Library, USB VCP и библиотек датчиков платы STM32F3Discovery. Проект устроен почти как header-only фреймворк: прикладной сценарий находится в src/main.cpp, а драйверы, контейнеры, фильтры, протоколы и обвязка периферии вынесены в заголовочные модули inc.

Общая структура

• src/main.cpp - точка входа, инициализация оборудования, главный цикл, стадии программы, обработчики команд и системные функции.
• inc/main.h - C/C++ мост к STM32 SPL, USB VCP, CMSIS и функциям пользовательского слоя.
• inc/Common - общие типы, константы, TriaxialData и базовый механизм регистрации обработчиков прерываний.
• inc/Periph - GPIO, EXTI и светодиоды платы.
• inc/Timers - обертки над аппаратными таймерами STM32, конфигурации и descriptor-классы.
• inc/Sensors - драйверы L3GD20, LSM303DLHC и масштабирование датчиков.
• inc/Filters - статистика, N-sigma фильтр и фильтр Калмана.
• inc/DataContainers - очереди фиксированного размера, включая SPSC-очередь для обмена между IRQ и main.
• inc/Communication - сообщения, пакеты, декодеры, USB VCP и USART.
• inc/aaa_Project_Files - доменная логика проекта: команды, пакет телеметрии, декодер входящих команд и датчик пройденного пути.

Инициализация и прерывания

При старте main() копирует таблицу векторов прерываний из flash в пользовательскую таблицу _user_vector_table в RAM, переключает SCB->VTOR на эту таблицу и затем инициализирует оборудование через InitAll(). Такой подход позволяет C++-объектам регистрировать собственные обработчики IRQ во время инициализации.

Механизм регистрации прерываний реализован через CRTP-класс BaseIRQDevice. Конкретные устройства, например таймеры или EXTI-пины, наследуются от него, сохраняют указатель на активный экземпляр и записывают статический обработчик в пользовательскую таблицу векторов. При срабатывании IRQ статический обработчик перенаправляет вызов в метод irq_handler() нужного объекта.

Основной цикл и стадии программы

Главный цикл прошивки работает как простой диспетчер событий. Сначала он выполняет накопленные отложенные команды из command_manager.command_queue, затем при необходимости переключает текущую стадию из program_stage_queue, после чего вызывает init() новой стадии один раз и execute() на каждом проходе цикла.

Поддерживаемые стадии:

• FooStage - состояние ожидания: таймеры остановлены, датчики периодически читаются для поддержания их рабочего состояния.
• StaticStage - статический сбор начальных данных: формируется InitFrameNum телеметрических пакетов, после чего отправляется END_OF_STATIC_INIT.
• MeasuringStage - рабочее измерение: по тику TIM3 читаются датчики, данные фильтруются, упаковываются и отправляются на ПК.

Таймеры

В прошивке используются два таймера общего назначения:

• TIM3 - основной таймер измерений. Его IRQ переключает светодиод LED9, выставляет флаг нового периода измерений и увеличивает счетчик времени tick_counter.
• TIM4 - таймер индикации состояния. Его IRQ переключает LED6 и LED7.

Таймеры описаны шаблонными классами Timer2, Timer3, Timer4, которые принимают пользовательский обработчик прерывания как compile-time параметр. Это позволяет вызывать обработчик без виртуальных функций и без runtime-диспетчеризации.

Датчики и фильтрация

Прошивка работает с датчиками платы STM32F3Discovery:

• L3GD20 - гироскоп, данные угловой скорости.
• LSM303DLHC - акселерометр и температурный датчик; магнитометр в текущей конфигурации отключен.
• DppSensor - датчик пройденного пути: импульсы приходят на EXTI-вход PC1, направление считывается с PC3.

Перед отправкой телеметрии данные акселерометра, гироскопа и температуры проходят через NSigmaFilter. Для ускорения и угловой скорости используется фильтр NSigmaFilter<TriaxialData, 4, 16>, для температуры - NSigmaFilter<float, 1, 16>. Фильтр отбрасывает выбросы по правилу N-sigma и накапливает итоговое среднее.

Связь с ПК и протокол

Основной канал связи с ПК - USB Virtual COM Port. Входящие данные принимаются в UserEP3_OUT_Callback(), преобразуются в Messages::SizedMessage<VCP_BUFFER_SIZE> и передаются в UsbPort, где поток байтов разбирается DecoderTelega.

Входящий командный протокол:

• header: 0xE7 0x7E;
• format: 0xAB;
• length: длина поля данных;
• data: код команды;
• checksum: младший байт суммы предыдущих байтов пакета.

DecoderTelega отвечает только за входящий поток команд. Он находит команду в списках urgent_commands и deferred_commands менеджера команд. Срочные команды выполняются сразу в контексте обработчика приема, отложенные команды помещаются в SPSC-очередь и выполняются позже в основном цикле.

Поддерживаемые команды:

• 0xff 0xff - перезагрузка МК.
• 0xaa 0x00 - переход в FooStage.
• 0xaa 0x02 - переход в MeasuringStage.
• 0xaa 0x03 - переход в StaticStage.
• HANDSHAKE_ACK, HEARTBEAT_ACK - текстовые служебные команды, на которые МК отвечает собственными ACK-сообщениями.

Исходящие пакеты

Телеметрия отправляется через TelegaPackage. Пакет содержит:

• счетчик времени tick_counter;
• ускорение acc_value;
• угловую скорость gyro_value;
• температуру temp_value;
• код датчика пройденного пути dpp_code;
• контрольную сумму.

Текстовые служебные ответы формируются через MessagePackage: подтверждение команды, handshake ACK, heartbeat ACK, сообщение об ошибке и окончание статической инициализации.

Соглашения проекта

Прошивка рассчитана на доверенный ПК-клиент, который отправляет небольшие корректные команды и не перегружает очередь команд. Переполнение очередей и чрезмерная длина входящих пакетов считаются нарушением протокольного соглашения, а не штатным режимом работы. Частота таймера измерений должна быть согласована со временем чтения датчиков, фильтрации и отправки пакета так, чтобы обработка успевала завершиться до следующего периода измерений.