refactor: rebrand to PosadMesh, translate docs to Russian, drop legacy brokers

posadmesh-docs/custom-cli.md

@@ -0,0 +1,313 @@
+# Собственные команды CLI
+
+Эта страница описывает команды CLI, специфичные для PosadMesh, добавленные в этом репозитории.
+
+Она не пытается повторять весь набор команд CLI апстримного MeshCore.
+
+## С чего начать
+
+Если вы выполняете первичную настройку, вот команды, которые нужны большинству пользователей прежде всего:
+
+```text
+set wifi.ssid <your-ssid>
+set wifi.pwd <your-password>
+get wifi.status
+set mqtt.iata <code>
+get mqtt.status
+```
+
+Для обсерверов с локальной веб-панелью также полезны:
+
+```text
+set web on
+get web.status
+set web off
+```
+
+Используйте `set web on` при настройке или диагностике, а затем `set web off`, когда стационарному обсерверу нужен максимальный запас памяти.
+
+## Команды обсервера
+
+Эти команды доступны в таргетах прошивки `*_repeater_observer`.
+
+Команды `get` без аргументов нужно вводить точно так, как показано.
+
+### Статус и маршрутизация MQTT
+
+- `get mqtt.status`: показывает состояние Wi-Fi, NTP, IATA, эндпоинта, транспорт пользовательского эндпоинта, состояние публикации статуса, состояние TX и `leaked:<n>` (MQTT-клиенты, намеренно оставленные неосвобождёнными после сбоя целостности heap при завершении; должно оставаться `0`).
+- `get mqtt.statuscfg`: показывает, включены ли периодические сообщения статуса, в виде простого значения `on` или `off`. Большинству пользователей достаточно `get mqtt.status`.
+- `get mqtt.client_version`: показывает строку MQTT `client_version`, публикуемую репитером.
+- `get mqtt.client_env`: показывает окружение PlatformIO, использованное для сборки прошивки репитера.
+- `get mqtt.iata`: показывает код IATA/местоположения, используемый в топиках MQTT.
+- `set mqtt.iata <code>`: задаёт код IATA/местоположения, например `MEL`.
+- `set mqtt.iata UNSET`: помечает MQTT IATA как ещё не настроенный. Пока он `UNSET`, включённые MQTT-брокеры остаются отключёнными, пока не будет сохранён реальный код.
+
+### Идентификация MQTT
+
+- `get mqtt.owner`: показывает настроенный публичный ключ владельца.
+- `set mqtt.owner <64-hex-char-public-key>`: задаёт публичный ключ владельца, используемый в метаданных JWT.
+- `mqtt.owner <64-hex-char-public-key>`: сокращённая форма для задания публичного ключа владельца.
+- `get mqtt.email`: показывает настроенный email владельца.
+- `set mqtt.email <email>`: задаёт email владельца, используемый в метаданных JWT.
+- `mqtt.email <email>`: сокращённая форма для задания email владельца.
+
+### Управление сообщениями MQTT
+
+- `get mqtt.packets`: показывает, публикуются ли сообщения с пакетами.
+- `set mqtt.packets on|off`: включает или отключает публикацию пакетов.
+- `get mqtt.raw`: показывает, публикуются ли необработанные payload пакетов.
+- `set mqtt.raw on|off`: включает или отключает отдельный топик MQTT `raw`.
+- `set mqtt.status on|off`: включает или отключает периодическую публикацию статуса MQTT.
+- `get mqtt.tx`: показывает, включаются ли пакеты TX.
+- `set mqtt.tx on|off`: включает или отключает публикацию пакетов TX.
+
+### Эндпоинты MQTT
+
+- `get mqtt.meshcoretel`
+- `set mqtt.meshcoretel on|off`
+- `get mqtt.custom`
+- `set mqtt.custom on|off`
+- `get mqtt.custom.host`
+- `set mqtt.custom.host <host>`
+- `get mqtt.custom.port`
+- `set mqtt.custom.port <port>`
+- `get mqtt.custom.transport`: показывает `tcp` или `wss`.
+- `set mqtt.custom.transport tcp|wss`
+- `get mqtt.custom.username`
+- `set mqtt.custom.username <username>`
+- `get mqtt.custom.password`: показывает `set`, когда пользовательский пароль настроен.
+- `set mqtt.custom.password <password>`
+
+Примечания:
+
+- новые установки обсерверов по умолчанию задают для `mqtt.iata` значение `UNSET`
+- одновременно можно включить максимум два MQTT-брокера
+- если `mqtt.iata` имеет значение `UNSET`, включённые MQTT-брокеры не подключатся
+- пользовательский MQTT использует настроенные имя пользователя и пароль, а не аутентификацию JWT
+- пользовательский MQTT по умолчанию использует TCP; задайте `mqtt.custom.transport wss` для MQTT через защищённые WebSockets с фиксированным путём websocket `/mqtt` и корневым набором сертификатов CA x509 из ESP-IDF
+- `get mqtt.status` выводит `> wifi:<up|down> ntp:<up|wait> iata:<code> meshcoretel:<state> custom:<transport>:<state> status:<on|off> tx:<on|off>`; состояния брокера: `up` (подключён), `conn` (подключение), `wait` (нет Wi-Fi или синхронизации времени), `backoff`, `retry`, `unconfigured`, `invalid iata` или `off`
+- пользовательский MQTT использует те же топики `meshcore/<IATA>/<device>/<leaf>`, что и курируемые брокеры
+- выключение подключённого брокера публикует retained-обновление статуса MQTT с `"status":"offline"` перед отключением клиента
+- изменение `mqtt.iata` относительно настроенного значения также публикует retained offline-статус в старый топик статуса, перезапускает подключённые клиенты брокеров и переподключается по новому пути топика
+
+Также принимаются устаревшие алиасы с точками:
+
+- `mqtt.meshcoretel.ru`
+
+### Настройки Wi-Fi для обсерверов
+
+- `get wifi.status`: показывает SSID, состояние подключения, необработанный код статуса Wi-Fi, IP, канал и уровень сигнала при подключении, а также состояние шлюза (`gw:ok|lost`) и счётчик переподключений сторожевым таймером (`wd:<n>`).
+- `get wifi.ssid`: показывает настроенный SSID Wi-Fi.
+- `set wifi.ssid <ssid>`: задаёт SSID Wi-Fi.
+- `set wifi.pwd <password>`: задаёт пароль Wi-Fi.
+- `get wifi.powersaving`: показывает текущий режим энергосбережения Wi-Fi.
+- `set wifi.powersaving none|min|max`: задаёт режим энергосбережения Wi-Fi.
+- `wifi reconnect`: разрывает текущее соединение и переподключается с полным сканированием каналов. Используйте, когда узел сообщает о подключении, но недоступен по сети.
+
+Обсерверы также используют сторожевой таймер связи: пока Wi-Fi сообщает о подключении, узел каждые 30 секунд проверяет свой шлюз через ARP. Если шлюз молчит 3 минуты (например, точка доступа, которая продолжает рассылать beacon после потери проводного аплинка), узел сам принудительно выполняет полное переподключение, увеличивая интервал между попытками вплоть до 48 минут, пока сбой не прекратится. `wd:<n>` в `get wifi.status` считает такие принудительные переподключения с момента загрузки.
+
+### Настройки NTP для обсерверов
+
+- `get ntp.server1`: показывает основной NTP-сервер.
+- `get ntp.server2`: показывает дополнительный NTP-сервер.
+- `get ntp.server3`: показывает третий NTP-сервер.
+- `set ntp.server1 <host>`: задаёт основной NTP-сервер и перезапускает синхронизацию времени.
+- `set ntp.server2 <host>`: задаёт дополнительный NTP-сервер и перезапускает синхронизацию времени.
+- `set ntp.server3 <host>`: задаёт третий NTP-сервер и перезапускает синхронизацию времени.
+
+Серверы по умолчанию: `au.pool.ntp.org`, `time.google.com` и `time.cloudflare.com`.
+
+### Настройки моста ESP-NOW для сборок Observer ESP-NOW
+
+Эти команды доступны в таргетах прошивки `*_repeater_observer_espnow`, использующих транспорт моста ESP-NOW.
+
+Команды моста предназначены для локального использования моста ESP-NOW между близко расположенными репитерами, например для связи репитеров в `Australia (Narrow)` и `Australia (Mid)`. Это не элементы управления MQTT-over-WAN, VPN или интернет-мостом.
+
+- `get bridge.channel`: показывает настроенный канал моста ESP-NOW.
+- `set bridge.channel <channel>`: задаёт канал моста ESP-NOW и перезапускает мост. Используйте значение от `1` до `14`.
+- `get bridge.secret`: показывает настроенный секрет моста ESP-NOW.
+- `set bridge.secret <secret>`: задаёт общий секрет моста ESP-NOW и перезапускает мост.
+
+После выполнения `set bridge.channel` ожидайте кратковременного разрыва соединения моста и веб-панели, пока радио перезапускается. В текущих сборках observer ESP-NOW это может выглядеть как перезагрузка платы.
+
+В сборках `*_repeater_observer_espnow`, подключённых к Wi-Fi, канал моста ESP-NOW должен совпадать с активным каналом Wi-Fi 2,4 ГГц:
+
+1. Выполните `get wifi.status`.
+2. Считайте значение `channel:<n>` из статуса подключённого Wi-Fi.
+3. Выполните `get bridge.channel`.
+4. Если значения различаются, выполните `set bridge.channel <n>`, подставив значение канала Wi-Fi.
+5. Используйте одинаковые `bridge.channel` и `bridge.secret` на каждом узле моста ESP-NOW, которые должны взаимодействовать друг с другом.
+
+Пример:
+
+```text
+> get wifi.status
+> ssid:EastMesh-IoT status:connected code:3 state:connected ip:192.168.1.50 channel:6 rssi:-61 quality:78% signal:good gw:ok wd:0
+> get bridge.channel
+> 1
+> set bridge.channel 6
+OK
+```
+
+### Элементы управления веб-панели
+
+- `get web`
+- `get web.status`: показывает, доступна ли локальная HTTPS-панель, а также `heals:<n>` (сколько раз панель перезапускалась из-за слишком сильной фрагментации внутреннего heap для TLS-рукопожатия) и `deferred:<n>` (попытки запуска, отложенные до восстановления запаса heap).
+- `get web.stats.status`: показывает, включены ли выделенная страница статистики и подсистема истории, активна ли последняя история, доступна ли история в PSRAM и смонтирован ли архив на SD. Когда это включено, сбор истории теперь охватывает и поддерживаемую телеметрию окружающей среды, а не только исходные серии по батарее и радио. Платы с активным GPS также записывают поминутные выборки по спутникам для исторического вида `/stats`. Если доступ к архиву пропадает, пока статистика остаётся включённой, репитер периодически повторяет монтирование SD.
+- При загрузке восстановление статистики из архива использует ограниченное чтение последней сводки, событий и снимков соседей, чтобы повреждённые или неожиданно большие файлы архива не задерживали запуск MQTT или веб-панели.
+- `set web on|off`
+- `set.web on|off`: включает или отключает локальную HTTPS-панель.
+- `set web.stats on|off`
+- `set.web.stats on|off`: включает или отключает выделенную страницу `/stats` и сбор исторической статистики.
+- `purge sd`: удаляет файлы и каталоги из смонтированного архива на SD-карте, затем заново создаёт пустой каталог архива `/stats`, чтобы сбор статистики во время работы мог продолжаться. Это не стирает внутреннюю файловую систему репитера или сохранённые настройки.
+
+### Диагностика во время работы
+
+- `memory`: показывает текущее использование heap и PSRAM.
+- `stats-core`: показывает батарею, время работы, счётчик неустранимых ошибок и глубину очереди исходящих.
+- `stats-radio`: показывает уровень шума радио, последний RSSI, последний SNR и время в эфире TX/RX.
+- `stats-packets`: показывает суммарные значения приёма/передачи пакетов, разбивку flood/direct и ошибки приёма.
+
+> Если `noise_floor` показывает `0`, проверьте `get agc.reset.interval`; если значение не `0`, попробуйте `set agc.reset.interval 0` и проверьте снова.
+
+### Лимит пересылки flood
+
+- `get flood.max.unscoped`: показывает лимит хопов для неограниченных flood-пакетов.
+- `set flood.max.unscoped <0-64>`: задаёт лимит хопов для неограниченных flood-пакетов.
+- `get flood.max.advert`: показывает лимит хопов для flood-пакетов advert.
+- `set flood.max.advert <0-64>`: задаёт лимит хопов для flood-пакетов advert.
+
+В сборках обсерверов `flood.max.unscoped` по умолчанию равен `64`. Меньшие значения могут ограничить, как далеко повторяется неограниченный flood-трафик, тогда как пересылка scoped/region flood остаётся под управлением `flood.max`.
+
+### Отчётность о батарее платы
+
+- В сборках обсерверов фоновый опрос батареи, используемый для истории MQTT/статуса, ограничен примерно одним разом в минуту. Явные запросы статуса и телеметрии по-прежнему обновляют показание сразу.
+
+### Управление вентилятором T-Beam 1W
+
+Эти команды доступны только в сборках репитера `LilyGo_TBeam_1W_*`.
+
+- `get fan`: показывает текущий режим вентилятора, текущее состояние вентилятора и последнюю температуру платы по NTC, когда она доступна.
+- `set fan auto`: возвращает вентилятор к автоматическому управлению и сохраняет этот режим после перезагрузки.
+- `set fan on`: принудительно включает вентилятор и сохраняет этот режим после перезагрузки.
+- `set fan off`: принудительно выключает вентилятор и сохраняет этот режим после перезагрузки.
+- `set fan timeout <Ns>`: изменяет автоматическое окно удержания после TX в секундах и сохраняет его после перезагрузки, например `set fan timeout 45s`.
+
+Поведение автоматического режима:
+
+- принудительно включает вентилятор во время TX и оставляет его включённым на настроенный таймаут после этого
+- в остальных случаях включает вентилятор при `48C`
+- выключает его обратно при `42C`
+- оставляет вентилятор включённым, если показание NTC недоступно
+
+Примечания:
+
+- режим вентилятора репитера по умолчанию — `auto`
+- таймаут после TX по умолчанию — `30s`
+- режим вентилятора и таймаут хранятся в prefs репитера и сохраняются после перезагрузки
+- только сборки репитера `LilyGo_TBeam_1W_*` используют эти сохраняемые настройки вентилятора
+- допустимый диапазон — от `0s` до `600s`
+
+## Доступ к CLI через веб-панель
+
+Когда веб-панель репитера включена и вы прошли аутентификацию, панель CLI в браузере может выполнять те же команды CLI, которые принимает репитер.
+
+Примечания:
+
+- панель по-прежнему использует для доступа пароль администратора репитера
+- команды выполняются с той же осторожностью, как если бы вы вводили их напрямую в CLI репитера
+- это предназначено для локального административного использования в доверенной сети
+- `start ota` освобождает локальный слушатель HTTP-редиректа на порту `80`, чтобы слушатель OTA HTTP мог занять его, не останавливая остальные службы репитера, независимо от того, выполнена ли команда из веб-панели, последовательного CLI или удалённого сеанса CLI companion/приложения
+- если старый слушатель редиректа не освободил порт `80` полностью, слушатель OTA повторяет попытки примерно до 30 секунд, после чего сдаётся
+- кнопка `Purge SD` в веб-интерфейсе выполняет `purge sd` после подтверждения в браузере
+- `start ota` использует существующий Wi-Fi-адрес репитера, если он уже подключён, или запускает точку доступа `MeshCore-OTA`, если Wi-Fi не подключён
+- ярлык Regions в `/app` последовательно выполняет существующие команды регионов MeshCore: `region put au`, `region put au-STATE`, `region allowf au`, `region allowf au-STATE`, затем `region save`
+
+## Команды восстановления Wi-Fi для companion
+
+Эти команды доступны в последовательном CLI восстановления для сборок `*_companion_radio_wifi`.
+
+Чтобы войти в `CLI Rescue`:
+
+- откройте последовательный монитор на скорости `115200` бод
+- перезагрузите устройство
+- удерживайте кнопку пользователя в течение первых 8 секунд после загрузки
+- дождитесь `========= CLI Rescue =========`
+
+- `get wifi.status`: показывает настроенный SSID, состояние подключения, необработанный код статуса Wi-Fi, IP, канал и уровень сигнала при подключении.
+- `get wifi.ssid`: показывает настроенный SSID Wi-Fi.
+- `get wifi.powersaving`: показывает текущий режим энергосбережения Wi-Fi.
+- `set wifi.ssid <ssid>`: сохраняет SSID Wi-Fi и сразу повторяет подключение.
+- `set wifi.pwd <password>`: сохраняет пароль Wi-Fi и сразу повторяет подключение.
+- `set wifi.powersaving none|min|max`: изменяет режим энергосбережения Wi-Fi.
+
+Сборки Companion Wi-Fi также по-прежнему поддерживают существующие команды восстановления, такие как:
+
+- `set pin <6-digit-pin>`
+- `rebuild`
+- `erase`
+- `ls ...`
+- `cat ...`
+- `rm ...`
+- `reboot`
+
+### Точка доступа для восстановления
+
+Когда у устройства companion Wi-Fi не настроены учётные данные Wi-Fi или оно не может подключиться
+к своей настроенной сети в течение 60 секунд, оно поднимает собственную
+точку доступа `EastMesh-WiFi`, чтобы его можно было восстановить без последовательного кабеля.
+
+**Пароль точки доступа — это pin устройства, дополненный нулями до 8 цифр** (WPA2 требует
+не менее 8 символов). Pin подчиняется тем же правилам, что и pin сопряжения Bluetooth в
+сборках BLE:
+
+| Устройство                      | Активный pin                                                             | Пароль `EastMesh-WiFi`                                       |
+| --------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Есть экран, pin не задан    | случайный 6-значный pin при каждой загрузке, отображается как `Pin:NNNNNN` на главном экране | `00NNNNNN` — считайте его с экрана                            |
+| Нет экрана, pin не задан       | `123456` (по умолчанию)                                                     | `00123456`                                                     |
+| Pin задан через `set pin <pin>` | ваш настроенный pin (любое устройство)                                       | ваш pin, дополненный нулями до 8 цифр, например pin `4242` → `00004242` |
+
+Примечания по pin:
+
+- на устройствах с экраном pin случаен только до тех пор, пока pin не сохранён; выполните
+  `set pin <pin>` для фиксированного пароля (вступает в силу при следующей загрузке)
+- устройствам без экрана в общедоступных местах всегда следует задавать собственный pin — `00123456` —
+  это документированное значение по умолчанию, поэтому относитесь к нему как к паролю роутера по умолчанию
+
+Шаги восстановления:
+
+1. подключитесь к сети `EastMesh-WiFi` с паролем из таблицы выше
+2. откройте CLI восстановления командой `telnet 192.168.4.1` (или `nc 192.168.4.1 23`) — все
+   команды восстановления, перечисленные выше, доступны
+3. `set wifi.ssid <ssid>`, затем `set wifi.pwd <password>` — устройство сразу
+   повторяет подключение к сети с новыми учётными данными
+4. `reboot` (или просто подождите — см. ниже)
+
+Пока точка доступа поднята, устройство продолжает повторять попытки подключения к настроенной сети примерно раз в
+минуту (ожидайте короткий сбой точки доступа при каждой попытке); как только подключение станции
+успешно, точка доступа восстановления автоматически отключается (это также разрывает
+ваш сеанс восстановления — это признак того, что всё сработало).
+
+### Использование приложения companion через AP (роуминг)
+
+Точка доступа восстановления нужна не только для исправления учётных данных — через неё
+доступен полный протокол companion, что делает её режимом роумингового доступа, когда устройство
+находится вне своей настроенной сети:
+
+1. подключитесь к `EastMesh-WiFi` с паролем, производным от pin (см. таблицу выше)
+2. в приложении companion MeshCore добавьте/подключите Wi-Fi-устройство с хостом
+   `192.168.4.1` и портом `5000`
+3. пользуйтесь приложением как обычно — сообщения, контакты и каналы работают через AP
+
+Примечания по использованию в роуминге:
+
+- один раз выполните `set pin <pin>`, чтобы пароль точки доступа оставался неизменным между перезагрузками;
+  иначе устройства с экраном выбирают новый случайный pin при каждой загрузке
+- точка доступа появляется примерно через 60 секунд после загрузки (сначала устройство пытается
+  подключиться к своей настроенной сети) и работает до тех пор, пока эта сеть недоступна
+- оказавшись снова в зоне действия своей настроенной сети, устройство подключается к ней и
+  автоматически отключает точку доступа — вместо этого переподключите приложение по адресу в локальной сети
+
+## Скрипт проверки состояния heap
+
+`posadmesh-tools/web-heap-check.sh <host> [--stress] [--rounds N]` читает `memory`, `get web.status`, `get mqtt.status` и `get wifi.status` через HTTPS API, а с флагом `--stress` имитирует всплески загрузки страниц браузером перед повторным чтением `memory`. Аутентифицируйтесь с помощью `REPEATER_PASSWORD` или `REPEATER_TOKEN` в окружении (или введите пароль по запросу). Следите за `heap_max` (наибольший внутренний блок; для TLS нужно ~40KB), `heap_min` и счётчиками `heals`/`deferred`/`leaked`.