universal-mr-uav

Imported from AgafonovAero/universal-mr-uav (AGENTS.md). Install upstream with npx skills add AgafonovAero/universal-mr-uav. Copyright stays with the author.

Инструкции проекта

Проект: универсальная математическая и имитационная модель мультироторного беспилотного воздушного судна для MATLAB/Simulink.

Текущий этап

Текущий этап соответствует стадии 1.5+ и включает:

• минимальную имитационную оболочку MIL;
• подготовленный интерфейсный слой TASK-08 для дальнейшего SIL;
• существующие .m-реализации подсистемы датчиков;
• существующие .m-реализации алгоритма оценивания состояния.

Приоритет дальнейшего сопряжения с внешними комплексами управления полетом установлен в следующем порядке:

1. ArduPilot SIL
2. PX4 SIL
3. PX4 HIL

Simulink допускается только как тонкая имитационная оболочка над уже существующим расчетным ядром.

В рамках задач проекта не допускается:

• создавать графические интерфейсы;
• создавать приложения .mlapp;
• делать бинарные артефакты основным инженерным описанием модели.

Основная инженерная идея

Исходным достоверным описанием модели должны оставаться MATLAB-код и текстовые файлы.

Simulink допускается только как тонкая имитационная оболочка, которая:

• формируется из .m-скриптов;
• сопровождается через .m-скрипты;
• не становится местом хранения основной физической логики;
• не подменяет расчетное ядро блок-схемой ручной сборки.

Терминология и стиль документации

Вся человекочитаемая документация проекта должна писаться на русском техническом языке.

Это требование распространяется на:

• README.md;
• документы каталога docs/;
• отчеты в artifacts/reports/;
• исходные журналы прогонов в artifacts/logs/;
• описания запросов на слияние;
• замечания по проверке;
• итоговые ответы по инженерным задачам.

При подготовке русскоязычных пояснений необходимо опираться на авиационную и нормативную терминологию, согласованную со следующими документами:

• ГОСТ Р 57258-2016;
• ГОСТ 20058-80;
• ГОСТ 23281-78;
• ГОСТ 24999-81.

Допускается не переводить:

• имена программных изделий, например MATLAB, Simulink, ArduPilot, PX4;
• имена файлов, функций, пакетов и веток репозитория;
• синтаксис командной строки;
• общепринятые буквенные обозначения физических величин и единиц.

Русские пояснения должны использовать инженерные формулировки, характерные для документации по динамике полета, системам управления и имитационному моделированию.

Если в тексте впервые упоминается иностранное техническое название, необходимо:

1. сначала дать русское техническое назначение;
2. затем указать точное имя программного изделия или протокола.

Для единообразия следует использовать следующие русские замены:

• source / of / truth -> исходное достоверное описание модели;
• code / centric -> программно-реализованное расчетное ядро;
• kernel / first -> первичность расчетного ядра;
• thin / shell -> тонкая имитационная оболочка;
• scaf / fold -> заготовка средства сопряжения;
• loop / back -> проверочный замкнутый прогон;
• smoke / test -> первичная проверка работоспособности;
• bound / ary -> граница сопряжения;
• adapt / er -> модуль сопряжения;
• run / ner -> исполнитель сценария моделирования;
• flight / stack -> внешний комплекс управления полетом;
• raw / logs -> исходные журналы прогонов;
• sum / mary -> отчет;
• road / map -> план-график работ;
• pack / et -> пакет данных;
• map / ping -> преобразование;
• estim / ator -> алгоритм оценивания состояния;
• sensor / layer -> подсистема датчиков;
• plant -> объект управления;
• true / state -> истинное состояние объекта;
• hover -> зависание;
• yaw / step -> ступенчатое воздействие по рысканию;
• pitch / step -> ступенчатое воздействие по тангажу;
• take / off -> взлет;
• de / bug -> отладка;
• dis / play -> отображение;
• back / end -> исполняющая часть сопряженного комплекса;
• runtime / bridge -> средство обмена данными в ходе моделирования;
• production / ready -> пригодный к штатной эксплуатации.

Предметная область

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

• объект управления;
• математическая модель движения;
• связанная система координат;
• земная система координат;
• винтомоторная группа;
• система автоматического управления;
• контур угловой стабилизации;
• контур стабилизации высоты;
• траекторное управление;
• верификация;
• валидация;
• идентификация;
• летные испытания.

