INAV: полезные настройки «только в CLI» — кандидаты на тумблеры (AD-690)

Статус: research / discovery, не решение о реализации. Документ обосновывает
список настроек, которые в официальном INAV Configurator доступны только через
CLI (set X = ...), но при этом полезны обычному пилоту и безопасны, чтобы
вывести их в нашем веб-туле «Инструменты → INAV» тумблерами/полями. Код тула
(web/static/js/tools/inav_msp.js, роуты, шаблоны) в рамках этого тикета не
трогаем — только исследование и этот файл.

0. Зачем это нужно

Официальный INAV Configurator сознательно не выносит в GUI часть параметров: их
меняют командой set <имя> = <значение> на вкладке CLI. Документация INAV прямо
говорит, что «GUI не умеет настраивать всё; часть фич включается/настраивается
только через CLI» (см. docs/Cli.md). Среди «спрятанных» параметров есть простые
и полезные — например одометр (stats), часовой пояс для логов (tz_offset),
выбор GNSS-созвездий. Наш тул может стать удобнее официального, показав их
понятными тумблерами — новичку не придётся лезть в CLI и знать точное имя команды.

Цель ресёрча: составить обоснованный список кандидатов с указанием, что делает
настройка, есть ли она в GUI Configurator, каким каналом MSP до неё дотянуться и
стоит ли выводить (риск/польза).

1. Модель доступа: почему «CLI-only» ≠ «недоступно по MSP»

Ключевой факт для реализации. В INAV каждый параметр set X зарегистрирован в
общей таблице настроек (src/main/fc/settings.yaml → генерится в таблицу
settings_t). Любой параметр из этой таблицы читается и пишется по MSP по имени
через общие команды протокола MSP v2 (src/main/msp/msp_protocol_v2_common.h):

Отсюда следствия для нас:

• «CLI-only» в Configurator означает лишь «не выведено в GUI», а НЕ «недоступно
  программно». Почти любой такой параметр мы можем читать/писать по MSP
  0x1003/0x1004 — ровно так, как наш тул уже делает для блока GPS
  (GPS_CONFIG_SETTINGS в inav_msp.js: список {name, key, kind}, значение по
  имени через MSP2_COMMON_SETTING). То есть добавить тумблер = добавить запись в
  такой список + элемент UI. Минимум кода, минимум риска.
• Клиент обязан знать тип/размер значения заранее (u8/i16/bool/enum-таблица) —
  MSP2_COMMON_SETTING отдаёт «сырые» байты без типа. Тип можно либо захардкодить
  (как сейчас у GPS), либо запрашивать динамически через MSP2_COMMON_SETTING_INFO
  (0x1007) — им же пользуется сам Configurator.
• У части настроек есть выделенные типизированные MSP-сообщения — их и стоит
  предпочесть, если они уже реализованы: имя борта → MSP_NAME/MSP_SET_NAME
  (10/11), маска фич → MSP_FEATURE/SET_FEATURE (36/37), часовой пояс →
  MSP2_COMMON_TZ/SET_TZ (0x1001/0x1002).
