# Веб-интерфейс, кнопка и локатор

Кроме окна, с программой работают из браузера, GPIO-кнопкой и через TCP-локатор: он
отдаёт внешним программам найденные объекты и принимает скорость радара. Без экрана
(раздел «Работа без экрана») других способов нет.

## Веб-интерфейс

Веб-сервер работает внутри программы, и с окном, и без экрана. Откройте в браузере
`http://<адрес машины>:8080/`. Порт меняется переменной окружения
`RADAR_SYSTEM_WEBUI_PORT`; неверное значение заменяется на 8080. Если порт занят,
программа работает без веб-интерфейса, а ошибка (`address already in use`) видна
только в выводе процесса. Если сервер не смог запуститься по другой причине, в журнале
появляется `Failed to start web UI`.

> **Внимание.** У веб-интерфейса нет пароля и шифрования: любой, кто достаёт до
> порта по сети, управляет радаром. По адресам `/docs`, `/redoc` и `/openapi.json`
> открыто описание API. Подключайте машину только к доверенной сети.

### Страница

Верхняя строка — кнопки управления: **Start**, **Single Capture**, **Stop**,
**Capture Temporary Reference**, **Remove Last Measurement**. Они делают то же, что
одноимённые кнопки окна (глава [Окно программы](desktop.md)).

**Processor Output** — картинка с графиков окна программы. Масштабировать её в
браузере нельзя: она повторяет то, что показано в окне. В режиме B-scan над ней
список пар (**Input i / Output o**) и кнопка **Next Combination**, в режиме 3D SAR —
строка состояния 3D SAR.

Боковая панель:

| Блок | Элемент | Что делает |
| --- | --- | --- |
| **Config Profile** | список и **Load** | загружает профиль из каталога `run_configs/`, как **Load Config…**; доступна при остановленном сборе. Список читается при открытии страницы; новые файлы видны после её перезагрузки |
| | `current: <файл>` | текущий профиль |
| **Save / Record Dataset** | **Save path**, **Name (optional)** | каталог и имя набора данных; при открытии страницы берутся из окна, а сохранение и запись из браузера переписывают ими **Path** и **Name** окна (запись — и **Sweeps to record**) |
| | **Save Last 1000** | сохраняет до 1000 последних коллекций каждой стадии, как одноимённая кнопка окна |
| | **Sweeps to record** и **Start + Record to Disk** | запускает сбор и записывает на диск заданное число следующих коллекций; ниже — ход записи `recording N / M sweep(s)…` |
| **Processor Settings** | форма | настройки текущего режима обработки (ниже); заголовок сворачивает форму |
| | таблицы **Tx geometry**, **Rx geometry** | геометрия антенн в режимах GPR и 3D SAR: **−** удаляет антенну, **Add Antenna** добавляет следующую свободную |
| | **Apply** | отправляет изменённые поля |
| | **Clear Runtime History** | очищает историю, как одноимённая кнопка окна |

Нижняя строка: `running` — идёт ли сбор, `processor` — работает ли процессор,
`ring` — имя кольца результатов, `scans` — сколько коллекций в истории каждой стадии,
и признак картинки: `live` — кадры приходят, `stale` — новых кадров нет дольше 2 с
(так бывает и тогда, когда картинка просто не меняется), `no data` — кадров ещё не
было. Сообщения об успехе и ошибках всплывают на 2,6 с; ошибки — красным.

Если окно браузера уже 760 пикселей, панель уходит под картинку.

### Как выполняются действия

Каждая кнопка вызывает тот же код, что и кнопка окна, с теми же проверками. Действия
из нескольких браузеров выполняются по очереди. Если окно программы не начало
действие за 30 с, запрос отменяется
(`The desktop did not start the action in time; the request was cancelled`). Если
начало, но не закончило, браузер получает
`The desktop action is still running; check its status before retrying`, а действие
доводится до конца. Ошибки, которые возникают позже (например, на середине
однократного съёма), видны только в журнале.

### Форма настроек

Форма строится из полей окна: те же подписи, пределы и группы. В ней поле **Mode** и
поля текущего режима; смена режима сразу перестраивает форму. **Apply** отправляет
только изменённые поля, поэтому два человека, правящие разные поля, не мешают друг
другу. Порядок полей может отличаться от окна. Значения проверяются так же, как в
окне: вне пределов — `Numeric setting is outside its allowed range`, неизвестный
вариант — `Unknown setting option: …`; при ошибке не применяется ни одно поле из
отправленных. Дробное число округляется до точности поля окна. Изменения из окна
приходят в форму раз в секунду.