В коде следует применять краткие и ясные английские идентификаторы.

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

• земная система координат в расчетном ядре: NED;
• связанная система координат: X вперед, Y вправо, Z вниз;
• внутренняя форма представления ориентации: кватернион;
• углы Эйлера допускаются только для отображения, отладки и отдельных интерфейсов.

Единицы измерения

В коде следует использовать только единицы системы СИ.

Углы в вычислительном коде должны задаваться в радианах.

Если где-либо используются градусы, преобразование должно быть выполнено явно и отражено в тексте, коде или названии поля.

Архитектурные правила

1. Реализация должна оставаться тексто-ориентированной.
2. В рамках задач не допускается создавать .mlapp, .sldd, .prj. Минимальный .slx допустим только при условии, что он формируется или сопровождается скриптами и остается тонкой оболочкой над .m ядром.
3. MATLAB-пакеты необходимо размещать под /src/+uav/.
4. Код следует распределять по подсистемам:
   • core
   • vmg
   • env
   • ctrl
   • sensors
   • est
   • sim
   • sil
   • sl
5. Каждая нетривиальная функция должна содержать:
   • строку H1;
   • описание назначения;
   • входы;
   • выходы;
   • единицы измерения;
   • допущения.
6. В универсальных функциях не допускаются жестко зашитые значения конкретного летательного аппарата.
7. Примерные параметры следует выносить в отдельные preset- или config-файлы.
8. Первая реализация должна быть минимальной, но исполнимой.
9. Нельзя утверждать, что проверки выполнены, если они реально не были запущены.
10. Если MATLAB недоступен, это необходимо прямо указать и привести точные локальные команды для выполнения.

Правила моделирования на текущем этапе

• базовая модель объекта управления: жесткое тело с шестью степенями свободы;
• ориентация: на основе кватернионов;
• модель движителей: простая квадратичная зависимость T = kT * omega^2, Q = kQ * omega^2;
• микшер: только схема quad-X;
• управление: минимальная заготовка ПИД-регулятора угловых скоростей;
• подсистема датчиков: программно-реализованная и явная;
• алгоритм оценивания состояния: программно-реализованный и явный;
• внешняя среда: пока только сила тяжести;
• один базовый сценарий зависания;
• минимум две базовые модульные проверки;
• оболочка MIL допускается только как оркестрация существующих .m интерфейсов объекта управления, датчиков и алгоритма оценивания;
• TASK-08 подготавливает только интерфейсный слой сопряжения между внешним комплексом управления и существующим расчетным ядром;
• TASK-08 не реализует реальный MAVLink, UDP, ArduPilot или PX4 обмен в ходе моделирования;
• models/mil_top.slx и сценарии TASK-07 должны оставаться работоспособными.

Критерии завершения задачи

Задача считается завершенной только в том случае, если:

• созданы все запрошенные файлы;
• структура репозитория остается согласованной;
• код читаем;
• добавлены проверки;
• приведены команды локальной верификации;
• записаны допущения и ограничения.

Правила работы с Git

• Для каждой инженерной задачи использовать отдельную ветку вида task/NN-short-name.
• Основной режим работы Codex для репозитория: Worktree.
• После завершения каждой задачи необходимо:
  1. запустить scripts/bootstrap_project.m;
  2. запустить runtests('tests');
  3. запустить сценарии моделирования, относящиеся к задаче;
  4. сохранить исходные журналы прогонов в artifacts/logs/;
  5. обновить отчет задачи в artifacts/reports/task_NN_summary_ru.md;
  6. сделать commit;
  7. выполнить push ветки;
  8. открыть или обновить запрос на слияние.
• Нельзя утверждать, что MATLAB-прогоны завершились успешно, если исходные журналы не сохранены в репозитории.
• Все отчеты по задачам, замечания по проверке, сообщения commit и описания запросов на слияние должны быть на русском языке.

Правила инженерной проверки

К ошибкам уровня P1 следует относить:

• ошибки знаков и систем координат;
• неверную геометрию микширования;
• скрытые параметры вне preset- и config-файлов;
• отсутствие исходных журналов после заявленных прогонов;
• перенос физической логики в бинарные артефакты вместо .m-кода;
• перенос физики объекта управления, подсистемы датчиков или алгоритма оценивания состояния внутрь .slx как ручной блок-схемной реализации.

При проверке необходимо требовать минимальный достаточный объем изменений без постороннего функционального расширения.