MeshCore-Posadmesh/README.md

MeshCore-Posadmesh

PosadMesh — форк проекта EastMesh, который, в свою очередь, основан на официальной прошивке MeshCore:

• https://github.com/meshcore-dev/MeshCore

Прошивку дорабатывают энтузиасты из Сергиева Посада; проект ориентирован на работу с сайтом https://meshcoretel.ru.

Благодарность Scott Powell / Ripple Radios и участникам MeshCore за оригинальную прошивку и основу проекта.

Этот репозиторий предоставляет адаптированные сборки MeshCore: прошивку MQTT-репитера, которая публикует телеметрию в mesh-сеть MeshCoreTel.

Сборки MQTT-репитера передают телеметрию на https://meshcoretel.ru — укажите координаты узла и радиопараметры своего региона, чтобы узел появился на карте и в связях. Для Москвы (MOW) это 868,731 МГц, полоса 62,5 кГц, SF7, CR7, хэш пути 2 байта.

Что добавляет этот репозиторий

• таргеты прошивки *_repeater_mqtt с:
  • встроенным WiFi
  • MQTT-аплинком к курируемому брокеру MeshCoreTel и дополнительно опциональным собственным брокером (TCP или WSS)
  • опциональной локальной панелью конфигурации HTTPS на поддерживаемых таргетах ESP32
• таргеты прошивки *_repeater_mqtt_espnow, добавляющие локальный мост ESP-NOW mesh
• таргеты прошивки *_repeater_bridge_espnow для обычного ESP-NOW-моста репитера в стиле upstream, без MQTT-аплинка и веб-панели PosadMesh
• специфичные для PosadMesh процесс релизов и версионирование поверх релизов upstream MeshCore
• документация и руководство по релизам для пользователей PosadMesh вместо полного набора документации upstream MeshCore

Отличия от upstream MeshCore

Ядро проекта — mesh-стек, радио, протокол и работа с платами — остаётся upstream-кодом MeshCore. PosadMesh добавляет поверх него транспорт, телеметрию и веб-интерфейс:

Область	upstream MeshCore	PosadMesh
Транспорт	нет MQTT; репитер работает только по радио и через последовательный порт	MQTT-аплинк: курируемый брокер meshcoretel и опциональный собственный брокер (TCP или WSS по пути /mqtt); публикация статуса, пакетов и raw-данных
MQTT-мост	нет	передача raw-пакетов mesh между репитерами через ваш собственный peer-брокер (трек repeater-mqtt-bridge)
Wi-Fi	нет	Wi-Fi на репитерах: подключение, энергосбережение, watchdog шлюза, автоматическое переподключение, команды wifi.*
Веб-интерфейс	нет	локальная HTTPS-панель: вход по паролю администратора, выполнение CLI-команд, настройки репитера/радио/MQTT, регионы, чёрные списки, обновление прошивки (OTA), управление сертификатом панели
Телеметрия	нет	история метрик в PSRAM и архив на SD: батарея, загрузка ядра, память, пакеты, ошибки, уровень сигнала и шума, датчики, GPS; страница /stats с графиками и списком соседей/событий
CLI	базовый набор MeshCore	дополнительно mqtt.*, wifi.*, web.*, blacklist path|chan, region, stats-*, time и time.force, режим Ghost Node, лимит пересылки flood, отчёт о батарее платы, управление вентилятором T-Beam 1W
Сборки	companion (USB/BLE), repeater, room server, sensor	только MQTT-таргеты: *_repeater_mqtt, *_repeater_mqtt_espnow, *_repeater_mqtt_bridge
Платы	базовый список MeshCore	добавлены свои варианты (Meshadventurer, самодельные ESP32-S3 + E22, Xiao S3 + LoRa2021F33, RAK3112, Station G2/G3, ThinkNode и другие)
Релизы	upstream-процесс	свои треки и теги repeater-mqtt*, локальная сборка через posadmesh-build.sh, публикация релизов в Gitea

Что не меняется: поведение mesh-сети, радиоконфигурации, протокол и совместимость с MeshCore; upstream-код сохраняется в репозитории и синхронизируется из meshcore-dev/MeshCore (см. AGENTS.md).

Релизы

Готовые прошивки публикуются в разделе Releases на git.meshinfo.ru:

• https://git.meshinfo.ru/shade/MeshCore-Posadmesh/releases

Руководство по прошивке, в том числе когда использовать .bin, а когда -merged.bin, см. в:

