PosadMesh — это mesh-сеть, развиваемая сообществом на востоке Австралии. Этот репозиторий предоставляет адаптированные сборки MeshCore, включая прошивку WiFi companion с дополнительными инструментами CLI и прошивку обсервера, которая интегрируется с нашей платформой телеметрии CoreScope.

CoreScope (https://core.eastmesh.au) обеспечивает видимость сети, включая состояние репитеров, обсерверов и данные картографирования.

Сборки обсервера передают телеметрию в PosadMesh Core и предназначены только для репитеров Восточной Австралии; запуск их в других местах может исказить общие данные сети.

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

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

Релизы

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

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

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

posadmesh-docs/releases.md

Сайт прошивальщика кастомной прошивки:

https://flasher.eastmesh.au/

Установка 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_observer
uv run pio run -e heltec_v4_companion_radio_wifi

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

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

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

uv run pio run -e heltec_v4_repeater_observer -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
- общие определения окружений обсервера 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 репитера
examples/companion_radio
- реализация прошивки companion
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 (обсервер)

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

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

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

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

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

uv run pio run -e Xiao_S3_WIO_repeater_observer_mqtt_bridge

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

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

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

uv run pio run -e Xiao_S3_WIO_repeater_observer_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_observer_mqtt_bridge/firmware-merged.bin

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

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

Установите Mosquitto на машине, доступной с обоих репитеров (например, 192.168.1.145).
Отредактируйте 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 работает и без файла паролей.

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

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

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

Restart-Service mosquitto

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

netstat -ano | findstr ":1883"

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

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

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. Обнаружение дубликатов ограничивает циклы, когда оба узла видят один и тот же трафик.

Подробнее:

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

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

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

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

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

Дополнения Companion WiFi

Таргеты *_companion_radio_wifi теперь поддерживают сохраняемые команды восстановления WiFi:

откройте последовательный монитор на скорости 115200 бод
перезагрузите устройство
удерживайте пользовательскую кнопку в течение первых 8 секунд после загрузки, чтобы войти в CLI Rescue
дождитесь ========= CLI Rescue =========
отправьте команды из последовательного монитора

Эти команды восстановления доступны только после входа в CLI Rescue:

get wifi.status
get wifi.ssid
get wifi.powersaving
set wifi.ssid <ssid>
set wifi.pwd <password>
set wifi.powersaving none|min|max

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

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

Собственные workflow GitHub Actions (сборка релизов, проверки сборки и публикация доков) удалены при переезде: релизы собираются локально через posadmesh-build.sh, а теги и релизы создаются вручную в веб-интерфейсе git.meshinfo.ru.

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

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

companion-wifi
repeater-bridge-espnow
observer-posadmesh
observer-posadmesh-bridge-espnow
observer-posadmesh-bridge-mqtt

Теги релизов

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

git tag companion-wifi-v1.14.1
git tag repeater-bridge-espnow-v1.15.0
git tag observer-posadmesh-v2026.5.1
git tag observer-posadmesh-bridge-espnow-v2026.5.1
git tag observer-posadmesh-bridge-mqtt-v2026.7.0

Companion WiFi использует в теге версию upstream MeshCore.

Обсервер использует:

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

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

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

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

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

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

README.md Unescape Escape

MeshCore-Posadmesh