• Настоящий CLI-passthrough (слать литеральную строку set x = y в текстовый
  #-режим) для скалярных тумблеров из этого документа не нужен — это запасной
  путь. В туле он уже есть (AD-619/AD-623, бэкап/восстановление diff all), но для
  наших кандидатов он избыточен: везде хватает MSP2_COMMON_SETTING.

Вывод: колонка «Доступ» ниже почти всегда — MSP по имени (0x1003/0x1004),
что позволяет делать честный двусторонний тумблер (прочитал текущее → показал →
записал новое), а не «слепой» CLI-set.

2. Таблица кандидатов

Данные (имя, дефолт, диапазон, тип) сверены по src/main/fc/settings.yaml INAV
9.1.0 (ветка master, получено 2026-07-18). Описания — свои, пересказ смысла
(clean-room, см. §5). «В GUI?» — по знанию официального Configurator (5.x/8.x/9.x);
где не уверен — помечено требует проверки.

3. Первая волна (рекомендованный минимум)

Критерий отбора: максимум пользы обычному пилоту при минимуме риска, все —
двусторонние (читаем текущее → пишем новое) через уже существующий в туле механизм
«настройка по имени» (MSP2_COMMON_SETTING/SET_SETTING). Ни один пункт не трогает
управление/моторы/ESC/шины.

1. Одометр — stats + панель stats_total_*. Флагманская фича.
   - stats — тумблер ON/OFF (bool), MSP по имени.
   - stats_total_time / stats_total_dist / stats_total_energy /
   stats_flight_count — блок «Наработка борта»: read-only показ (перевести в
   ч/км/мА·ч/шт.) + кнопка «Сбросить» (запись 0 в каждый). MSP по имени.
   - ⚠️ Тонкость для тултипа: при включённом stats INAV сохраняет конфиг в EEPROM
   при каждом disarm. Побочный эффект — заодно фиксируются изменения, сделанные
   в полёте RC-adjustments (PID, board alignment). Это нормальное поведение, но
   пользователя стоит предупредить одной строкой.

2. Часовой пояс логов — tz_offset (+ tz_automatic_dst). Прямо усиливает наш
   раздел flight-logs: без него метки времени в Blackbox/GPS идут по UTC.
   tz_offset имеет выделенную типизированную команду MSP2_COMMON_TZ/SET_TZ
   (0x1001/0x1002, i16 минут) — самый надёжный путь; tz_automatic_dst — по имени
   (enum OFF/EU/USA).

3. GNSS-созвездия — gps_ublox_use_beidou, gps_ublox_use_glonass. Логичное
   дополнение к уже выведенному gps_ublox_use_galileo: два bool-тумблера в тот же
   GPS-блок (GPS_CONFIG_SETTINGS). Помогает добрать спутники в своём регионе.

4. small_angle — макс. угол arming. Одно числовое поле (0…180°, дефолт 25).
   Реально нужно при пуске с наклонной поверхности / ручном старте крыла, когда борт
   стоит под углом и отказывается армиться. Безопасно, MSP по имени.

Все четыре пункта укладываются в существующий паттерн GPS_CONFIG_SETTINGS
(inav_msp.js) — новый код минимален: описания настроек + элементы UI. Отдельных
MSP-команд писать не нужно, кроме опционального использования MSP2_COMMON_TZ для
tz_offset.

Вторая волна (после первой, требует аккуратности): failsafe-нюансы
(failsafe_min_distance + _procedure), nav_extra_arming_safety, Airmode
(airmode_type / airmode_throttle_threshold) — полезны, но это safety/тюнинг,
нужен более осторожный UI и предупреждения; и часть требует проверки наличия в GUI.

Явно НЕ выводить: i2c_speed, debug_mode, applied_defaults,
model_preview_type, motor_pwm_protocol, throttle_idle — опасно/служебно/уже в
GUI. name и pilot_name уже есть в официальном GUI (вкладка OSD) и/или в нашем
туле — не «спрятанные».

4. Мини-чеклист для реализующего тикета (не в этом тикете)

• [ ] Для каждого параметра первой волны — знать точный тип/размер (см. таблицу)
  либо тянуть его через MSP2_COMMON_SETTING_INFO (0x1007).
• [ ] stats_total_* — только чтение + явная кнопка сброса (не редактируемое поле).
• [ ] Тултип-предупреждение про EEPROM-сохранение при stats = ON.
• [ ] tz_offset — предпочесть выделенный MSP2_COMMON_TZ/SET_TZ.
• [ ] Проверить на живом борте наличие/отсутствие tz_*, failsafe_min_distance*,
  nav_extra_arming_safety, osd_home_position_arm_screen в текущем GUI
  Configurator (снять пометки «требует проверки»).
• [ ] Неизвестные enum-коды не терять (показывать «код N»), как уже сделано для
  serialrx-провайдера/GPS.

5. Источники и clean-room

Исходники INAV читались только для понимания фактов (имена параметров, дефолты,
диапазоны, номера MSP-команд) — это API/данные, не творческий код. GPLv3-код в наш
репозиторий и тул не копировался; все описания настроек написаны своими словами.

Источники (INAV, ветка master = 9.1.0, получено 2026-07-18):

• src/main/fc/settings.yaml — полный список set-параметров, дефолты, диапазоны,
  enum-таблицы. Ключевые строки: stats* — 3974–3996; name/pilot_name —
  3945–3956; tz_offset/tz_automatic_dst — 4001–4010 (+ таблица DST 111–113);
  gps_ublox_use_beidou/glonass/galileo — 1758–1772; small_angle — 1553–1557;
  failsafe_min_distance* — 910–918; nav_extra_arming_safety — 2574–2578;
  airmode_* — 1818–1828; i2c_speed — 3924–3928; applied_defaults — 1615–1621;
  model_preview_type — 1250–1255.
• src/main/msp/msp_protocol_v2_common.h — opcodes MSP v2: MSP2_COMMON_TZ 0x1001,
  SET_TZ 0x1002, SETTING 0x1003, SET_SETTING 0x1004, SETTING_INFO 0x1007.
• CMakeLists.txt — project(INAV VERSION 9.1.0).
• docs/Cli.md (INAV) — подтверждение, что часть настроек доступна только через CLI.
• Наш тул web/static/js/tools/inav_msp.js — существующий паттерн «настройка по
  имени» (GPS_CONFIG_SETTINGS, MSP2_COMMON_SETTING) и CLI-passthrough
  (AD-619/AD-623) как база для реализации.
• Проверка наличия в GUI: релиз-ноты INAV Configurator 5.0 (перенос craft name в
  OSD) и PR добавления pilot_name в OSD-вкладку; фича-реквесты по выводу
  stats_total_* в OSD/GUI.