Valentin V. Bartenev
88517878d6
web-panel.md: - Replace Start OTA nav item with dedicated Firmware Update section - Update Info panel: Version/Client Version → Hardware/Firmware - Add auto-refresh toggle to /stats element list - Expand Trends list: add error_rate, core0_util, mcu_temp, note RX/TX stacked rendering of packets series - Update sequential trend loading order accordingly - Rewrite OTA subsection to describe native HTTPS upload flow api.md: - Add error_rate and core0_util to supported series list boards.md: - Add DIY_ESP32S3_N16R8_E22_Back2back to repeater_mqtt table local-builds.md: - Add DIY_ESP32S3_N16R8_E22_Back2back_repeater_mqtt - Add Ebyte_EoRa-S3_Repeater_mqtt - Add ThinkNode_M2_Repeater_mqtt - Add ThinkNode_M5_Repeater_mqtt
341 lines
14 KiB
Markdown
341 lines
14 KiB
Markdown
# Веб-API ретранслятора
|
||
|
||
На этой странице описывается локальный HTTPS API, предоставляемый сборками MeshCoreTel-firmware, который поддерживает веб-панель.
|
||
|
||
Он предназначен для:
|
||
|
||
- легковесной автоматизации в вашей локальной сети
|
||
- панелей мониторинга или скриптов, которым требуется текущее состояние ретранслятора
|
||
- удалённого доступа к CLI по тому же аутентифицированному пути, который используется веб-панелью
|
||
|
||
Это не облачный API и не отдельный фоновый сервис. Прошивка ретранслятора предоставляет его напрямую.
|
||
|
||
## Область применения и доступность
|
||
|
||
API доступно только при соблюдении следующих условий:
|
||
|
||
- вы используете поддерживаемую сборку прошивки
|
||
- веб-панель ретранслятора включена и работает
|
||
- вы можете связаться с ретранслятором по локальной сети
|
||
- вы аутентифицировались с паролем администратора ретранслятора
|
||
|
||
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. Текущая модель использования MeshCoreTel-firmware:
|
||
|
||
- опрос статистики раз в `60` секунд
|
||
- запросы по требованию для всего остального
|
||
|
||
Это рекомендуемый базовый уровень, если вы хотите избежать перегрузки устройства. Держите частоту запросов низкой, избегайте шквального опроса и отдавайте предпочтение ручному обновлению или чтению по событиям для более тяжёлых операций.
|
||
|
||
Рекомендуемая практика:
|
||
|
||
- опрашивайте `/api/stats` не чаще одного раза в минуту
|
||
- избегайте параллельного запроса нескольких конечных точек
|
||
- используйте вызовы по требованию для чтения конфигурации и действий CLI
|
||
- завершайте сессию, когда закончили, и прекращайте опрос, когда данные активно не используются
|
||
|
||
## Конечные точки
|
||
|
||
### `POST /login`
|
||
|
||
Аутентификация с паролем администратора ретранслятора.
|
||
|
||
Тело запроса:
|
||
|
||
```text
|
||
<admin-password>
|
||
```
|
||
|
||
Ответ:
|
||
|
||
- токен сессии в виде обычного текста при успехе
|
||
- `401` при неверном пароле
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
curl -sk -X POST https://<repeater-ip>/login --data '<admin-password>'
|
||
```
|
||
|
||
### `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'
|
||
```
|
||
|
||
### `GET /api/stats`
|
||
|
||
Получить сводные данные, используемые на отдельной странице `/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` в сводных данных с текущей телеметрией GPS и окружающей среды
|
||
- объект `core` включает исходное `battery_mv`, `battery_pct` (если устройство сообщает), готовый для интерфейса `battery_display_pct`, а также специфичные для устройства подсказки диапазона `battery_min_mv` / `battery_max_mv`, используемые `/stats`, когда устройство не предоставляет собственный процент заряда
|
||
|
||
### `GET /api/stats?series=<name>`
|
||
|
||
Получить один ряд тренда.
|
||
|
||
Поддерживаемые ряды:
|
||
|
||
- `battery`
|
||
- `memory`
|
||
- `signal`
|
||
- `noise_floor`
|
||
- `packets`
|
||
- `error_rate`
|
||
- `core0_util`
|
||
- `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`
|
||
|
||
## Типовые сценарии использования
|
||
|
||
### 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-брокеру
|
||
- убедиться, что веб-панель включена перед попыткой чтения статистики
|
||
- проверить текущие настройки LoRa перед применением изменений
|
||
|
||
Пример:
|
||
|
||
```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`.
|
||
|
||
Это означает, что ваши собственные инструменты могут делать то же самое для специфичных для MeshCoreTel-firmware настроек, таких как:
|
||
|
||
- поля идентификации ретранслятора
|
||
- информация о владельце
|
||
- переключатели MQTT-брокеров
|
||
- метаданные владельца MQTT
|
||
- LoRa-настройки, поддерживаемые 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 "Сводка:"
|
||
curl -sk "$BASE_URL/api/stats" \
|
||
-H "X-Auth-Token: $TOKEN"
|
||
|
||
echo
|
||
echo "Тренд памяти:"
|
||
curl -sk "$BASE_URL/api/stats?series=memory" \
|
||
-H "X-Auth-Token: $TOKEN"
|
||
|
||
echo
|
||
echo "Статус MQTT:"
|
||
curl -sk "$BASE_URL/api/command" \
|
||
-H "X-Auth-Token: $TOKEN" \
|
||
--data 'get mqtt.status'
|
||
```
|
||
|
||
## Варианты ошибок
|
||
|
||
Типичные ответы:
|
||
|
||
- `401 Unauthorized`: отсутствует или истёк токен
|
||
- `503 Service Unavailable`: статистика отключена
|
||
- `404 No stats data`: не удалось сформировать запрошенные данные статистики
|
||
- `400 Bad request`: некорректное тело запроса при входе или выполнении команды
|
||
|
||
Если запросы статистики не удаются:
|
||
|
||
1. убедитесь, что веб-панель включена
|
||
2. убедитесь, что `web.stats` включён
|
||
3. убедитесь, что токен сессии всё ещё действителен
|
||
4. уменьшите частоту опроса, если устройство испытывает нехватку памяти
|
||
|
||
## Практические рекомендации
|
||
|
||
- отдавайте предпочтение `/api/command`, когда нужно точное соответствие CLI
|
||
- отдавайте предпочтение `/api/stats` для панелей мониторинга и просмотра трендов
|
||
- делайте опрос консервативным, особенно на ретрансляторах с двумя активными MQTT-соединениями
|
||
- если вы закончили диагностику, рассмотрите отключение веб-панели командой `set web off`, чтобы максимизировать запас памяти на устройствах с ограниченными ресурсами
|