20 KiB

Raw Blame History

Пункт управления NODE.DC

Универсальный браузерный пункт управления NODE.DC на React 19, TypeScript и Vite. Приложение задаёт общую операторскую оболочку для аппаратов, сенсоров, наблюдения, миссий и записей. XGRIDS/LixelKity K1 является первым реальным device adapter, но структура интерфейса от него не зависит.

Внутри пространственной рабочей поверхности встроен открытый Rerun Web Viewer. Это self-hosted frontend-компонент из npm-пакета @rerun-io/web-viewer, а не переход во внешний облачный интерфейс. При запуске K1 live/replay backend сам создаёт Rerun gRPC/proxy source; ручной адрес нужен только для другого Rerun потока или совместимой RRD-записи.

Текущее состояние

Контур	Состояние	Что это означает
NODE.DC fixed shell	Реализован	Header, навигация по разделам, рабочая поверхность, окна и инспекторы работают в одном приложении.
Локальный control plane	Реализован	React получает состояние и выполняет операции через FastAPI REST и WebSocket на loopback.
K1 BLE → Wi-Fi	Реализован	Реальный BLE-поиск всех видимых устройств и одна подтверждённая provisioning-запись выбранному устройству.
K1 live/replay MQTT	Реализован	Read-only приём, raw-first сохранение, декодирование облака точек и позы, реальные метрики.
Автоматический MQTT → Rerun	Реализован	Первый live/replay поднимает process-wide `RecordingStream` и gRPC/proxy на TCP 9876; следующие сессии сбрасывают сцену и метрики и переиспользуют его.
Встроенный Rerun Viewer	Реализован	Self-hosted npm-компонент автоматически открывает текущий gRPC source внутри Control Station; внешний viewer не используется.
Контролы сцены → Rerun	Реализованы для текущей геометрии	Работают размер и видимость точек, атрибут цвета, палитра, окно накопления, траектория и сетка. Проекция, собственный timeline и сохранённые layout-профили ещё не подключены.
Legacy Foxglove module	Только regression	Модуль и тесты сохранены для сравнения декодирования. Текущий live/replay runtime не запускает Foxglove WebSocket и не использует TCP 8765.
Камеры, карты и миссии	Интерфейс готов	Серверная логика и реальные каналы для этих рабочих поверхностей ещё не подключены.

Приложение не генерирует демонстрационное облако, траекторию, кадры или метрики. Если реальных данных нет, область сцены остаётся пустой, а числовые поля показывают —.

Архитектура данных

K1 MQTT :1883, read-only
└── raw .k1mqtt + metadata + SHA-256 сохраняются первыми
    └── bounded latest-wins preview queue (32 сообщения)
        └── проверенный protobuf/LZ4 decoder
            └── Rerun Points3D + Transform3D + LineStrips3D
                └── gRPC/proxy TCP 9876
                    └── rerun_grpc_url в REST/WebSocket state
                        └── встроенный @rerun-io/web-viewer
                            └── пространственная сцена NODE.DC

