@@ -0,0 +1,161 @@
# Домен K — Датчики / периферия
> Не-CAN сенсоры и периферия **самого устройства**: GPS (→ сервис `Location`),
> IMU, выделенные ADC/GPIO-входы (резистивный руль), USB-сенсоры. Содержит
> `ru.shturman.Location`, на который ссылаются C (distraction, день/ночь), D, a-base §7 (GPS-время).
Статус: **v2 (на ревью). ** v2 — после adversarial-ревью (18 находок).
Связано с hardware.md ](../contracts/hardware.md ) (§4 GPS/периферия) · [ipc.md ](../contracts/ipc.md ) (`Location` ) · [security-privacy.md ](../contracts/security-privacy.md ) (`location` , приватность) · [a-base-system.md ](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.
- **Граница с
## 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), с
(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 ](../contracts/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/климат) — у
| 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 |
