MeshCore-Posadmesh/posadmesh-docs/custom-cli.md

Собственные команды CLI

Эта страница описывает команды CLI, специфичные для PosadMesh, добавленные в этом репозитории.

Она не пытается повторять весь набор команд CLI апстримного MeshCore.

С чего начать

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

set wifi.ssid <your-ssid>
set wifi.pwd <your-password>
get wifi.status
set mqtt.iata <code>
get mqtt.status

Для обсерверов с локальной веб-панелью также полезны:

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, которые должны взаимодействовать друг с другом.

Пример:

> 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.