Открытый API-контракт CARTelemetry¶

Интеграция CARTelemetry принимает телеметрию от любого приложения, которое умеет отправлять данные по контракту ниже, и возвращает этому приложению команды. Машиночитаемая версия: GET https://mytechnic.ru/cartelemetry/api/spec/ (генерируется из реестров проекта).

Аутентификация¶

Long-lived access token Home Assistant, заголовок Authorization: Bearer <token>.

Отправка телеметрии¶

POST /api/cartelemetry

{
  "car_name": "my_car",
  "vvn": "VIN (опционально)",
  "firmware": "прошивка головы (опционально)",
  "app_version": "1.0.0",
  "ts": 1730000000,
  "batch": [
    {
      "t": 1730000000,
      "g": {"lat": 56.02, "lon": 92.89, "a": 4.0},
      "s": {"speed": "0", "soc": "68", "power_state": "on"}
    }
  ]
}

car_name должен совпадать с именем, заданным при настройке интеграции.
batch — окно снапшотов (рекомендуется 1 Гц, отправка раз в ~4 с).
g — GPS-минимум (широта/долгота/точность), присутствует всегда.

Получение команд¶

GET /api/cartelemetry/commands?car_name=my_car
→ {"commands": [{"id": "ac_on", "value": "1", ...}]}

Приложение забирает очередь, выполняет команды и подтверждает:

POST /api/cartelemetry/commands
{"car_name": "my_car", "acked": [{"id": "ac_on", "success": true}]}

Сенсоры¶

Ядро (sensors_core, 33 сигнала) — универсальный минимум: скорость, SOC, диапазон, power_state, GPS-блок, батарея устройства, двери/окна/люк, замки, климат, температура за бортом.
Расширенные (sensors_extended, 108) — специфичные для источников (BYD/DiPlus, OBD, Voyah): RADAR-сигналы, зарядная система, подогревы и т.д.

Неизвестные ключи интеграция игнорирует — приложение может отправлять только то, что умеет. Минимально жизнеспособный клиент — только car_name + batch[].s с несколькими ключами ядра.

Команды¶

commands в спеке: id, связанный state_sensor (для подтверждения изменения), параметр и каналы, которыми команда доступна. Приложение выполняет команду тем же каналом, которым читает соответствующий сенсор, либо любым доступным.

Служебные API¶

Ручка	Назначение	Доступ
`POST /api/cartelemetry`	приём телеметрии (HA)	Bearer-токен HA
`GET/POST /api/cartelemetry/commands`	очередь команд	Bearer-токен HA
`POST /api/probe-report`	анонимные отчёты исследования	`X-Cartelemetry-Token`
`POST /api/logs`	отправка журнала приложения разработчику (+описание авто)	`X-Cartelemetry-Token`
`GET /api/spec`	эта спецификация (JSON)	открыто
`POST /api/mcp`	анализ исследований: `list_car_profiles`, `signal_availability`, `channel_availability`, `raw_reports`	открыто
`POST /api/admin`	управление хранилищем исследований/журналов: `list` (по дате/статусу), `get`, `grep` (по строкам), `mark` (обработан), `delete`, `summary`	`X-Cartelemetry-Admin-Token`

Токены intake хранятся на сервере (.data/api_token.txt, .data/admin_token.txt); в APK вшит intake-токен (защита от случайного использования сторонними ресурсами). Обработанные записи старше 7 дней автоматически удаляются при приёме новых данных.