• posadmesh-docs/releases.md

Веб-прошивальщик MeshCoreTel (в том числе прошивки наблюдателя и настройка радиопараметров):

• https://meshcoretel.ru/ru/flasher

Установка uv

Этот репозиторий использует uv для Python-инструментов и запускает PlatformIO через uv run.

Официальная документация по установке:

• https://docs.astral.sh/uv/getting-started/installation/

Распространённые способы установки:

macOS и Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Homebrew:

brew install uv

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Типовое использование репозитория

Установка инструментов:

uv sync

Список доступных таргетов сборки:

bash posadmesh-build.sh list

Сборка одного таргета:

uv run pio run -e heltec_v4_repeater_mqtt
uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt

Сборка с релизными метаданными версии:

export FIRMWARE_VERSION=v1.15.0
export POSADMESH_VERSION=v2026.5.1
bash posadmesh-build.sh build-firmware heltec_v4_repeater_mqtt

Прошивка таргета:

uv run pio run -e heltec_v4_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX

Открыть последовательный монитор:

uv run pio device monitor --port /dev/tty.usbmodemXXXX --baud 115200

Локальная сборка документации:

uv run --group docs zensical serve
uv run --group docs zensical build

Ключевые файлы

• posadmesh-build.sh
  • обёртка локальной/релизной сборки PosadMesh
  • внедряет FIRMWARE_VERSION, CLIENT_VERSION и релизные метаданные PosadMesh
• build.sh
  • обёртка сборки upstream MeshCore, сохранённая для уменьшения будущих конфликтов слияния
• pyproject.toml
  • Python-инструменты и зависимости для документации
• platformio.ini
  • корневой конфиг PlatformIO и вспомогательные скрипты ESP32
• variants/posadmesh_mqtt/platformio.ini
  • общие определения окружений MQTT-репитера PosadMesh
• examples/simple_repeater/MyMesh.cpp
  • подключение CLI репитера, набор MQTT-команд и интеграция с белым списком веб-панели
• src/helpers/bridges/MQTTBridge.cpp
  • двунаправленный MQTT-мост mesh (peer-брокер TCP, топик meshcore/bridge/packets)
• src/helpers/mqtt/MQTTUplink.cpp
  • реализация MQTT-аплинка, веб-панель HTTPS, поддержка собственного брокера (TCP/WSS) и управление WiFi репитера
• RELEASE.md
  • форматы тегов и порядок выпуска релизов
• posadmesh-docs/
  • документация, ориентированная на PosadMesh, для чтения в веб-интерфейсе git.meshinfo.ru
• docs/
  • документация upstream MeshCore, сохранённая для уменьшения будущих конфликтов слияния

Ключевые возможности PosadMesh

Дополнения MQTT для репитера

• поддержка курируемого брокера:
  • meshcoretel
• опциональный собственный брокер (TCP или MQTT поверх WSS по пути /mqtt) с именем пользователя и паролем
• элементы управления в CLI для:
  • учётных данных WiFi
  • энергосбережения WiFi
  • отчётов о заряде батареи платы на поддерживаемых таргетах
  • включения MQTT-эндпоинта
  • публикации MQTT-пакетов и raw-данных
  • публичного ключа и email владельца
  • включения локальной веб-панели

MQTT-мост mesh (MQTT-репитер)

Трек релиза repeater-mqtt-bridge (*_repeater_mqtt_bridge) выполняет мостовую передачу raw-пакетов mesh между репитерами через peer-брокер MQTT, который запускаете вы сами (например, Mosquitto на ПК в локальной сети). Это не то же самое, что MQTT-аплинк к курируемому брокеру MeshCoreTel:

	MQTT-аплинк (MQTT-репитер)	MQTT-мост mesh
Назначение	Публикация JSON-телеметрии в курируемые брокеры	Передача зашифрованных пакетов mesh между радиоустройствами
Брокеры	meshcoretel, собственный брокер	Ваш peer-брокер (host:port, TCP)
Топик	meshcore/<iata>/... (по IATA)	meshcore/bridge/packets (фиксированный)
По умолчанию в bridge-сборках	Выключено по умолчанию (включается в веб-панели / CLI)	Включено, когда включён bridge.enabled

Первый поддерживаемый таргет: Xiao_S3_WIO_repeater_mqtt_bridge

Связанный трек: repeater-mqtt-espnow (*_repeater_mqtt_espnow) использует ESP-NOW вместо MQTT для локальной мостовой передачи.

