# Веб-панель ретранслятора

Эта страница предназначена для конечных пользователей, использующих сборку MeshCoreTel-firmware с включённой локальной веб-панелью.

Здесь описано, как открыть панель, за что отвечает каждый раздел и чего ожидать при использовании на компьютере или мобильном устройстве.

## Что это такое

Веб-панель ретранслятора — это локальная страница конфигурации по HTTPS, обслуживаемая непосредственно самим ретранслятором через Wi-Fi.

Она предоставляет:

- защищённую паролем страницу локального администратора по адресу `/app`
- отдельную страницу статистики и трендов по адресу `/stats`
- быстрые команды `get` для типовых проверок ретранслятора и MQTT
- панель CLI в стиле терминала для полного доступа к командной строке ретранслятора
- редактируемые настройки ретранслятора
- редактируемые настройки MQTT
- исторический обзор статистики с трендами, соседями и недавними событиями

Рекомендации по использованию:

- используйте панель для первоначальной настройки, эпизодических изменений конфигурации и устранения неполадок
- после завершения работы отдавайте предпочтение команде `set web off` на MQTT-ретрансляторах, где важен максимальный запас ресурсов
- это оставляет больше памяти, доступной для работы MQTT/WSS, особенно в конфигурациях с двумя WSS-брокерами

## Обзор скриншотов

Скриншоты ниже показывают текущее разделение на облегчённую страницу администратора `/app` и отдельную страницу статуса `/stats`.

### Скриншот `/app`

