shade
26b724c0f0
- добавлен ручной workflow Gitea Actions (.gitea/workflows/build-mqtt-firmwares.yml): сборка MQTT-прошивок на сервере и публикация релиза - добавлен posadmesh-tools/publish-gitea-release.sh для выгрузки собранных файлов в релиз Gitea (идемпотентно, фильтр по треку) - README: происхождение проекта переписано (форк EastMesh, доработка энтузиастов из Сергиева Посада, ориентация на meshcoretel.ru), добавлены раздел «Отличия от upstream MeshCore» и журнал «Изменения в проекте» - убраны упоминания Австралии, ссылки на eastmesh.au и региональные материалы; руководство по прошивке переведено на файлы релизов и esptool.py - posadmesh-build.sh: вывод PlatformIO очищается от \r — на Windows групповые команды сборки не находили ни одной цели; companion-команды удалены, добавлены build-mqtt-firmwares и list-mqtt - release-notes.yml: треки repeater-mqtt*, запись 2026.10.0 дополнена удалением companion и исправлением сборки, companion-wifi помечен как снятый с выпуска - AGENTS.md: правило дописывать изменения в README - .gitignore: .pio-home
411 lines
16 KiB
Markdown
411 lines
16 KiB
Markdown
# Веб-API репитера
|
||
|
||
Эта страница описывает локальный HTTPS API, который предоставляют сборки PosadMesh `*_repeater_mqtt` с поддержкой веб-панели.
|
||
|
||
Он предназначен для:
|
||
|
||
- небольшой автоматизации в вашей локальной сети
|
||
- дашбордов или скриптов, которым нужен текущий статус репитера
|
||
- удалённого доступа к CLI через тот же аутентифицированный путь, который использует веб-панель
|
||
|
||
Это не облачный API и не отдельный серверный сервис. Его напрямую обслуживает прошивка репитера.
|
||
|
||
## С чего начать
|
||
|
||
Для обычного использования PosadMesh эта страница не нужна. Обратитесь к [Веб-панели репитера](./web-panel.md), если вы просто хотите настроить или проверить репитер в браузере.
|
||
|
||
Используйте эту страницу, когда нужно, чтобы локальный скрипт, дашборд или домашний инструмент общался с репитером напрямую.
|
||
|
||
Простейший полезный сценарий работы с API:
|
||
|
||
1. войдите с паролем администратора репитера
|
||
2. сохраните полученный токен
|
||
3. отправьте команду CLI через `/api/command`
|
||
|
||
```bash
|
||
TOKEN=$(curl -sk -X POST https://<repeater-ip>/login --data '<admin-password>')
|
||
|
||
curl -sk https://<repeater-ip>/api/command \
|
||
-H "X-Auth-Token: $TOKEN" \
|
||
--data 'get mqtt.status'
|
||
```
|
||
|
||
## Область применения и доступность
|
||
|
||
API доступен только когда:
|
||
|
||
- вы запускаете поддерживаемую сборку прошивки `*_repeater_mqtt`
|
||
- веб-панель репитера включена и работает
|
||
- репитер доступен из локальной сети
|
||
- вы прошли аутентификацию с паролем администратора репитера
|
||
|
||
API предназначен для администрирования в доверенной локальной сети. Не открывайте его напрямую в публичный интернет.
|
||
|
||
## Базовый URL
|
||
|
||
Используйте локальный HTTPS-адрес репитера:
|
||
|
||
```text
|
||
https://<repeater-ip>/
|
||
```
|
||
|
||
Пример:
|
||
|
||
```text
|
||
https://192.168.1.123/
|
||
```
|
||
|
||
## Аутентификация
|
||
|
||
API использует тот же пароль администратора, что и CLI репитера и веб-панель.
|
||
|
||
1. отправьте `POST` с паролем на `/login`
|
||
2. сохраните полученный токен сессии
|
||
3. передавайте этот токен в заголовке `X-Auth-Token` в последующих запросах
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
TOKEN=$(curl -sk -X POST https://<repeater-ip>/login --data '<admin-password>')
|
||
```
|
||
|
||
Использование токена:
|
||
|
||
```bash
|
||
curl -sk https://<repeater-ip>/api/stats -H "X-Auth-Token: $TOKEN"
|
||
```
|
||
|
||
Примечания:
|
||
|
||
- репитер использует самоподписанный сертификат, поэтому большинству инструментов потребуется `-k` или аналог
|
||
- если сессия истекает или заблокирована, запросы возвращают `401 Unauthorized`
|
||
- повторный вход выдаёт новый токен
|
||
|
||
## Рекомендации по производительности
|
||
|
||
API работает на самом репитере, поэтому частота опроса имеет значение.
|
||
|
||
Если репитер дополнительно держит два MQTT-соединения, избегайте частого опроса API. Текущая схема использования в PosadMesh:
|
||
|
||
- опрос статистики раз в `60` секунд
|
||
- запросы по требованию для всего остального
|
||
|
||
Это рекомендуемая базовая схема, если вы хотите избежать перегрузки платы. Держите частоту запросов низкой, избегайте всплесков опроса и предпочитайте ручное обновление или чтение по событию для более тяжёлых операций.
|
||
|
||
Рекомендуемая практика:
|
||
|
||
- опрашивайте `/api/stats` не чаще одного раза в минуту
|
||
- не опрашивайте несколько эндпоинтов параллельно
|
||
- используйте вызовы по требованию для чтения конфигурации и действий CLI
|
||
- завершайте сессию, когда закончили, и прекращайте опрос, когда данные активно не используются
|
||
|
||
## Эндпоинты
|
||
|
||
### `POST /login`
|
||
|
||
Аутентификация с паролем администратора репитера.
|
||
|
||
Тело запроса:
|
||
|
||
```text
|
||
<admin-password>
|
||
```
|
||
|
||
Ответ:
|
||
|
||
- токен сессии в виде обычного текста при успехе
|
||
- `401` при неверном пароле
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk -X POST https://<repeater-ip>/login --data '<admin-password>'
|
||
```
|
||
|
||
### `GET /api/session`
|
||
|
||
Проверка, действителен ли сохранённый токен сессии.
|
||
|
||
Заголовки:
|
||
|
||
```text
|
||
X-Auth-Token: <token>
|
||
```
|
||
|
||
Ответ:
|
||
|
||
- JSON `{"authenticated":true}` при успехе
|
||
- `401 Unauthorized`, если токен отсутствует или устарел после блокировки, перезапуска или перепрошивки
|
||
|
||
### `POST /api/command`
|
||
|
||
Удалённый запуск команды CLI репитера.
|
||
|
||
Заголовки:
|
||
|
||
```text
|
||
X-Auth-Token: <token>
|
||
```
|
||
|
||
Тело запроса:
|
||
|
||
```text
|
||
get wifi.status
|
||
```
|
||
|
||
Ответ:
|
||
|
||
- вывод CLI в виде обычного текста
|
||
- `OK`, если команда выполняется успешно и не возвращает текст
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk https://<repeater-ip>/api/command \
|
||
-H "X-Auth-Token: $TOKEN" \
|
||
--data 'get wifi.status'
|
||
```
|
||
|
||
### `POST /api/firmware-update`
|
||
|
||
Загрузите `.bin` прошивки приложения через HTTPS-веб-панель и перезагрузитесь после успешного обновления.
|
||
|
||
Заголовки:
|
||
|
||
```text
|
||
X-Auth-Token: <token>
|
||
X-Firmware-MD5: <32-character md5>
|
||
Content-Type: application/octet-stream
|
||
```
|
||
|
||
Тело запроса:
|
||
|
||
```text
|
||
raw firmware .bin bytes
|
||
```
|
||
|
||
Ответ:
|
||
|
||
- `OK` после того, как прошивка записана и перезагрузка запланирована
|
||
- `401 Unauthorized`, если токен отсутствует или устарел
|
||
- `400` или `500`, если загрузка или проверка прошивки не удалась
|
||
|
||
### `GET /api/stats`
|
||
|
||
Получить текущий сводный payload, который использует отдельная страница `/stats`.
|
||
|
||
Заголовки:
|
||
|
||
```text
|
||
X-Auth-Token: <token>
|
||
```
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk https://<repeater-ip>/api/stats \
|
||
-H "X-Auth-Token: $TOKEN"
|
||
```
|
||
|
||
Примечания:
|
||
|
||
- именно это сводное представление веб-панель из репозитория запрашивает первым, прежде чем загружать серии трендов
|
||
- если `web.stats` отключён, эндпоинт возвращает `503 Service Unavailable`
|
||
- поддерживаемые платы могут также включать необязательный объект `sensors` в сводный payload для текущей телеметрии GPS и окружающей среды
|
||
- объект `core` включает необработанный `battery_mv`, сообщаемый платой `battery_pct`, когда он доступен, готовый для UI `battery_display_pct` и специфичные для платы подсказки диапазона `battery_min_mv` / `battery_max_mv`, которые использует `/stats`, когда плата не предоставляет собственный процент заряда батареи
|
||
|
||
### `GET /api/stats?series=<name>`
|
||
|
||
Получить одну серию тренда.
|
||
|
||
Поддерживаемые серии:
|
||
|
||
- `battery`
|
||
- `memory`
|
||
- `signal`
|
||
- `noise_floor`
|
||
- `packets`
|
||
- `voltage`
|
||
- `sensor_temp`
|
||
- `humidity`
|
||
- `pressure`
|
||
- `pressure_altitude`
|
||
- `mcu_temp`
|
||
- `gps_altitude`
|
||
- `gps_satellites`
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk "https://<repeater-ip>/api/stats?series=memory" \
|
||
-H "X-Auth-Token: $TOKEN"
|
||
```
|
||
|
||
Примечания:
|
||
|
||
- используйте `?series=battery`, а не просто `?series`
|
||
- встроенная веб-панель загружает эти серии последовательно, а не все сразу, чтобы снизить нагрузку на память платы
|
||
- серии окружающей среды включаются только когда плата сообщает эти показания; если в серии ещё нет сохранённых точек, она возвращает пустой массив `points` и `current:null`
|
||
|
||
### `GET /api/stats?view=legacy`
|
||
|
||
Получить более старый payload статистики в стиле bundle.
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk "https://<repeater-ip>/api/stats?view=legacy" \
|
||
-H "X-Auth-Token: $TOKEN"
|
||
```
|
||
|
||
Он существует для совместимости и диагностики. Для новых интеграций предпочитайте сводный эндпоинт плюс отдельные запросы `series`.
|
||
|
||
## Типовые сценарии использования
|
||
|
||
### 1. Удалённый доступ к CLI
|
||
|
||
`/api/command` — самый гибкий эндпоинт. Он позволяет выполнять те же команды CLI, которые принимает репитер.
|
||
|
||
Примеры:
|
||
|
||
- `get wifi.status`
|
||
- `get mqtt.status`
|
||
- `get web.status`
|
||
- `get web.stats.status`
|
||
- `get repeat`
|
||
- `get radio`
|
||
|
||
Это полезно для:
|
||
|
||
- удалённой диагностики с ноутбука или телефона
|
||
- простых скриптов, которые собирают рабочее состояние
|
||
- админ-инструментов, которые хотят переиспользовать существующее поведение CLI вместо добавления новых эндпоинтов прошивки
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk https://<repeater-ip>/api/command \
|
||
-H "X-Auth-Token: $TOKEN" \
|
||
--data 'get mqtt.status'
|
||
```
|
||
|
||
### 2. Сборка лёгкого дашборда состояния
|
||
|
||
Используйте `/api/stats` для сводной информации и по одному вызову `series` за раз для линий трендов.
|
||
|
||
Рекомендуемый сценарий:
|
||
|
||
1. получите `/api/stats`
|
||
2. отобразите текущее состояние сервисов и сводные поля
|
||
3. запрашивайте одну серию тренда только когда это нужно
|
||
4. обновляйте с интервалом `60` секунд или реже, если репитер загружен
|
||
|
||
Это тот же базовый сценарий, который использует встроенная страница `/stats`.
|
||
|
||
### 3. Использование API для быстрых проверок работоспособности
|
||
|
||
Поскольку `/api/command` возвращает вывод CLI напрямую, он хорошо подходит для небольших эксплуатационных проверок в скриптах или домашнем мониторинге.
|
||
|
||
Примеры:
|
||
|
||
- убедиться, что у репитера по-прежнему есть Wi-Fi
|
||
- проверить состояние подключения к MQTT-брокеру
|
||
- убедиться, что веб-панель включена, прежде чем пытаться читать статистику
|
||
- убедиться в текущих настройках радио перед применением изменений
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk https://<repeater-ip>/api/command \
|
||
-H "X-Auth-Token: $TOKEN" \
|
||
--data 'get web.status'
|
||
```
|
||
|
||
### 4. Удалённые административные действия
|
||
|
||
Веб-панель также использует `/api/command` для действий оператора, а не только для запросов на чтение.
|
||
|
||
Примеры:
|
||
|
||
- `advert`
|
||
- `reboot`
|
||
- `start ota`
|
||
- `time <epoch>`
|
||
- `time.force <epoch>`
|
||
|
||
Это мощные команды. Относитесь к ним так же, как к прямому доступу к CLI через последовательный порт.
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk https://<repeater-ip>/api/command \
|
||
-H "X-Auth-Token: $TOKEN" \
|
||
--data 'advert'
|
||
```
|
||
|
||
### 5. Помощники удалённой настройки
|
||
|
||
Веб-панель сохраняет настройки, генерируя команды CLI и отправляя их через `/api/command`.
|
||
|
||
Это значит, что ваши собственные инструменты могут делать то же самое для специфичных для PosadMesh настроек, таких как:
|
||
|
||
- поля идентичности репитера
|
||
- информация о владельце
|
||
- переключатели MQTT-брокера
|
||
- метаданные владельца MQTT PosadMesh
|
||
- настройки радио, поддерживаемые CLI репитера
|
||
|
||
Это практичный способ автоматизировать настройку, сохраняя существующую семантику CLI.
|
||
|
||
## Пример скрипта
|
||
|
||
Этот пример на shell выполняет вход, получает сводную статистику, получает одну серию тренда и запускает команду CLI:
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
set -euo pipefail
|
||
|
||
BASE_URL="https://192.168.1.123"
|
||
PASSWORD="your-admin-password"
|
||
|
||
TOKEN=$(curl -sk -X POST "$BASE_URL/login" --data "$PASSWORD")
|
||
|
||
echo "Summary:"
|
||
curl -sk "$BASE_URL/api/stats" \
|
||
-H "X-Auth-Token: $TOKEN"
|
||
|
||
echo
|
||
echo "Memory trend:"
|
||
curl -sk "$BASE_URL/api/stats?series=memory" \
|
||
-H "X-Auth-Token: $TOKEN"
|
||
|
||
echo
|
||
echo "MQTT status:"
|
||
curl -sk "$BASE_URL/api/command" \
|
||
-H "X-Auth-Token: $TOKEN" \
|
||
--data 'get mqtt.status'
|
||
```
|
||
|
||
## Случаи ошибок
|
||
|
||
Частые ответы:
|
||
|
||
- `401 Unauthorized`: токен отсутствует или истёк
|
||
- `503 Service Unavailable`: статистика отключена
|
||
- `404 No stats data`: запрошенный payload статистики не удалось собрать
|
||
- `400 Bad request`: некорректное тело запроса входа или команды
|
||
|
||
Если запросы статистики не выполняются:
|
||
|
||
1. убедитесь, что веб-панель включена
|
||
2. убедитесь, что `web.stats` включён
|
||
3. убедитесь, что токен сессии всё ещё действителен
|
||
4. снизьте частоту опроса, если плата испытывает нехватку памяти
|
||
|
||
## Практические рекомендации
|
||
|
||
- предпочитайте `/api/command`, когда нужен точный паритет с CLI
|
||
- предпочитайте `/api/stats` для дашбордов и представлений трендов
|
||
- держите опрос умеренным, особенно на репитерах с двумя активными MQTT-соединениями
|
||
- если вы закончили диагностику, рассмотрите отключение веб-панели командой `set web off`, чтобы максимизировать запас heap на ограниченных платах
|