Пример сборки:

uv run pio run -e Xiao_S3_WIO_repeater_mqtt_bridge

Прошивка (обновление):

uv run pio run -e Xiao_S3_WIO_repeater_mqtt_bridge -t upload --upload-port COM10

После полного стирания флеш-памяти прошивайте объединённый образ по адресу 0x0, а не только firmware.bin:

uv run pio run -e Xiao_S3_WIO_repeater_mqtt_bridge -t mergebin
uv run pio pkg exec -p tool-esptoolpy -- esptool.py --chip esp32s3 --port COM10 write_flash 0x0 .pio/build/Xiao_S3_WIO_repeater_mqtt_bridge/firmware-merged.bin

Peer-брокер Mosquitto (локальная сеть)

Каждый узел моста подключается к одному и тому же peer-брокеру с одними и теми же учётными данными и bridge.secret.

1. Установите Mosquitto на машине, доступной с обоих репитеров (например, 192.168.1.145).
2. Отредактируйте mosquitto.conf (при установке службой Windows: C:\Program Files\Mosquitto\mosquitto.conf) и добавьте:

listener 1883 0.0.0.0
allow_anonymous false
password_file C:\Program Files\Mosquitto\passwd

Только для лабораторных/тестовых целей allow_anonymous true работает и без файла паролей.

3. Создайте пользователя (CMD от имени администратора):

cd "C:\Program Files\Mosquitto"
mosquitto_passwd -c passwd bridgeuser

4. Перезапустите службу (не запускайте второй mosquitto -v, пока служба занимает порт 1883):

Restart-Service mosquitto

5. Убедитесь, что прослушивание идёт в локальной сети, и откройте брандмауэр:

netstat -ano | findstr ":1883"

Ожидается 0.0.0.0:1883, а не только 127.0.0.1:1883.

6. Проверьте с другой машины:

mosquitto_pub -h 192.168.1.145 -p 1883 -u bridgeuser -P your-password -t test -m hello
mosquitto_sub -h 192.168.1.145 -p 1883 -u bridgeuser -P your-password -t meshcore/bridge/packets -v

Двоичный мусор в meshcore/bridge/packets — это нормально: payload — это XOR-зашифрованные кадры mesh, а не текст.

Настройка репитера

Настройте оба узла моста одинаково для доступа к брокеру; используйте один и тот же bridge.secret на каждом узле группы моста.

CLI через последовательный порт или веб-панель:

set wifi.ssid YourNetwork
set wifi.pwd YourWiFiPassword
set bridge.peer.host 192.168.1.145
set bridge.peer.port 1883
set bridge.peer.username bridgeuser
set bridge.peer.password your-password
set bridge.secret your-shared-bridge-secret

Веб-панель: Настройки MQTT → Peer MQTT моста mesh (host:port, имя пользователя, пароль). Этот раздел появляется, когда get bridge.type возвращает mqtt.

Полезные проверки:

get bridge.type
get bridge.peer.host
get bridge.enabled

Пароль администратора по умолчанию в dev-сборках обычно password, если вы его не изменили.

Пакеты используют магическое значение 0xC03E, контрольную сумму Fletcher, XOR-шифрование с bridge.secret, затем публикацию/подписку в meshcore/bridge/packets. Обнаружение дубликатов ограничивает циклы, когда оба узла видят один и тот же трафик.

Подробнее:

• Пользовательский CLI — настройки MQTT-моста
• Веб-панель — настройки MQTT и поля peer моста
• Релизы — сравнение треков

Локальная веб-панель

На поддерживаемых таргетах ESP32 *_repeater_mqtt репитер может предоставлять локальную панель конфигурации HTTPS по WiFi.

Возможности:

• доступ с проверкой пароля по существующему паролю администратора репитера
• выполнение CLI только из белого списка
• сгруппированные быстрые действия
• светлая и тёмная темы
• опциональное отключение через set web off

Рекомендуется использовать для первичной настройки и периодической диагностики. При развёртывании MQTT-репитеров отключайте панель по завершении, если нужен максимальный запас heap для MQTT.

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

На платах с дисплеем и кнопкой мастер настройки доступен прямо на устройстве — без компьютера и телефона: двойное нажатие кнопки из экрана состояния открывает меню. Настраиваются координаты, частота, полоса, CR и SF по отдельности, мощность передатчика, пересылка пакетов, размер хэша пути, интервалы advert и flood advert, лимит flood. Внизу меню — Save & exit. Значения применяются через тот же обработчик, что и последовательный CLI, поэтому проверка и сохранение одинаковы для обоих путей, а ответ устройства показывается на экране.