Только в окне программы:

- **Apply Radar**, **Load Config…** из произвольного места, **Save Config…**;
- окно **Preprocessing…**: съём и выбор наборов, калибровка по объекту;
- **Save S21 JSON**;
- секции **Radar** и **Switches**: развёртка, лазер, ключи, пары сбора;
- **Show magnitude**, **Show phase**, **Unwrap phase**, **Scans to show (stopped)**;
- журнал и его уровень, строка состояния;
- масштаб и сдвиг графиков мышью.

### Картинка и обновление

Программа снимает картинку графиков, только когда подключён хотя бы один браузер и
изображение изменилось, и не чаще 5 раз в секунду. Каждый браузер получает самую
свежую картинку, состояние и настройки; медленное соединение пропускает
промежуточные кадры. Пока окно занято синхронным съёмом (калибровка, референс),
картинка не обновляется. Браузер переподключается сам через 1,5 с после обрыва.

### API

Страница работает через HTTP API, которым можно пользоваться и из своих программ.
Тело запросов и ответов — JSON; ошибка действия — код 400 и
`{"detail": "<сообщение>"}`. Тело неверного вида (поле не того типа, нет обязательного
поля) даёт код 422 со списком ошибок в `detail`.

| Запрос | Тело | Что делает |
| --- | --- | --- |
| `GET /api/status` | — | состояние (то же, что в нижней строке страницы) |
| `POST /api/start` | — | **Start** |
| `POST /api/single_capture` | — | **Single Capture** |
| `POST /api/stop` | — | **Stop** |
| `POST /api/tmp_reference` | — | **Capture Temporary Reference** |
| `POST /api/remove_last` | — | **Remove Last Measurement** |
| `POST /api/clear_history` | — | **Clear Runtime History** |
| `GET /api/configs` | — | список профилей в `run_configs/` |
| `POST /api/load_config` | `{"name": "<файл>.json"}` | загрузить профиль |
| `POST /api/save_dataset` | `{"path": "…", "name": "…"}` | **Save Last 1000** |
| `POST /api/start_recording` | `{"path": "…", "name": "…", "count": N}` | **Start + Record to Disk**, N от 1 до 1 000 000 |
| `GET /api/live_settings` | — | описание полей формы |
| `POST /api/live_settings` | `{"<поле>": значение, …}` | применить настройки. Имена полей — из описания формы; у настроек обработки они совпадают с ключами `processing_live.json` |
| `POST /api/display_combo` | `{"input_pos": i, "output_pos": o}` | выбрать пару B-scan |
| `POST /api/next_combo` | — | **Next Combination** |
| `WS /ws` | — | поток сообщений `frame` (картинка PNG в base64), `status`, `settings` |

## GPIO-кнопка

Кнопка, подключённая к GPIO компьютера, снимает временный референс — то же, что
**Capture Temporary Reference**. Она настраивается в разделе `control_button`
профиля (глава [Файл конфигурации](configuration.md)) и читается один раз при запуске
программы.

Схема по умолчанию: кнопка между линией GPIO и землёй, внутренняя подтяжка к питанию,
нажатие — спад уровня, по одному действию на нажатие. Индикации на самой кнопке нет;
результат виден в журнале (`GPIO control button pressed: capturing tmp reference`, затем
`Tmp S21 Reference captured: …`) и на графике pass-through.

Нажатие, пришедшее, пока программа останавливает сбор перед съёмом, отбрасывается
(`Tmp reference capture already in progress; ignoring duplicate request`). Нажатие во
время самого съёма ждёт его конца и запускает ещё один съём. Ошибки съёма только
записываются в журнал, окон с ошибкой кнопка не
открывает. Если настройки неполные, кнопка не включается
(`GPIO control button configuration is incomplete or unsupported; watcher not started`).
Если линию не удалось открыть — `Failed to start GPIO control button watcher`; если
наблюдение за линией прервалось — `GPIO control button watcher stopped: …`. В обоих
случаях программа работает дальше без кнопки до перезапуска.

## TCP-локатор

Локатор — TCP-сервер внутри процессора. Он отдаёт подключившимся программам объекты,
найденные режимом GPR, и принимает от них скорость радара для поправки на движение.
Настройки — раздел `run.locator_server` профиля; по умолчанию порт 8888 на всех
интерфейсах. Сервер работает, пока работает процессор: от первого **Start** до
закрытия программы или перезапуска процессора. **Stop**, временный референс и
пересчёт B-scan процессор и локатор не останавливают.