React Control Station ←→ REST /api/* + WebSocket /api/events
                         FastAPI на 127.0.0.1:8000
                         CoreBluetooth + live/replay runtime

В момент готовности RerunBridge backend публикует адрес вида rerun+http://127.0.0.1:9876/proxy. Frontend автоматически назначает его сцене, если оператор не указал ручной source. После остановки приёма URL и встроенный viewer остаются активны, а следующая сессия сбрасывает session-local геометрию, траекторию и метрики и использует тот же listener. Он закрывается вместе с процессом k1link serve.

Поля foxglove_ws_url и foxglove_viewer_url пока остаются в API как совместимость со старым контрактом, но текущий runtime держит их пустыми.

Фиксированная оболочка

Shell собран из локальных NODE.DC UI packages и сохраняет одну структуру для всех функциональных модулей:

AppHeader — марка NODE.DC, выбор архитектурного раздела и состояние локального backend.
AdminNavigationPanel — контекст аппарата и список рабочих поверхностей выбранного раздела.
LandingStage — стартовая ситуационная поверхность и быстрые переходы.
ApplicationPanel — единый контейнер активной рабочей поверхности.
Window и Inspector — источник, отображение, слои и компоновка без раскрытия внутренних панелей визуального движка.

Встроенный Rerun Viewer работает как canvas внутри этой оболочки. Его верхняя, blueprint-, selection- и time-панели скрыты, чтобы продуктовые действия жили в Control Station. Размер точек, способ окрашивания и палитра, 12-секундное по умолчанию накопление, видимость облака и траектории и сетка связаны с backend и Rerun Blueprint. Кнопки собственного timeline, смена 2D/3D/карты и сохранение layout пока остаются интерфейсным контрактом.

Архитектурные разделы

Навигация описана данными в src/productModel.ts, а не зашита в разметку каждой страницы.

Раздел	Назначение
Центр	Оперативный обзор, состояние контура и активность оператора.
Парк	Аппараты, текущее устройство, сенсоры и конфигурации борта.
Наблюдение	Пространственная сцена, камеры, карта, объекты, телеметрия и время.
Миссии	Планировщик, маршруты, сценарии и исполнение. Командный backend отключён.
Данные	Сессии, потоки, сущности, playback и экспорт доказательств.
Система	Модули, интеграции, сеть, аудит и настройки платформы.

Карточки возможностей имеют четыре честных уровня: работает сейчас, готово к источнику, интерфейсный контракт и последующий этап. Каталог не следует читать как утверждение, что для каждой карточки уже существует backend.

Установка, проверка, сборка и запуск

Требуются Node.js 20.19+ либо 22.12+, uv и соседний checkout NODEDC_DESIGN_GUIDELINE: зависимости @nodedc/* подключены к нему через локальные file: пути. Python устанавливается только в .venv репозитория.

Канонический путь от корня репозитория:

cd /Users/dcconstructions/Downloads/mnt/NODEDC/NDC_xgrids-k1-connector
uv sync --group dev

cd apps/k1-viewer
npm install
npm run typecheck
npm run build

cd ../..
uv run k1link serve

Открыть http://127.0.0.1:8000. Команда serve отдаёт собранный dist/ и локальный API. Она намеренно привязана только к 127.0.0.1; LAN bind не предусмотрен, потому что endpoint подключения кратковременно принимает пароль Wi-Fi.

Для разработки интерфейса после запуска backend:

cd apps/k1-viewer
npm run dev

Vite слушает http://127.0.0.1:5173 и проксирует /api и /api/events на http://127.0.0.1:8000. Другой локальный backend можно указать переменной VITE_API_TARGET. Preview production-сборки запускается командой npm run preview на http://127.0.0.1:4173.

Операторский путь для текущего K1 adapter

Запустить uv run k1link serve и открыть Control Station.
Выбрать Парк → Локальное устройство.
Включить K1, дождаться стабильного индикатора и подтвердить это в форме.
Нажать Показать все BLE-устройства. Интерфейс показывает полный результат шестисекундного поиска; метка совместимости является подсказкой, выбор делает оператор.
Ввести SSID и пароль существующей сети и явно запустить подключение. Это одна reviewed provisioning-запись без автоматических повторов.
Запустить live-приём по определённому адресу K1 либо replay локального .k1mqtt/проверенного TSV. Физическое сканирование K1 запускается и останавливается подтверждённым двойным нажатием кнопки устройства.
Backend автоматически поднимет Rerun gRPC на TCP 9876 и опубликует адрес в state. Ручной source вводить не требуется.
Открыть Наблюдение → Пространственная сцена. Реальные облако и траектория, частота, число точек, задержка и пропуски preview появятся после прихода сообщений K1.

В проверочном live-сеансе через этот путь прошло 80 реальных MQTT-сообщений: 38 кадров lio_pcl, 42 кадра lio_pose, 2 775 точек в последнем облаке и 0 ошибок декодирования.

Источники Rerun

Live/replay runtime автоматически назначает первый URL из примера. В Наблюдение → Пространственная сцена → Источник можно оставить ручное поле пустым либо указать другой адрес, который понимает @rerun-io/web-viewer зафиксированной в package.json версии:

rerun+http://127.0.0.1:9876/proxy
http://127.0.0.1:8080/recording.rrd
https://example.internal/recording.rrd

rerun+http://…/proxy — живой Rerun gRPC source через доступный браузеру proxy;
http(s)://…/recording.rrd — RRD-запись по HTTP(S);
версия RRD должна быть совместима с версией Web Viewer;
ручной URL хранится только в состоянии текущей страницы и имеет приоритет над автоматическим source;
ошибка запуска показывается в viewport, без подстановки фиктивных данных.

После готовности Viewer выбор Rerun entity возвращает entityPath и имя view в оболочку. Backend принимает и применяет к Rerun размер точки 0.5–12.0, режимы цвета intensity, height, distance, rgb, class, палитры Turbo, Viridis, Plasma, grayscale и custom, накопление 0–120 секунд, а также видимость облака, траектории и сетки. Значение по умолчанию — 12 секунд истории реальных кадров. Для текущего firmware-3 lio_pcl доказана только интенсивность из младшего байта rgbi; RGB используется лишь когда он действительно присутствует в декодированном формате. Custom/class сейчас означает выбранный сплошной цвет, а не готовую семантическую классификацию.

Custom timeline, переключатель 2D/3D/карты, семантические слои и сохранение RBL пока не вызывают Blueprint/playback API. Черновик компоновки фиксируется только в памяти текущей страницы и не записывается на диск.

Контракт локального API

Метод	Route	Тело / назначение
`GET`	`/api/health`	Проверка локального сервиса.
`GET`	`/api/state`	Авторитетный snapshot состояния.
`POST`	`/api/ble/scan`	`{ "duration_seconds": 6 }`.
`POST`	`/api/connect`	`{ "device_id", "ssid", "password" }`.
`POST`	`/api/session/live`	Опционально `{ "host", "duration_seconds" }`.
`POST`	`/api/session/replay`	`{ "path", "speed", "loop" }`.
`POST`	`/api/session/stop`	Остановка активного источника.
`POST`	`/api/viewer/settings`	Размер/цвет точек, накопление, видимость облака, траектории и сетки.
`WS`	`/api/events`	Периодические snapshots для live UI.

/api/state и изменяющие состояние ответы могут вернуть snapshot напрямую или как { "state": { ... } }. Текущие поля включают phase, message, devices, selected_device_id, k1_ip, source_mode, metrics, rerun_grpc_url и viewer_settings. Legacy-поля foxglove_ws_url/foxglove_viewer_url остаются пустыми. OpenAPI доступен по /api/docs.

Карта исходников frontend

Файл	Ответственность
`src/App.tsx`	Fixed shell, выбор разделов и окна source/display/layers/layout.
`src/productModel.ts`	Архитектурные разделы, рабочие поверхности и уровни готовности.
`src/workspaces/DeviceWorkspace.tsx`	Реальный K1 BLE/Wi-Fi/live/replay adapter UI.
`src/workspaces/Workspaces.tsx`	Оперативный обзор, spatial viewport и остальные продуктовые поверхности.
`src/components/RerunViewport.tsx`	Жизненный цикл встроенного Rerun Web Viewer и selection events.
`src/api.ts`	REST/WebSocket контракт с FastAPI.
`src/useK1Console.ts`	Состояние backend, polling, события и действия оператора.
`src/sceneSettings.ts`	Типизированный UI-профиль пространственной сцены.
`src/presentation.ts`	Русские подписи фаз и форматирование реальных метрик.
`src/messages.ts`	Обезличивание и локализация технических сообщений в пользовательском интерфейсе.
`src/styles.css`, `src/styles/*`	Компоновка shell и рабочих поверхностей.

Safety и чувствительные данные

Control Station и credential endpoint доступны только на loopback.
Исключение: Rerun gRPC/proxy на TCP 9876 сейчас слушает все сетевые интерфейсы, хотя автоматически возвращаемый URL содержит 127.0.0.1. На нём нет connector-level authentication или TLS. Этот порт допустим только в доверенной лабораторной LAN; его нельзя пробрасывать в публичный Интернет или cellular WAN без аутентифицированного TLS reverse proxy. Listener намеренно остаётся активным между сессиями; для его закрытия нужно остановить k1link serve.
Пароль Wi-Fi находится только в React memory, передаётся в JSON POST body, очищается после успешного ответа и не сохраняется в URL/local storage.
BLE-подключение выполняет только отдельно рассмотренную provisioning-запись; случайные GATT writes и автоматические повторы запрещены.
MQTT live/replay не публикует команды устройству. Запуск и остановка физического сканирования остаются за кнопкой K1.
Live-сессии сначала сохраняют сырые сообщения, затем формируют preview. При перегрузке preview может быть отброшен, raw evidence сохраняется.
Timeline capture_time сохраняет Unix-время приёма сообщения Mac, а окно накопления viewer использует session-local stream_time. capture_time — не доказанный timestamp сенсора K1 и не photon-to-screen latency.
Панорамный камерный поток в наблюдавшихся MQTT report topics отсутствует; текущая Rerun-сцена содержит только облако точек и позу/траекторию, а операционные метрики отображаются внешней оболочкой Control Station.
sessions/ игнорируется Git и может содержать адреса, идентификаторы, траекторию и карту помещения. В репозиторий попадают только redacted manifests и безопасная документация.

20 KiB Raw Blame History Unescape Escape