MeshCore-Posadmesh/posadmesh-docs/api.md

Веб-API репитера

Эта страница описывает локальный HTTPS API, который предоставляют сборки PosadMesh *_repeater_mqtt с поддержкой веб-панели.

Он предназначен для:

• небольшой автоматизации в вашей локальной сети
• дашбордов или скриптов, которым нужен текущий статус репитера
• удалённого доступа к CLI через тот же аутентифицированный путь, который использует веб-панель

Это не облачный API и не отдельный серверный сервис. Его напрямую обслуживает прошивка репитера.

С чего начать

Для обычного использования PosadMesh эта страница не нужна. Обратитесь к Веб-панели репитера, если вы просто хотите настроить или проверить репитер в браузере.

Используйте эту страницу, когда нужно, чтобы локальный скрипт, дашборд или домашний инструмент общался с репитером напрямую.

Простейший полезный сценарий работы с API:

1. войдите с паролем администратора репитера
2. сохраните полученный токен
3. отправьте команду CLI через /api/command

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-адрес репитера:

https://<repeater-ip>/

Пример:

https://192.168.1.123/

Аутентификация

API использует тот же пароль администратора, что и CLI репитера и веб-панель.

1. отправьте POST с паролем на /login
2. сохраните полученный токен сессии
3. передавайте этот токен в заголовке X-Auth-Token в последующих запросах

Пример:

TOKEN=$(curl -sk -X POST https://<repeater-ip>/login --data '<admin-password>')

Использование токена:

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

Аутентификация с паролем администратора репитера.

Тело запроса:

<admin-password>

Ответ:

• токен сессии в виде обычного текста при успехе
• 401 при неверном пароле

Пример:

curl -sk -X POST https://<repeater-ip>/login --data '<admin-password>'

GET /api/session

Проверка, действителен ли сохранённый токен сессии.

Заголовки:

X-Auth-Token: <token>

Ответ:

• JSON {"authenticated":true} при успехе
• 401 Unauthorized, если токен отсутствует или устарел после блокировки, перезапуска или перепрошивки

POST /api/command

Удалённый запуск команды CLI репитера.

Заголовки:

X-Auth-Token: <token>

Тело запроса:

get wifi.status

Ответ:

• вывод CLI в виде обычного текста
• OK, если команда выполняется успешно и не возвращает текст

Пример:

curl -sk https://<repeater-ip>/api/command \
  -H "X-Auth-Token: $TOKEN" \
  --data 'get wifi.status'

POST /api/firmware-update

Загрузите .bin прошивки приложения через HTTPS-веб-панель и перезагрузитесь после успешного обновления.

Заголовки:

X-Auth-Token: <token>
X-Firmware-MD5: <32-character md5>
Content-Type: application/octet-stream

Тело запроса:

raw firmware .bin bytes

Ответ:

• OK после того, как прошивка записана и перезагрузка запланирована
• 401 Unauthorized, если токен отсутствует или устарел
• 400 или 500, если загрузка или проверка прошивки не удалась

GET /api/stats

Получить текущий сводный payload, который использует отдельная страница /stats.

Заголовки:

X-Auth-Token: <token>

Пример:

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

Пример:

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.

Пример:

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 вместо добавления новых эндпоинтов прошивки

Пример:

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-брокеру
• убедиться, что веб-панель включена, прежде чем пытаться читать статистику
• убедиться в текущих настройках радио перед применением изменений

Пример:

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 через последовательный порт.

Пример:

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:

#!/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 на ограниченных платах