Координаты вводятся в формате xx.xxxx yy.yyyy, частота — как 868.731 MHz (целые МГц шагом 1, кГц по разрядам), полоса — как 062.50 kHz, поразрядно: длинное нажатие входит в правку цифры или позиции, короткое — +1, двойное — −1, длинное — применить, короткое после применения — перейти к следующей цифре; внизу экранов частоты и полосы — пункт Save & exit, после сохранения возврат в меню.

Подробное описание кнопок, меню и ограничений — в Настройке с дисплея и кнопки, там же иллюстрации всех экранов. Та же страница с картинками опубликована в вики проекта: https://git.meshinfo.ru/shade/MeshCore-Posadmesh/wiki/Device-Setup.

Сборка и релизы

Репозиторий живёт на https://git.meshinfo.ru/shade/MeshCore-Posadmesh.

Собственные workflow GitHub Actions (сборка релизов, проверки сборки и публикация доков) удалены при переезде. Сейчас прошивки собираются локально через posadmesh-build.sh или на сервере ручным workflow .gitea/workflows/build-mqtt-firmwares.yml (Actions → Build MQTT firmwares → Run workflow); теги и релизы создаются в веб-интерфейсе git.meshinfo.ru, а собранные файлы выгружаются в релиз скриптом posadmesh-tools/publish-gitea-release.sh. Подробности — в RELEASE.md.

Workflow upstream MeshCore (.github/workflows/build-*.yml, firmware-builder.yml, pr-build-check.yml, run-unit-tests.yml, stale-bot.yml) сохранены под исходными именами файлов для уменьшения конфликтов слияния. Они не являются частью процесса релизов PosadMesh и не используются.

Текущие треки релизов:

• repeater-bridge-espnow
• repeater-mqtt
• repeater-mqtt-espnow
• repeater-mqtt-bridge

Теги релизов

Текущие теги релизов:

git tag repeater-bridge-espnow-v1.15.0
git tag repeater-mqtt-v2026.5.1
git tag repeater-mqtt-espnow-v2026.5.1
git tag repeater-mqtt-bridge-v2026.7.0

repeater-bridge-espnow использует в теге версию upstream MeshCore.

MQTT-репитер использует:

• FIRMWARE_VERSION — версия upstream MeshCore, задаётся при локальной сборке
• POSADMESH_VERSION — версия релиза PosadMesh из тега

Полный процесс релиза см. в RELEASE.md.

Изменения в проекте

Правило ведения: после любых правок проекта сюда дописывается короткая запись о том, что изменилось.

2026.10.0 (текущая разработка)

Ребрендинг в PosadMesh

