shturman/docs/domains/k-sensors-peripherals.md

Домен K — Датчики / периферия

Не-CAN сенсоры и периферия самого устройства: GPS (→ сервис Location), IMU, выделенные ADC/GPIO-входы (резистивный руль), USB-сенсоры. Содержит ru.shturman.Location, на который ссылаются C (distraction, день/ночь), D, a-base §7 (GPS-время).

Статус: v2 (на ревью). v2 — после adversarial-ревью (18 находок). Связано с: hardware.md (§4 GPS/периферия) · ipc.md (Location) · security-privacy.md (location, приватность) · a-base-system.md (§7 GPS-время) · домены C (ввод/distraction/тема), D, E (CAN-граница), J (камеры)

---

1. Назначение и границы

• Что делает: интегрирует не-vehicle-bus сенсоры и периферию устройства: GPS (→ Location), IMU/акселерометр, выделенные ADC/GPIO-входы, специфичные USB-сенсоры.
• Граница с E (важно): K не трогает CAN — единственный владелец CAN — E (red-line, #2). Сигналы с шины авто (кнопки руля на CAN, парктроники, TPMS, климат) — сигналы E/data-model, не K.
• Граница с A: udev/USB-стек — база (A); K — прикладная интеграция конкретных сенсоров.

2. ru.shturman.Location — GPS / положение (главный артефакт K)

• Источник: GPS-приёмник (USB/UART, NMEA) → gpsd → сервис (hardware §4).
• Публикует (ipc §3): Latitude, Longitude, Heading, Speed, FixQuality, HDOP, satellites, ts; сигналы LocationChanged, FixChanged. Гейтится capability location.

FixQuality — многоуровневый (не бинарный): enum {no_fix, fix_2d, fix_3d, augmented (DGPS/SBAS), dead_reckoning} + HDOP/satellites как метрики достоверности при валидном фиксе. Инварианты: dead_reckoning НЕ считается валидным для distraction/Nav (экстраполяция); высокий HDOP = большая ошибка. Валидность времени отделена от валидности позиции (RMC/ZDA UTC может быть валиден без позиционного фикса — для a-base §7). Точный маппинг NMEA — сверяется при реализации.

Скорость/курс на малой скорости (контракт): ниже порога уверенности (~2–3 км/ч, BSP-tunable) Location зануляет Speed (не сырой Doppler-шум) и помечает Heading невалидным. Это source-level фикс (ортогонален гистерезису distraction в C §7): убирает систематический дрейф на стоянке, который иначе держал бы ложный distraction-on. C потребляет занулённую/ quality-флагнутую Speed, не сырую.

QoS: типовая частота NMEA ~1 Гц (выше — зависит от приёмника); латентный бюджет fix→LocationChanged→потребитель. Ненадёжность у нуля и в urban-canyon — вход для гистерезиса/ fail-safe C §7. До поднятия K — мок-стаб (dev fake-GPS).

Приём, старт, антенна:

• Внешняя/активная антенна на reference-плате (встроенная в торпедо часто не видит небо) → hardware §4.
• TTFF: cold-start (потеря эфемерид) — десятки секунд; warm/hot — быстрее. После battery-cutoff (B §7, долгая стоянка) поездка может стартовать с окна без GPS — потребители деградируют штатно (C §7 консервативный distraction; a-base §7 нет GPS-времени до первого fix).
• Питание в sleep/battery-cutoff: по умолчанию GPS обесточивается (приоритет энергии на запуск, #5; ценой cold-start на wake), keep-alive рейл — только если сценарий wake требует фикса сразу. Селективный рейл — hardware §3; бюджет разряда — B §7/§12.
• Boot: Location/gpsd поднимаются в Stage 2 (фоном, architecture §6); ранняя поездка до фикса — деградированный режим. Подписки авто-снимаются по NameOwnerChanged (ipc §2).

Точность времени: по NMEA-via-gpsd-SHM — десятки–сотни мс (достаточно для TLS-гейта a-base §7 и упорядочивания логов). PPS (µs) — опционально, требует приёмник с 1PPS + линию на GPIO/UART-DCD (hardware §4); на USB-донгле обычно нет. По умолчанию — SHM-класс.

Приватность локации: по умолчанию эфемерна — live-позиция на шине, без персистентного трека (в v1 нет фичи, требующей хранения; Nav — v4). Если позже понадобится (last-parked/ trip-log) — только fscrypt-поддерево /data (a-base §3), с retention и factory-reset-wipe (a-base §12). Доступ к локации — в audit-log (security-privacy ✅); точная локация исключена из онлайн-LLM-промпта по умолчанию (только по отдельному гранту, security-privacy §7); location-грант — while-in-use (revoke при уходе в фон). First-party-потребители (C, a-base) — строго on-device, наружу не уходит.

Dev-симулятор Location (#13): обязательные сценарии — реплей NMEA-трека, no-fix/тоннель/потеря, дрейф, cold-start TTFF, время-без-позиции, низкоскоростной джиттер у нуля, расхождение GPS-vs-OBD (для арбитража C §7 v2). Детали — dev-environment.

3. Мультируль (кнопки руля) — двойной источник

• CAN-кнопки (современные авто): читаются как сигналы E (через VehicleData), не K.
• Резистивная ADC-лесенка (старые авто): K оцифровывает → нормализует в события.

Контракт ADC-лесенки (самая хрупкая часть — не одна строка):

• Window-table, не точечные пороги: BSP даёт на кнопку окно [min,max] + гистерезис (учитывая резисторы авто И наш делитель/Vref/pull-up). Статические per-vehicle данные, аналог DBC (hardware §5).
• Рантайм-кондиционирование: debounce + median/avg-фильтр + отбрасывание транзиентных уровней при нажатии/отпускании (release-through-adjacent не даёт фантомных нажатий); short/long/repeat.
• Коллизии: чтение вне всех окон → no-press (никогда не ложная кнопка); простая лесенка не различает одновременные нажатия (паразитный уровень) — политика detect-and-drop.
• Темп./aging-дрейф: ширина окон/гистерезис под конверт −20…+70 °C (hardware §1a) + запас.

Транспорт ввода — uinput/evdev (не Shell-D-Bus): K нормализует кнопки (ADC + опц. проксированные CAN из E) в виртуальное uinput-устройство → libinput → smithay-композитор Shell → штатный Wayland-input сфокусированному клиенту. Это покрывает и декларативные тайлы, и surface-апы (нав/медиа), что вариант «только Shell-D-Bus» НЕ покрывает. Гейтинг «кому руль» — фокус композитора (C §2), не отдельная D-Bus-capability.

Distraction-дисциплина: в distraction-режиме (C §7, через DistractionModeChanged) часть руль-действий гейтится — навигация по упрощённому UI и приоритет голосу OK; сложное листание/ глубокие меню блокируются, чтобы руль не обходил #6.

4. IMU / акселерометр

• Ориентация устройства, детект движения; опционально g-sensor.
• I2C/SPI-сенсор на плате — не обязателен, на большинстве сборок может отсутствовать. Фаза — later.
• ⚠️ Констрейнт для J: g-sensor НЕ гарантирован. Dashcam (J) не закладывается на g-sensor: дефолт — непрерывная кольцевая запись без триггера; event-маркировка опциональна (IMU или резкое замедление по GPS-Speed). Деградирует видимо (пишет всегда), не тихо (#4).

5. Прочие сенсоры (в основном — E)

• Парктроники, TPMS, климат (чтение): в современных авто на CAN → сигналы E/data-model (K не дублирует).
• K подключает только выделенные не-CAN датчики (редко, ретрофит). Парктроник-дистанция → оверлей поверх вида камеры (J) — данные из E или K по источнику.

6. USB-периферия

• Енумерация/интеграция специфичных сенсоров на USB. Базовый udev/USB-стек — A.
• (mic-массив — PipeWire/аудио; ELM327 — транспорт E; модем — Connectivity; не K.)

7. IPC

• ru.shturman.Location — см. §2 и ipc.md §3 (FixQuality-enum + per-property quality для Speed/Heading).
• Input руля — через uinput/evdev (§3), не отдельный D-Bus-интерфейс.

8. Функции

функция	MVP/later	зависит от	фаза
ru.shturman.Location (GPS → position/speed/heading + FixQuality/HDOP)	MVP	hardware(GPS), gpsd	v1
Zero-clamp скорости / валидность курса у нуля	MVP	—	v1
GPS-источник (NMEA/gpsd) для time-sync a-base §7	MVP	hardware(GPS)	v1
Приватность локации (эфемерна; audit; не в промпт)	MVP	security-privacy	v1
Мультируль: ADC-лесенка (window-table) → uinput	later	hardware(ADC)/BSP	v1/v2
Мультируль: CAN-кнопки (через E)	later	E	v2
IMU/акселерометр (опц.)	later	hardware(IMU)	later
Выделенные не-CAN датчики	later	hardware	later
Nav-позиционирование (потребитель Location)	later	домен I	v4

9. Зависимости

• Вниз: hardware (§4 GPS/антенна/1PPS-опц., ADC-входы, IMU; §3 селективный рейл GPS).
• Вбок: E (CAN-граница); A (udev/USB-стек); B (питание GPS в sleep/battery-cutoff, бюджет разряда); J (парктроник-оверлей; констрейнт — dashcam не на гарантированный g-sensor, §4).
• Вверх/потребители: C (GPS-скорость для distraction v1, GPS-восход для темы v1; input с руля через uinput), D (геоконтекст), a-base §7 (GPS-время, v1), Nav (I, v4).

10. Открытые вопросы

• 🟡 Маппинг кнопок руля → действия + калибровка ADC-порогов на конкретном авто (BSP/HAL, hardware §5).
• ◻️ Какие руль-действия гейтятся в distraction (C §7) — парный вопрос с C §11.
• ◻️ IMU на reference-плате — нужен ли (ориентация? опц. g-sensor для dashcam-маркировки?); до решения J = непрерывный ring-buffer (§4). + dead-reckoning (IMU+GPS) для тоннелей/удержания distraction-скорости при потере GPS — нужен ли и где живёт (K-fusion/gpsd/Nav).
• ◻️ Питание GPS в sleep/battery-cutoff (keep-alive warm-start vs обесточивание+cold-start) — hardware §3 + B §7.
• ◻️ Арбитраж GPS-vs-OBD-скорости (C §7 v2) — кросс-проверка.

---

Журнал решений (домен K)

Решение	Выбор	Дата
Граница с E	K — не-CAN сенсоры/периферия; CAN-сигналы (кнопки/парктроник/TPMS/климат) — у E	2026-06-16
Location	ru.shturman.Location (GPS/gpsd) — владелец K; K поставляет фид, time-sync владеет a-base §7	2026-06-16
Скорость GPS	zero-clamp <~2-3 км/ч; FixQuality многоуровневый; dead_reckoning не валиден для distraction	2026-06-16
Приватность	эфемерна (без трека в v1); audit-log; не в LLM-промпт; while-in-use грант; on-device	2026-06-16
Мультируль	window-table + кондиционирование + collision-drop; транспорт uinput/evdev; гейт фокусом C	2026-06-16
IMU/dashcam	IMU опц./не гарантирован; J = непрерывный ring-buffer, не на g-sensor	2026-06-16
Время	SHM-класс (десятки-сотни мс); PPS — опц., hardware-gated	2026-06-16