Initial

README.md

@@ -0,0 +1,92 @@
+# telemetry-dashboard
+
+Одностраничный дэшборд телеметрии стратосферного зонда. Подключается к
+WebSocket бэкенда stratoflights и отображает все поля MSG_BEACON в реальном
+времени. Запускается рядом с leaflet_svelte (карта — там, здесь — приборы).
+
+## Быстрый старт
+
+```bash
+npm install
+
+# дев-сервер
+npm run dev
+
+# type-check + продакшн-сборка (статика в ./build)
+npm run check
+npm run build
+```
+
+Деплой идентичен leaflet_svelte: `build/` раздаётся любым статическим
+сервером, fallback — `index.html`.
+
+## Использование
+
+В шапке указывается полный адрес WS-эндпоинта:
+
+```
+ws://<host>/api/ws/satellite/<satellite-uuid>/telemetry/
+```
+
+Адрес сохраняется в localStorage (дефолт можно задать через
+`VITE_DEFAULT_WS_URL`, см. `.env.example`). Если URL совпадает с известным
+шаблоном stratoflights, перед подключением подтягивается история по REST
+(`/api/<uuid>/telemetry/`); для любого другого ws-адреса дэшборд просто
+слушает поток. При обрыве связи — автопереподключение с экспоненциальным
+бэкоффом (до 30 с), данные не сбрасываются, плитки затемняются, возраст
+последнего пакета подсвечивается (янтарный > 15 с, красный > 60 с).
+
+## Тестовый сервер
+
+```bash
+pip install websockets
+python3 test_server.py --interval 1 --speedup 20   # полный полёт за ~9 минут
+python3 test_server.py --speedup 200 --start 5900  # сразу перед разрывом шара
+```
+
+Эмулирует полный профиль полёта (подъём 5 м/с → разрыв на 30 км → спуск) в
+точном формате пакетов бэкенда. Подключаться на `ws://localhost:8765/`.
+
+## Пре-флайт аудит форматов
+
+```bash
+python3 field_audit.py   # из корня telemetry-dashboard
+```
+
+Исполняемая сверка всей цепочки: математика firmware против контрольных
+примеров из даташитов (MS5611, SHT4x), бит-точный round-trip
+beacon → PN9/CRC → Deframer → parse → webclient, совпадение ключей payload и
+имён флагов с нашим парсером. 9 групп проверок; любое расхождение — assert.
+
+## Устройство
+
+- **SvelteKit + adapter-static** (Svelte 5 runes, TypeScript) — тот же стек и
+  процесс сборки, что у leaflet_svelte; тот же брендовый Bootstrap
+  (`static/css/bootstrap.min.css`).
+- **uPlot** для графиков — им же рендерит time series Grafana; ~22 КБ gzip,
+  потоковые обновления через `setData()`, курсор синхронизирован между всеми
+  графиками (`cursor.sync`).
+- `src/lib/telemetry.ts` — чистый домен: парсинг пакета, производная
+  вертикальная скорость (окно 30 с, как у SondeHub), колонки для uPlot с
+  разрывами линий при пропаже связи > 60 с.
+- `src/lib/store.svelte.ts` — WebSocket + реконнект + массив сэмплов.
+- Пороги (батарея, спутники, возраст пакета, быстрый спуск) — константы в
+  начале `src/routes/+page.svelte`.
+
+## Выбор визуализаций (по итогам ресёрча SondeHub/SatNOGS/Grafana-практик)
+
+| Показатель | Форма |
+|---|---|
+| Возраст пакета | stat-плитка, верхний левый угол, порог 15/60 с |
+| Высота GPS + баро | hero-график (две серии; баро выявляет отказ MS5611) + плитка |
+| Верт. скорость | производная по GPS-высоте; плитка ▲/▼ + график с нулевой линией |
+| Давление | график, лог-шкала (экспонента → прямая), гПа |
+| Температуры ×3 | один график, три серии с прямой подписью |
+| Влажность | график с фиксированной шкалой 0–100 % |
+| Батарея | плитка + спарклайн, порог 3,5/3,3 В (3,3 = BATT_LOW_MV firmware) |
+| Спутники | плитка + спарклайн, порог 4/6 |
+| Координаты | моноширинная плитка, 5 знаков |
+| 13 флагов | лампы с семантикой: OK-флаги зелёный/красный, состояния синий/серый, LOW_BATT/PYRO_ARMED — тревожные только когда взведены |
+
+Радиальных gauge нет намеренно: ни один осмотренный боевой дэшборд
+(sonik.space, SondeHub, SatNOGS) их не использует.