shade
8fa0bfe1d3
- добавлены Waveshare_S3_LR1121_repeater_mqtt/_espnow/_bridge: из новых плат upstream 1.18.0 только эта на ESP32; ThinkNode M8 и M4, Wio Tracker L1 1W и Muzi Base — на nRF52, WiFi нет, MQTT-сборки для них невозможны (им место в форке MeshCore, не здесь) - EnvironmentSensorManager: возвращён scanI2CBus из upstream (слияние его потеряло, потому что мы когда-то заменили полное сканирование шины поштучной проверкой адресов); при этом сохранён наш таймаут 20 мс на ESP32 и наша поддержка адреса, определённого платой - AGENTS.md: работаем в main, ветка develop устарела (эпоха EastMesh); upstream тянем релизным тегом, а не веткой dev; версия upstream — v1.18.0 Проверено сборкой после слияния: heltec_v4_repeater_mqtt, LilyGo_TBeam_1W_repeater_mqtt, Meshadventurer_sx1262_repeater_mqtt, RAK_3112_repeater_mqtt, heltec_v4_repeater_mqtt_espnow, heltec_v4_repeater_mqtt_bridge, LilyGo_Tlora_C6_repeater_mqtt_espnow (наш фикс ESP-IDF 5), LilyGo_TBeam_1W_repeater_mqtt_espnow, Waveshare_S3_LR1121_repeater_mqtt, Waveshare_S3_LR1121_repeater_mqtt_bridge MQTT-целей стало 112: 42 uplink, 34 espnow, 36 bridge
236 lines
12 KiB
Markdown
236 lines
12 KiB
Markdown
# AGENTS.md
|
|
|
|
## Назначение
|
|
|
|
Слой PosadMesh поверх upstream MeshCore.
|
|
|
|
**По умолчанию:** сохраняем поведение upstream.
|
|
Изменяем код только для чётко ограниченных возможностей PosadMesh:
|
|
|
|
- `*_repeater_mqtt`
|
|
- MQTT-аплинк/брокер
|
|
- веб-панель репитера
|
|
- документация, релизы, автоматизация
|
|
|
|
## Принципы
|
|
|
|
- Минимальные точечные изменения
|
|
- Предпочитаем дополнять, а не менять код upstream
|
|
- Избегаем посторонних рефакторингов
|
|
- Сохраняем паритет с поведением upstream
|
|
|
|
## Ограничения
|
|
|
|
### Upstream
|
|
|
|
- Не менять постороннюю логику MeshCore
|
|
- Не менять семантику CLI без явной необходимости
|
|
- Не вносить ломающие изменения в существующие таргеты
|
|
|
|
### Документация (обновлять в том же PR, когда это возможно)
|
|
|
|
| Изменение | Файл |
|
|
| --------------------- | ----------------------------- |
|
|
| CLI | `posadmesh-docs/custom-cli.md` |
|
|
| UI/поведение веб-панели | `posadmesh-docs/web-panel.md` |
|
|
| Релизы | `release-notes.yml` |
|
|
| Руководство по прошивке | `posadmesh-docs/releases.md` |
|
|
|
|
### Контроль веб-панели
|
|
|
|
Если правите `examples/simple_repeater/MyMesh.cpp`, обновите также `posadmesh-docs/custom-cli.md`.
|
|
|
|
## Инструменты
|
|
|
|
- Использовать `uv` + PlatformIO через `uv run`
|
|
- Не рассчитывать на глобально установленный `pio`
|
|
|
|
### Политика сборок
|
|
|
|
Сборки дорогие. Избегать без необходимости.
|
|
|
|
НЕ собирать для:
|
|
|
|
- только документация / HTML / CSS
|
|
|
|
Предпочитать:
|
|
|
|
- локальные сборки, запускаемые пользователем
|
|
- рассуждения вместо выполнения
|
|
|
|
Собирать только если:
|
|
|
|
- изменение высокого риска
|
|
- нужно проверить поведение прошивки
|
|
|
|
### Команды
|
|
|
|
```bash
|
|
uv sync
|
|
uv run pio run -e <env>
|
|
uv run pio device monitor --port <port> --baud 115200
|
|
uv run --group docs zensical serve
|
|
uv run --group docs zensical build
|
|
```
|
|
|
|
Не рассчитывайте, что `pio` установлен глобально.
|
|
|
|
## Частые команды
|
|
|
|
Показать список таргетов сборки:
|
|
|
|
```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
|
|
uv run pio run -e heltec_v4_repeater_mqtt_espnow
|
|
uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt_bridge
|
|
```
|
|
|
|
Сборка с релизными метаданными:
|
|
|
|
```bash
|
|
export FIRMWARE_VERSION=v1.15.0
|
|
export POSADMESH_VERSION=v2026.5.1
|
|
bash posadmesh-build.sh build-firmware heltec_v4_repeater_mqtt
|
|
bash posadmesh-build.sh build-firmware T_Beam_S3_Supreme_SX1262_repeater_mqtt
|
|
```
|
|
|
|
Прошить таргет:
|
|
|
|
```bash
|
|
uv run pio run -e heltec_v4_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX
|
|
uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX
|
|
```
|
|
|
|
## Ключевые файлы
|
|
|
|
- `posadmesh-build.sh` — обёртка сборки PosadMesh
|
|
- `build.sh` — обёртка сборки upstream MeshCore, сохранена ради чистоты слияний
|
|
- `platformio.ini`
|
|
- `variants/posadmesh_mqtt/platformio.ini`
|
|
- `examples/simple_repeater/MyMesh.cpp`
|
|
- `src/helpers/mqtt/MQTTUplink.cpp`
|
|
- `posadmesh-docs/*.md`
|
|
- `RELEASE.md`
|
|
- `release-notes.yml`
|
|
|
|
## Принадлежность workflow
|
|
|
|
Репозиторий живёт на <https://git.meshinfo.ru/shade/MeshCore-Posadmesh>.
|
|
|
|
Собственные workflow:
|
|
|
|
- `.gitea/workflows/build-mqtt-firmwares.yml` — ручная сборка MQTT-прошивок на сервере Gitea Actions (`workflow_dispatch`): собирает группу или один таргет, умеет создавать релиз Gitea и загружать в него файлы. Публикация использует секрет репозитория `GITEA_TOKEN`.
|
|
|
|
Кроме workflow прошивки собираются локально через `posadmesh-build.sh`, а теги и релизы создаются в веб-интерфейсе git.meshinfo.ru. Выгрузка собранных файлов в релиз — через `posadmesh-tools/publish-gitea-release.sh`.
|
|
|
|
Workflow upstream MeshCore в `.github/workflows/` остаются под исходными именами файлов ради чистоты слияний. Не адаптируйте их под поведение PosadMesh; держите их близко к upstream. Они не используются для релизов PosadMesh.
|
|
|
|
## Требования к синхронизации документации
|
|
|
|
Если вы меняете что-либо из перечисленного, обновляйте документацию в том же PR, когда это возможно:
|
|
|
|
- Любые изменения в проекте:
|
|
- дописать запись о них в раздел «Изменения в проекте» файла `README.md`
|
|
- Команды веб-панели:
|
|
- обновить `posadmesh-docs/custom-cli.md`
|
|
- Пользовательское поведение, разделы, элементы управления или диагностика веб-панели:
|
|
- обновить `posadmesh-docs/web-panel.md`
|
|
- Добавления в CLI PosadMesh или изменения семантики:
|
|
- обновить `posadmesh-docs/custom-cli.md`
|
|
- Подготовка релиза/тега:
|
|
- обновить `release-notes.yml`
|
|
- Руководство по прошивке и файлам релиза:
|
|
- обновить `posadmesh-docs/releases.md`
|
|
|
|
## Замечания по MQTT-репитерам
|
|
|
|
Сборки `*_repeater_mqtt` могут включать локальную HTTPS-веб-панель на поддерживаемых таргетах ESP32.
|
|
|
|
Эксплуатационные рекомендации уже отражены в документации:
|
|
|
|
- использовать для первичной настройки и диагностики
|
|
- после этого предпочитать `set web off` для максимального запаса heap
|
|
|
|
## Границы продукта
|
|
|
|
Проект собирает и поставляет только MQTT-прошивки (`*_repeater_mqtt`, `*_repeater_mqtt_espnow`, `*_repeater_mqtt_bridge`). Связанные с этим правила:
|
|
|
|
- текущая официальная версия MeshCore — `v1.18.0` (база PosadMesh после слияния upstream; предыдущая база — `v1.17.1`)
|
|
- линия companion-прошивок удалена из проекта: окружения `*_companion_radio_*` и код `examples/companion_radio` остаются в upstream-оверлеях, PosadMesh их не собирает и не документирует
|
|
- не придумывайте отдельные номера версий PosadMesh для треков, которых нет в `release-notes.yml`
|
|
|
|
## Процесс релиза
|
|
|
|
Текущие форматы тегов:
|
|
|
|
```bash
|
|
git tag repeater-bridge-espnow-v1.15.0
|
|
git tag repeater-mqtt-espnow-v2026.5.1
|
|
git tag repeater-mqtt-bridge-v2026.7.0
|
|
git tag repeater-mqtt-v2026.5.1
|
|
```
|
|
|
|
Правила:
|
|
|
|
- теги `repeater-bridge-espnow` используют версию upstream MeshCore напрямую
|
|
- теги `repeater-mqtt-espnow` используют версию релиза PosadMesh в теге
|
|
- теги `repeater-mqtt-bridge` используют версию релиза PosadMesh в теге
|
|
- теги `repeater-mqtt` используют версию релиза PosadMesh в теге
|
|
- переменная `FIRMWARE_VERSION` при локальной сборке задаёт базовую версию upstream для релизных сборок треков `repeater-mqtt`, `repeater-mqtt-espnow` и `repeater-mqtt-bridge`
|
|
- переменная `POSADMESH_VERSION` при локальной сборке задаёт версию релиза PosadMesh
|
|
- если версия релиза upstream MeshCore изменилась, обновите `FIRMWARE_VERSION` при сборке и в документации
|
|
|
|
Типичный порядок выпуска:
|
|
|
|
1. Обновить `release-notes.yml` в `main`.
|
|
2. Собрать нужные прошивки — локально или ручным workflow в Gitea Actions — с подходящими `FIRMWARE_VERSION` и `POSADMESH_VERSION`.
|
|
3. Создать нужный тег или теги релиза на целевом коммите в `main`.
|
|
4. Запушить теги в git.meshinfo.ru и создать релиз в его веб-интерфейсе.
|
|
|
|
## Синхронизация с upstream
|
|
|
|
Когда просят подтянуть изменения из upstream MeshCore:
|
|
|
|
- брать релизный тег upstream нужной роли (например `repeater-v1.18.0`), а не ветку: тег содержит ещё и релизные коммиты, которых в `dev` нет (на момент 1.18.0 — 7 штук)
|
|
- вся работа ведётся в `main` (ветка `develop` в этом репозитории — устаревшая, от эпохи EastMesh, ей не пользуемся)
|
|
- создать временную интеграционную ветку от `main`, например `integrate/upstream-1.18.0`
|
|
- поставить страховочный тег `pre-<версия>` на текущий `main` и сделать `git bundle` перед слиянием
|
|
- влить тег upstream в интеграционную ветку, разрешать конфликты так, чтобы сохранить изменения, специфичные для PosadMesh
|
|
- проверить сборкой несколько ключевых целей, затем влить интеграционную ветку в `main`
|
|
|
|
Вливать upstream напрямую в `main` можно только через интеграционную ветку с проверкой сборкой.
|
|
|
|
## Границы области работ
|
|
|
|
НЕ делать (без явной просьбы):
|
|
|
|
- переименовывать треки
|
|
- менять форматы тегов
|
|
- расширять CLI без обновления документации
|
|
- менять семантику CLI upstream
|
|
- вводить новые схемы версионирования
|
|
|
|
## Сообщения коммитов
|
|
|
|
Используйте краткие общепринятые префиксы:
|
|
|
|
- `feat:` новая функциональность
|
|
- `fix:` исправления ошибок
|
|
- `docs:` изменения документации
|
|
- `chore:` обслуживание, инструменты, нефункциональное
|
|
- `refactor:` изменения кода без изменения поведения
|
|
|
|
Держите сообщения короткими и по делу.
|
|
|
|
## Правило принятия решений
|
|
|
|
Если изменение не является явно специфичным для PosadMesh, не меняйте код.
|
|
При сомнениях предпочитайте не менять ничего или запросить уточнение.
|