MeshCoreTel-firmware/meshcoretel-docs/web-panel.md

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

Эта страница предназначена для конечных пользователей, использующих сборку 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` (Объявление)
- `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, которые принимает ретранслятор

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

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

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

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

## Обновление прошивки (OTA)

Этот раздел позволяет безопасно загружать прошивку на устройство по Wi-Fi.

Чтобы перепрошить устройство, нажмите на поле выбора файла и выберите файл прошивки с расширением `.bin`, при этом кнопка `Upload` активируется.
Нажмите кнопку `Upload` и после подтверждения начнётся загрузка прошивки с индикацией в процентах.

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

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

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

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

Примечания:

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

## Режим скрытого узла (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`: заряд батареи, свободная память, пакетная активность (RX/TX в виде составного графика), частота ошибок приёма (RX error rate), сигнал, уровень шума, загрузка ядра процессора, температура MCU (с цветовой индикацией теплового порога) и, если включён GPS, спутники; карточки графиков показывают диапазон `min`/`max`, подсветка при наведении синхронизирована по всем графикам
- `Neighbours`: текущая таблица соседей с ID, SNR, возрастом последнего приёма и возрастом объявления
- `Events`: события текущей загрузки/сессии

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

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

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

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

1. сводка / статус
2. батарея
3. память
4. пакетная активность
5. частота ошибок приёма
6. загрузка ядра процессора
7. сигнал
8. спутники, когда 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. Откройте панель
2. Найдите `Firmware Update` и нажмите на поле выбора файла
3. Выберите файл с прошивкой `.bin`
4. Нажмите `Upload` и подтвердите действие
5. Дождитесь загрузки прошивки и перезагрузки устройства

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

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)