![Обзор веб-панели ретранслятора `/app`](./_assets/repeater_web_panel_app_light.webp#only-light)
![Обзор веб-панели ретранслятора `/app`](./_assets/repeater_web_panel_app_dark.webp#only-dark)

### Скриншот `/stats`

![Обзор веб-панели ретранслятора `/stats`](./_assets/repeater_web_panel_stats_light.webp#only-light)
![Обзор веб-панели ретранслятора `/stats`](./_assets/repeater_web_panel_stats_dark.webp#only-dark)

## Требования

Вам потребуется:

- поддерживаемая сборка прошивки MeshCoreTel
- настроенный Wi-Fi на ретрансляторе
- ретранслятор, подключённый к вашей локальной сети
- пароль администратора ретранслятора

На некоторых платформах с ограниченными ресурсами веб-панель отключена, чтобы уложиться в лимиты флеш-памяти. Если ваше устройство её не поддерживает, `get web.status` не покажет её как доступную.

## Как открыть панель

1. Подключите ретранслятор к Wi-Fi.
2. Узнайте его IP-адрес.
3. Откройте `https://<IP-репитера>/` в браузере.
4. Примите предупреждение браузера о самоподписанном сертификате.
5. Введите пароль администратора ретранслятора.

Полезные команды CLI:

- `get wifi.status`: показывает состояние Wi-Fi и IP-адрес при подключении.
- `get web.status`: показывает, запущена ли веб-панель и по какому URL она доступна.

Пример:

- `https://10.33.135.208/`

## Вход и безопасность

- панель использует тот же пароль администратора, что и CLI ретранслятора
- соединение по HTTPS, но сертификат самоподписанный
- браузеры будут выдавать предупреждение при первом подключении
- после входа панель открывает доступ к CLI ретранслятора

Панель предназначена для локального администрирования в доверенной сети и не рассчитана на использование в открытом интернете.

## Замечания по производительности

Панель использует HTTPS и расходует память. На устройствах, работающих с одним или двумя WSS MQTT-брокерами, открытие панели уменьшает запас ресурсов для MQTT, пока сессия активна.

Рекомендуемая практика для развёртывания ретрансляторов:

- включайте панель для первоначальной настройки
- используйте её снова для периодических проверок или устранения неполадок
- отключайте командой `set web off` после завершения, чтобы у MQTT был максимальный запас ресурсов

## Навигация и действия

Веб-панель состоит из двух основных страниц:

- `/app`: облегчённый вид для управления и конфигурации
- `/stats`: текущий статус, тренды, соседи и недавние события

Обе страницы имеют одинаковую верхнюю навигацию и служебные действия.

### `/app`

Страница `/app` — это основной интерфейс администратора и конфигурации.

Она включает:

- навигацию: `App` и `Stats`
- `Advert` (Объявление)
- `Start OTA` (Запустить OTA)
- `Reboot` (Перезагрузка)
- переключатель темы
- `Logout` (Выход)

Используйте `Start OTA` только тогда, когда намереваетесь обновить прошивку дистанционно.

### `/stats`

Страница `/stats` — это раздел для текущего статуса и хронологии данных.

Она включает:

- навигацию: `App` и `Stats`
- `Refresh` (Обновить)
- `Reboot` (Перезагрузка)
- переключатель темы
- `Logout` (Выход)

## Быстрые команды "get"

Этот раздел выполняет стандартные команды только для чтения для:

- Wi-Fi
- MQTT

Они удобны для быстрых проверок без ввода команд в поле CLI. Быстрые действия MQTT включают `mqtt.status`, `mqtt.client_version`, `mqtt.iata`, `mqtt.owner` и `mqtt.email`.

## Выполнение команд CLI

Это мини-терминал для CLI ретранслятора.

- нажмите `Enter`, чтобы выполнить команду
- история команд отображается в окне терминала ниже
- кнопки сохранения в других местах страницы также показывают сгенерированную команду и ответ здесь
- здесь доступна команда `clock`, если нужно узнать текущее время платы ретранслятора
- авторизованные сессии могут выполнять те же команды CLI, которые принимает ретранслятор

Это позволяет легко увидеть, что именно панель отправила ретранслятору.

## Настройки ретранслятора

Этот раздел включает:

- Имя устройства (Device Name)
- UTC часы (Clock UTC)
- Широта (Latitude)
- Долгота (Longitude)
- Гостевой пароль (Guest Password)
- Приватный ключ (Private Key)
- Интервал объявлений (Advert Interval)
- Интервал массовой рассылки (Flood Interval)
- Макс. массовых сообщений (Flood Max)
- Информация о владельце (Owner Info)

Примечания:

- `Latitude` и `Longitude` по умолчанию равны `0.0` как заполнители
- изменение приватного ключа требует перезагрузки для применения
- кнопки обновления загружают текущее значение с ретранслятора
- кнопки сохранения немедленно отправляют соответствующую команду CLI

## Информация

В этом разделе отображается:

- `Version`: версия прошивки с датой сборки
- `Client Version`: строка версии MQTT-клиента
- `Public Key` (Публичный ключ)

## Режим скрытого узла (Ghost Node Mode)

Режим скрытого узла — это удобный элемент управления на `/app` для ретранслятора, который должен оставаться в Wi-Fi и MQTT, но не должен активно вести себя как ещё один близлежащий ретранслятор.

Типичный сценарий использования:

- комнатный или расположенный рядом MQTT-наблюдатель, когда другой ретранслятор поблизости уже выполняет радио-ретрансляцию
- узел, который должен передавать данные MQTT, веб-статус и диагностику, не добавляя лишнего ретрансляционного трафика или объявлений

При включении Режим скрытого узла:

- выключает `repeat`
- устанавливает `advert.interval` в `0`
- устанавливает `flood.advert.interval` в `0`
- оставляет локальную веб-панель и функции MQTT работающими

При отключении панель восстанавливает предыдущие настройки повтора и объявлений, если они ещё известны из текущей сессии браузера. Если нет, она возвращается к:

- `repeat on`
- `advert.interval 60`
- `flood.advert.interval 12`

Этот режим полезен, когда нужно, чтобы устройство наблюдало и публиковало данные, а не действовало как дополнительный передающий ретранслятор. Он не создаёт отдельную роль прошивки; это просто сгруппированное сокращение в веб-панели для существующих настроек.

## Настройки MQTT

Этот раздел включает:

- `mqtt.iata`: выбирается из подготовленного списка.
- `mqtt.owner`: публичный ключ владельца.
- `mqtt.email`: контактный email владельца.
- Переключатели MQTT-брокеров: `meshcoretel`, `letsmesh-eu` и `letsmesh-us`.

`UNSET - To be configured` — значение по умолчанию для новых установок MQTT ретранслятора, пока не появится реальное сохранённое значение.

Примечания:

- если `mqtt.iata` имеет значение `UNSET`, панель показывает баннер вверху с напоминанием задать его в разделе MQTT Settings
- пока `mqtt.iata` имеет значение `UNSET`, включённые MQTT-брокеры не пытаются подключиться
- состояние MQTT-брокер загружается при открытии страницы
- вы можете включать или выключать каждый MQTT-брокер из этой панели
- включить можно не более двух MQTT-брокеров одновременно

## Обзор `/stats`

Страница статистики загружается отдельно от `/app` и предназначена для того, чтобы основная страница администратора оставалась легче.

Страница `/stats` в настоящее время показывает:

- `Services`: MQTT, web, архив, количество соседей и, если SD-карта смонтирована, ёмкость карты и архива
- опциональную полноширинную сводную карточку `Environment` на платах, передающих GPS или данные телеметрии окружающей среды
- `Trends`: заряд батареи, свободная куча, пакетная активность, сигнал, уровень шума и, если включён GPS, спутники
- `Neighbours`: текущая таблица соседей с ID, SNR, возрастом последнего приёма и возрастом объявления
- `Events`: события текущей загрузки/сессии

Для устройств, передающих дополнительную телеметрию, опциональная сводная карточка `Environment` может показывать текущие значения, такие как состояние GPS-фиксации, широту, долготу, высоту по GPS, напряжение, температуру с датчика, влажность, давление, высоту по давлению и температуру MCU.

Метрики, не имеющие текущего значения, скрываются, а не показывают строки-заполнители, поэтому карточки меняются в зависимости от устройства и текущего состояния датчиков.

Индикатор батареи `Core` предпочитает отображаемый устройством процент заряда, если устройство его предоставляет. На таких устройствах детализация показывает только текущее напряжение батареи в милливольтах. В противном случае отображаемый процент вычисляется из настроенного диапазона напряжения батареи устройства, и этот диапазон показывается в детализации, а не предполагается фиксированный одноэлементный диапазон `3000-4200 мВ`.

Графики трендов загружаются последовательно, а не одним большим пакетом:

1. сводка / статус
2. батарея
3. память
4. пакетная активность
5. сигнал
6. спутники, когда GPS включён

Это позволяет снизить потребление памяти как на стороне браузера, так и на устройстве по сравнению с предыдущим внутристраничным просмотром статистики.

Если `web.stats` включён и SD-архив смонтирован, тренды могут восстанавливать архивные сводные точки после перезагрузки из последнего снимка на SD. Недавние актуальные точки по-прежнему добавляются из истории в памяти.

### Объём истории статистики

Сэмплы статистики собираются раз в минуту.

Текущие лимиты истории в памяти:

| Класс устройства                 | Лимит сэмплов | Лимит событий | Период истории       |
| -------------------------------- | ------------: | ------------: | -------------------------- |
| Без PSRAM                        |           `24` |            `8` | Только недавняя оперативная история |
| Менее `4 Мб` PSRAM               |          `240` |           `96` | Примерно `4` часа          |
| От `4 Мб` до менее `8 Мб` PSRAM  |          `480` |          `192` | Примерно `8` часов         |
| `8 Мб` PSRAM или больше          |          `720` |          `288` | Примерно `12` часов        |

На устройствах с объёмом PSRAM примерно от `2 Мб` и выше история статистики начинает записываться с момента загрузки, когда `web.stats` включён, даже если `/stats` ещё не открывали.

Для восстановления из архива требуется включённый `web.stats` и смонтированная SD-карта на платах, которые поддерживают архивацию на MeshCoreTel-firmware.

Основное назначение SD-карты — позволить ретранслятору сохранять и восстанавливать историю для `/stats`. Архив хранит файлы снимков `.latest` для быстрого восстановления и ежедневные файлы `.log` с датой по UTC для долгосрочной истории. В качестве дополнительной опции эти файлы также можно извлечь и проанализировать на компьютере для более глубокого ручного анализа.

На устройствах без PSRAM `/stats` всё ещё может показывать недавние графики, пока активен просмотр статистики, но история меньше и не поддерживает такое же поведение с резервным копированием в архив, как на платах с PSRAM.

Полезные команды CLI:

- `set web.stats on`
- `set web.stats off`
- `get web.stats.status`

## Использование на мобильных устройствах

Страница адаптивна и должна корректно работать на телефоне.

На мобильных устройствах:

- кнопки быстрых команд сворачиваются в двухколоночный макет
- верхняя навигация и группы действий остаются компактными и удобными для касаний
- строки ввода остаются пригодными для сенсорного взаимодействия
- карточки трендов перестраиваются в одноколоночные секции, где это необходимо

## Типовые задачи

### Проверка Wi-Fi и MQTT

1. Откройте панель.
2. Нажмите `wifi.status` в быстрых командах `get`.
3. Нажмите `mqtt.status` в быстрых командах `get`.
4. Откройте `/stats` из верхней навигации для просмотра истории статистики.

### Изменение имени устройства

1. Отредактируйте `Device Name`.
2. Нажмите `Save`.
3. Проверьте сгенерированную команду и ответ в окне терминала CLI.

### Обновление MQTT Owner или Email

1. Перейдите в `MQTT Settings`.
2. Введите новое значение.
3. Нажмите `Save`.
4. Используйте кнопку обновления, если хотите перечитать сохранённое значение с ретранслятора.

### Запуск OTA

1. Нажмите `Start OTA`.
2. Подтвердите действие.
3. Локальный HTTP-редирект на порту `80` освобождается, чтобы OTA мог занять этот порт.
4. Продолжите стандартную процедуру OTA.

### Использование истории статистики

1. При необходимости включите статистику командой `set web.stats on`.
2. Откройте `/stats` из верхней навигации.
3. Проверьте `Services` на предмет состояния архива и среды выполнения.
4. Просмотрите `Trends` для недавней истории графиков.
5. Используйте `Refresh` для перезагрузки страницы статистики.

## Устранение неполадок

### Браузер предупреждает о сертификате

Это ожидаемо. Панель использует самоподписанный сертификат, сгенерированный для локального использования.

### Не могу открыть страницу

Проверьте:

- подключён ли ретранслятор к Wi-Fi
- IP-адрес из `get wifi.status`
- `get web.status` сообщает, что панель запущена
- ваше устройство / сборка прошивки поддерживает веб-панель

### Панель открывается, но не удаётся войти

Используйте пароль администратора ретранслятора, а не гостевой пароль.

### MQTT становится нестабильным при входе

Веб-панель загружает настройки посекционно, чтобы снизить нагрузку при запуске, но HTTPS всё ещё потребляет внутреннюю память.

Проверьте:

- сколько MQTT-брокеров включено (один или два)
- `memory` до и после входа
- улучшается ли стабильность после `set web off`

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

### Открывается HTTP вместо HTTPS

Ретранслятор перенаправляет простые запросы `http://` на локальный URL панели `https://`. Если браузер всё ещё показывает проблему с подключением после перенаправления, откройте `https://<repeater-ip>/` напрямую и сначала примите предупреждение о самоподписанном сертификате.

### Статистика или настройки не обновляются

Попробуйте:

- обновить вкладку браузера
- использовать `Refresh` на `/stats`
- выйти и войти снова
- проверить стабильность Wi-Fi с помощью `get wifi.status`

### `/stats` недоступна

Проверьте:

- `get web.status`
- `get web.stats.status`
- была ли применена команда `set web.stats on`

Если `web.stats` выключен, `/stats` останется отключённой, и запросы истории графиков выполняться не будут.

## Связанная документация

- [Пользовательские команды CLI](./custom-cli.md)
- [Загрузка и прошивка релизов](./releases.md)
- [Локальная сборка с помощью uv](./local-builds.md)