• папки и скрипты: eastmesh-docs → posadmesh-docs, eastmesh-tools → posadmesh-tools, eastmesh-build.sh → posadmesh-build.sh;
• цели сборки: *_repeater_observer* → *_repeater_mqtt*;
• треки и теги релизов: repeater-mqtt, repeater-mqtt-espnow, repeater-mqtt-bridge (ранее observer-eastmesh*);
• переменная версии релиза EASTMESH_VERSION → POSADMESH_VERSION, суффикс версии сборки -posadmesh-;
• posadmesh-docs/*, README.md, RELEASE.md и AGENTS.md переведены на русский язык; команды, их вывод, код, пути и идентификаторы оставлены без перевода.

Удалено

• брокеры waev, meshmapper, letsmesh-eu и letsmesh-us — из прошивки, веб-панели и документации; остались mqtt.meshcoretel и mqtt.custom. Сохранённые выборы удалённых брокеров сбрасываются один раз при обновлении;
• линия companion-прошивок: трек companion-wifi, команды сборки companion и разделы документации. Проект собирает только MQTT-прошивки.

Переименование observer → mqtt

• цели: *_repeater_mqtt, *_repeater_mqtt_espnow, *_repeater_mqtt_bridge;
• команды сборки: build-repeater-mqtt-firmwares, build-repeater-mqtt-espnow-firmwares, build-repeater-mqtt-bridge-firmwares; добавлены build-mqtt-firmwares (все MQTT-треки) и list-mqtt;
• из документации, release-notes.yml и шаблонов issue убраны старые имена (историю релизов с реальными git-тегами не переписывали).

Локальный мастер настройки

• добавлен мастер настройки репитера (examples/simple_repeater/UITask.*): работает на любой цели, у которой есть дисплей и кнопка, и полностью исключается препроцессором там, где их нет;
• вход в мастер — двойное нажатие кнопки из экрана состояния (на узле без имени мастер открывается сам после заставки); выход — пункт Save & exit;
• ввод координат в формате xx.xxxx yy.yyyy: длинное нажатие — правка текущей цифры, короткое — +1, двойное — −1, длинное — применить, короткое после применения — следующая цифра; после всех 12 цифр — экран сохранения;
• радиопараметры настраиваются по отдельности: Frequency (значение 868.731 MHz: целые МГц шагом ±1, кГц по разрядам), Bandwidth (062.50 kHz, поразрядно), CR и SF (шагом); внизу экранов частоты и полосы — пункт Save & exit, после сохранения возврат в меню; любой из четырёх пунктов отправляет set radio <частота>,<полоса>,<sf>,<cr>, поэтому остальные значения сохраняются;
• остальные пункты: мощность TX, пересылка пакетов, размер хэша пути, интервалы advert и flood advert, лимит flood; внизу меню — Save & exit;
• значения применяются через тот же CommonCLI, что и последовательный порт, а ответ устройства (OK или текст ошибки) выводится на экран;
• документация с иллюстрациями: страница Настройка с дисплея и кнопки дополнена схемой управления и изображениями всех экранов (состояние, меню, частота и правка разряда, полоса, CR, SF, координаты, подтверждение, ответ устройства); та же документация опубликована в вики проекта — https://git.meshinfo.ru/shade/MeshCore-Posadmesh/wiki/Device-Setup;
• сборка проверена на heltec_v4_repeater_mqtt, Meshadventurer_sx1262_repeater_mqtt, Generic_E22_sx1262_repeater_mqtt (без дисплея) и RAK_3112_repeater_mqtt.

Исправлено

• set mqtt.meshcoretel on|off не срабатывал: обработчик сравнивался со строкой set mqtt.mqtt.meshcoretel . Алиас set mqtt.meshcoretel.ru on|off читает значение по правильному смещению;
• setEndpointEnabled маскировал сохранённую маску брокеров значением 0x07 и терял бит собственного брокера при переключении любого другого;
• на странице логина веб-панели незакрытый тег </div съедал абзац-подсказку про пароль администратора;
• разбор дерева регионов срезал завершающую букву F в имени региона, из-за чего region allowf, region denyf и region remove не работали для таких имён;
• групповые команды сборки не собирали ничего: использовались устаревшие суффиксы _repeater_observer*, а на Windows имена окружений приходили с символом \r. Теперь используются реальные суффиксы, а вывод PlatformIO очищается от \r.

Инфраструктура и релизы

• репозиторий переехал на https://git.meshinfo.ru/shade/MeshCore-Posadmesh; собственные workflow GitHub Actions удалены, upstream-оверлеи сохранены под исходными именами;
• добавлен ручной workflow Gitea Actions .gitea/workflows/build-mqtt-firmwares.yml — сборка MQTT-прошивок на сервере и публикация релиза;
• добавлен скрипт posadmesh-tools/publish-gitea-release.sh для выгрузки собранных файлов в релиз Gitea;
• в README добавлен раздел «Отличия от upstream MeshCore»;
• собран полный набор MQTT-прошивок (109 целей) с версией v1.17.1-posadmesh-v2026.10.0 для публикации в релизах repeater-mqtt, repeater-mqtt-espnow и repeater-mqtt-bridge;
• проект и документация переориентированы на meshcoretel.ru: в README переписано происхождение проекта и заведён этот журнал изменений; из документации убраны прежние региональные материалы, ссылки на сторонние сервисы, примеры радиопресетов и коды регионов других стран; руководство по прошивке переведено на файлы из раздела релизов и esptool.py, вместо раздела региональных материалов добавлен раздел материалов MeshCoreTel.

Документация

Отдельный сайт документации больше не публикуется: страницы лежат в каталоге posadmesh-docs/ и читаются прямо в веб-интерфейсе git.meshinfo.ru:

• https://git.meshinfo.ru/shade/MeshCore-Posadmesh/src/branch/main/posadmesh-docs

Текущие страницы документации:

• Главная
• Скачивание и прошивка релизов
• Локальная сборка с uv
• Пользовательские команды CLI
• Веб-панель