Moved docs and workflows to avoid conflicts while merging official repo
Этот коммит содержится в:
Valentin V. Bartenev
@@ -0,0 +1,394 @@
|
||||
# Веб-панель ретранслятора
|
||||
|
||||
Эта страница предназначена для конечных пользователей, использующих сборку MeshCoreTel-firmware с включённой локальной веб-панелью.
|
||||
|
||||
Здесь описано, как открыть панель, за что отвечает каждый раздел и чего ожидать при использовании на компьютере или мобильном устройстве.
|
||||
|
||||
## Что это такое
|
||||
|
||||
Веб-панель ретранслятора — это локальная страница конфигурации по HTTPS, обслуживаемая непосредственно самим ретранслятором через Wi-Fi.
|
||||
|
||||
Она предоставляет:
|
||||
|
||||
- защищённую паролем страницу локального администратора по адресу `/app`
|
||||
- отдельную страницу статистики и трендов по адресу `/stats`
|
||||
- быстрые команды `get` для типовых проверок ретранслятора и MQTT
|
||||
- панель CLI в стиле терминала для полного доступа к командной строке ретранслятора
|
||||
- редактируемые настройки ретранслятора
|
||||
- редактируемые настройки MQTT
|
||||
- исторический обзор статистики с трендами, соседями и недавними событиями
|
||||
|
||||
Рекомендации по использованию:
|
||||
|
||||
- используйте панель для первоначальной настройки, эпизодических изменений конфигурации и устранения неполадок
|
||||
- после завершения работы отдавайте предпочтение команде `set web off` на MQTT-ретрансляторах, где важен максимальный запас ресурсов
|
||||
- это оставляет больше памяти, доступной для работы MQTT/WSS, особенно в конфигурациях с двумя WSS-брокерами
|
||||
|
||||
## Обзор скриншотов
|
||||
|
||||
Скриншоты ниже показывают текущее разделение на облегчённую страницу администратора `/app` и отдельную страницу статуса `/stats`.
|
||||
|
||||
### Скриншот `/app`
|
||||
|
||||
|
||||
|
||||
|
||||
### Скриншот `/stats`
|
||||
|
||||
|
||||
|
||||
|
||||
## Требования
|
||||
|
||||
Вам потребуется:
|
||||
|
||||
- поддерживаемая сборка прошивки 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)
|
||||
Ссылка в новой задаче
Block a user