Обмен в обе стороны идёт пакетами: заголовок из 8 байт — номер устройства и длина
данных (оба uint32, младший байт первым), затем текст JSON в UTF-8.

Пакет от радара:

```text
03 00 00 00 71 00 00 00
{"obs":[{"crs":0.3,"dst":4.3},{"crs":-1.0,"dst":6.0},{"crs":1.0,"dst":2.0}],"sts":1,"tim":"13:42:25.058","ver":1}
```

| Поле | Что это |
| --- | --- |
| `obs` | объекты: `crs` — координата X (вдоль ряда антенн, поперёк направления обзора), `dst` — дальность (Z), метры, округлены до 0,1 м |
| `sts` | всегда 1 |
| `tim` | местное время сборки пакета `ЧЧ:ММ:СС.ммм` (не время съёма) |
| `ver` | `run.locator_server.protocol_version` |

В заголовке — `run.locator_server.device_id`. Пакет уходит после обработки каждой
новой коллекции в любом режиме; вне режима GPR и без объектов список `obs` пуст.
Объекты — те же, что видны на графике GPR: внутри окна видимости, после отбора по
числу и фильтра приближения. При пересчёте после смены настроек уходит пакет только
для новейшей коллекции. Новый клиент сразу получает последний отправленный пакет.

Пакет к радару — скорость в м/с:

```text
00 00 00 00 0c 00 00 00
{"vlc":1.25}
```

Остальные поля и номер устройства в заголовке не читаются. Скорость считается свежей
5 с после прихода. Пока она свежая и на странице GPR или 3D SAR выключена
**Ignore socket speed**, она заменяет скорость из поля, а её изменение пересчитывает
новейшую коллекцию в GPR и 3D SAR. Использованная скорость сохраняется в каждом
результате.

Клиентов может быть несколько; у каждого очередь на `client_queue_size` пакетов (по
умолчанию 32), при переполнении выбрасываются старые. Клиент, который 5 с не принимает
данные или прислал пакет больше `max_payload_bytes` (по умолчанию 65 536 байт),
отключается. Сообщения локатора пишутся в
`python_app/runtime/logs/data_processor.err.log`; если порт занят, процессор работает
без локатора и пишет туда же `locator server disabled`.

## Работа без экрана

На машине без оператора (Raspberry Pi) программу запускает служба systemd
`radar.service` (установка — в главе [Установка и запуск](installation.md)). Она
запускает `./start.sh --headless --skip-build`: окно не показывается, через 0,5 с
выполняется **Apply Radar**, ещё через 1 с — **Start**, даже если **Apply Radar** не
удался. Если **Start** не удался, программа завершается, и systemd запускает её
снова через 3 с.

Профиль служба берёт последний использованный (из
`python_app/runtime/gui_session_state.json`), а если его нет — корневой
`run_config.json`, то есть симулятор. Поэтому перед установкой службы загрузите или
сохраните на машине нужный профиль. Если запомненный профиль не читается, программа
пишет `Failed to load the last selected config profile; falling back to root run_config.json.`,
берёт корневой профиль и запоминает уже его: исправленный профиль нужно загрузить снова.

| Канал | Для чего |
| --- | --- |
| браузер, `http://<машина>:8080/` | запуск и остановка, временный референс, сохранение данных, профили из `run_configs/`, настройки обработки |
| GPIO-кнопка | временный референс |
| TCP-локатор, порт 8888 | объекты и скорость |
| `sudo systemctl start` / `stop` / `restart radar.service` | управление службой |
| `journalctl -u radar.service -f` | журнал службы |

Без экрана нет окон с ошибками: всё пишется в журнал. Окно калибровки и
**Save Config…** без экрана недоступны: калибровку снимайте, запустив окно программы
на той же машине. При запуске окна `./start.sh` сначала останавливает службу; после
закрытия окна она сама не запускается.

Если процесс конвейера упал, программа перезапускает конвейер: первый раз сразу,
следующие подряд — не раньше чем через 6, 12, 24, 48, затем 60 с после предыдущей
попытки; когда данные снова пошли, счёт начинается заново. После 400 подряд ошибок чтения
колец конвейер останавливается и сам уже
не запускается: нажмите **Start** в браузере.