# MeshCore-Posadmesh PosadMesh — форк проекта EastMesh, который, в свою очередь, основан на официальной прошивке MeshCore: - Прошивку дорабатывают энтузиасты из Сергиева Посада; проект ориентирован на работу с сайтом . Благодарность Scott Powell / Ripple Radios и участникам MeshCore за оригинальную прошивку и основу проекта. Этот репозиторий предоставляет адаптированные сборки MeshCore: прошивку MQTT-репитера, которая публикует телеметрию в mesh-сеть MeshCoreTel. **Сборки MQTT-репитера передают телеметрию на ** — укажите координаты узла и радиопараметры своего региона, чтобы узел появился на карте и в связях. Для Москвы (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`](./posadmesh-build.sh), публикация релизов в Gitea | Что **не** меняется: поведение mesh-сети, радиоконфигурации, протокол и совместимость с MeshCore; upstream-код сохраняется в репозитории и синхронизируется из `meshcore-dev/MeshCore` (см. [AGENTS.md](./AGENTS.md)). ## Релизы Готовые прошивки публикуются в разделе Releases на git.meshinfo.ru: - Руководство по прошивке, в том числе когда использовать `.bin`, а когда `-merged.bin`, см. в: - [posadmesh-docs/releases.md](./posadmesh-docs/releases.md) Веб-прошивальщик MeshCoreTel (в том числе прошивки наблюдателя и настройка радиопараметров): - ## Установка uv Этот репозиторий использует `uv` для Python-инструментов и запускает PlatformIO через `uv run`. Официальная документация по установке: - Распространённые способы установки: macOS и Linux: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` Homebrew: ```bash brew install uv ``` Windows PowerShell: ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` ## Типовое использование репозитория Установка инструментов: ```bash uv sync ``` Список доступных таргетов сборки: ```bash bash posadmesh-build.sh list ``` Сборка одного таргета: ```bash uv run pio run -e heltec_v4_repeater_mqtt uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt ``` Сборка с релизными метаданными версии: ```bash export FIRMWARE_VERSION=v1.15.0 export POSADMESH_VERSION=v2026.5.1 bash posadmesh-build.sh build-firmware heltec_v4_repeater_mqtt ``` Прошивка таргета: ```bash uv run pio run -e heltec_v4_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX ``` Открыть последовательный монитор: ```bash uv run pio device monitor --port /dev/tty.usbmodemXXXX --baud 115200 ``` Локальная сборка документации: ```bash uv run --group docs zensical serve uv run --group docs zensical build ``` ## Ключевые файлы - [`posadmesh-build.sh`](./posadmesh-build.sh) - обёртка локальной/релизной сборки PosadMesh - внедряет `FIRMWARE_VERSION`, `CLIENT_VERSION` и релизные метаданные PosadMesh - [`build.sh`](./build.sh) - обёртка сборки upstream MeshCore, сохранённая для уменьшения будущих конфликтов слияния - [`pyproject.toml`](./pyproject.toml) - Python-инструменты и зависимости для документации - [`platformio.ini`](./platformio.ini) - корневой конфиг PlatformIO и вспомогательные скрипты ESP32 - [`variants/posadmesh_mqtt/platformio.ini`](./variants/posadmesh_mqtt/platformio.ini) - общие определения окружений MQTT-репитера PosadMesh - [`examples/simple_repeater/MyMesh.cpp`](./examples/simple_repeater/MyMesh.cpp) - подключение CLI репитера, набор MQTT-команд и интеграция с белым списком веб-панели - [`src/helpers/bridges/MQTTBridge.cpp`](./src/helpers/bridges/MQTTBridge.cpp) - двунаправленный MQTT-мост mesh (peer-брокер TCP, топик `meshcore/bridge/packets`) - [`src/helpers/mqtt/MQTTUplink.cpp`](./src/helpers/mqtt/MQTTUplink.cpp) - реализация MQTT-аплинка, веб-панель HTTPS, поддержка собственного брокера (TCP/WSS) и управление WiFi репитера - [`RELEASE.md`](./RELEASE.md) - форматы тегов и порядок выпуска релизов - [`posadmesh-docs/`](./posadmesh-docs) - документация, ориентированная на PosadMesh, для чтения в веб-интерфейсе git.meshinfo.ru - [`docs/`](./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) | `meshcore/bridge/packets` (фиксированный) | | По умолчанию в bridge-сборках | Выключено по умолчанию (включается в веб-панели / CLI) | Включено, когда включён `bridge.enabled` | **Первый поддерживаемый таргет:** `Xiao_S3_WIO_repeater_mqtt_bridge` **Связанный трек:** `repeater-mqtt-espnow` (`*_repeater_mqtt_espnow`) использует ESP-NOW вместо MQTT для локальной мостовой передачи. Пример сборки: ```bash uv run pio run -e Xiao_S3_WIO_repeater_mqtt_bridge ``` Прошивка (обновление): ```bash uv run pio run -e Xiao_S3_WIO_repeater_mqtt_bridge -t upload --upload-port COM10 ``` После **полного стирания флеш-памяти** прошивайте объединённый образ по адресу `0x0`, а не только `firmware.bin`: ```bash 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](https://mosquitto.org/download/) на машине, доступной с обоих репитеров (например, `192.168.1.145`). 2. Отредактируйте `mosquitto.conf` (при установке службой Windows: `C:\Program Files\Mosquitto\mosquitto.conf`) и добавьте: ```conf listener 1883 0.0.0.0 allow_anonymous false password_file C:\Program Files\Mosquitto\passwd ``` Только для лабораторных/тестовых целей `allow_anonymous true` работает и без файла паролей. 3. Создайте пользователя (CMD от имени администратора): ```cmd cd "C:\Program Files\Mosquitto" mosquitto_passwd -c passwd bridgeuser ``` 4. Перезапустите **службу** (не запускайте второй `mosquitto -v`, пока служба занимает порт 1883): ```powershell Restart-Service mosquitto ``` 5. Убедитесь, что прослушивание идёт в локальной сети, и откройте брандмауэр: ```cmd netstat -ano | findstr ":1883" ``` Ожидается `0.0.0.0:1883`, а не только `127.0.0.1:1883`. 6. Проверьте с другой машины: ```cmd 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 через последовательный порт или веб-панель: ```text 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`. Полезные проверки: ```text get bridge.type get bridge.peer.host get bridge.enabled ``` Пароль администратора по умолчанию в dev-сборках обычно `password`, если вы его не изменили. Пакеты используют магическое значение `0xC03E`, контрольную сумму Fletcher, XOR-шифрование с `bridge.secret`, затем публикацию/подписку в `meshcore/bridge/packets`. Обнаружение дубликатов ограничивает циклы, когда оба узла видят один и тот же трафик. Подробнее: - [Пользовательский CLI — настройки MQTT-моста](./posadmesh-docs/custom-cli.md) - [Веб-панель — настройки MQTT и поля peer моста](./posadmesh-docs/web-panel.md) - [Релизы — сравнение треков](./posadmesh-docs/releases.md) ### Локальная веб-панель На поддерживаемых таргетах ESP32 `*_repeater_mqtt` репитер может предоставлять локальную панель конфигурации HTTPS по WiFi. Возможности: - доступ с проверкой пароля по существующему паролю администратора репитера - выполнение CLI только из белого списка - сгруппированные быстрые действия - светлая и тёмная темы - опциональное отключение через `set web off` Рекомендуется использовать для первичной настройки и периодической диагностики. При развёртывании MQTT-репитеров отключайте панель по завершении, если нужен максимальный запас heap для MQTT. ### Настройка с дисплея и кнопки На платах с дисплеем и кнопкой мастер настройки доступен прямо на устройстве — без компьютера и телефона: двойное нажатие кнопки из экрана состояния открывает меню. Меняются координаты, радиопресет сети MeshCoreTel, мощность передатчика, пересылка пакетов, размер хэша пути, интервалы advert и flood advert, лимит flood. Значения применяются через тот же обработчик, что и последовательный CLI, поэтому проверка и сохранение одинаковы для обоих путей, а ответ устройства показывается на экране. Координаты вводятся в формате `xx.xxxx yy.yyyy`: длинное нажатие входит в правку цифры, короткое — `+1`, двойное — `−1`, длинное — применить, короткое после применения — перейти к следующей цифре, в конце экран подтверждения. Подробное описание кнопок, меню и ограничений — в [Настройке с дисплея и кнопки](./posadmesh-docs/device-setup.md). ## Сборка и релизы Репозиторий живёт на . Собственные workflow GitHub Actions (сборка релизов, проверки сборки и публикация доков) удалены при переезде. Сейчас прошивки собираются локально через [`posadmesh-build.sh`](./posadmesh-build.sh) или на сервере ручным workflow [`.gitea/workflows/build-mqtt-firmwares.yml`](./.gitea/workflows/build-mqtt-firmwares.yml) (Actions → Build MQTT firmwares → Run workflow); теги и релизы создаются в веб-интерфейсе git.meshinfo.ru, а собранные файлы выгружаются в релиз скриптом [`posadmesh-tools/publish-gitea-release.sh`](./posadmesh-tools/publish-gitea-release.sh). Подробности — в [RELEASE.md](./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` ## Теги релизов Текущие теги релизов: ```bash 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](./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.*`](./examples/simple_repeater/UITask.cpp)): работает на любой цели, у которой есть дисплей и кнопка, и полностью исключается препроцессором там, где их нет; - вход в мастер — двойное нажатие кнопки из экрана состояния (на узле без имени мастер открывается сам после заставки); выход — пункт `Save & exit`; - ввод координат в формате `xx.xxxx yy.yyyy`: длинное нажатие — правка текущей цифры, короткое — `+1`, двойное — `−1`, длинное — применить, короткое после применения — следующая цифра; после всех 12 цифр — экран сохранения; - остальные пункты: радиопресет MeshCoreTel (868,731 МГц, 62,5 кГц, SF7, CR7), мощность TX, пересылка пакетов, размер хэша пути, интервалы advert и flood advert, лимит flood; - значения применяются через тот же `CommonCLI`, что и последовательный порт, а ответ устройства (`OK` или текст ошибки) выводится на экран; - документация — [Настройка с дисплея и кнопки](./posadmesh-docs/device-setup.md); - сборка проверена на `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` и терял бит собственного брокера при переключении любого другого; - на странице логина веб-панели незакрытый тег `; собственные workflow GitHub Actions удалены, upstream-оверлеи сохранены под исходными именами; - добавлен ручной workflow Gitea Actions [`.gitea/workflows/build-mqtt-firmwares.yml`](./.gitea/workflows/build-mqtt-firmwares.yml) — сборка MQTT-прошивок на сервере и публикация релиза; - добавлен скрипт [`posadmesh-tools/publish-gitea-release.sh`](./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/`](./posadmesh-docs) и читаются прямо в веб-интерфейсе git.meshinfo.ru: - Текущие страницы документации: - [Главная](./posadmesh-docs/index.md) - [Скачивание и прошивка релизов](./posadmesh-docs/releases.md) - [Локальная сборка с uv](./posadmesh-docs/local-builds.md) - [Пользовательские команды CLI](./posadmesh-docs/custom-cli.md) - [Веб-панель](./posadmesh-docs/web-panel.md)