Веб-API ретранслятора¶

На этой странице описывается локальный HTTPS API, предоставляемый сборками MeshCoreTel-firmware, который поддерживает веб-панель.

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

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

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

Область применения и доступность¶

API доступно только при соблюдении следующих условий:

вы используете поддерживаемую сборку прошивки
веб-панель ретранслятора включена и работает
вы можете связаться с ретранслятором по локальной сети
вы аутентифицировались с паролем администратора ретранслятора

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

Базовый URL¶

Используйте локальный HTTPS-адрес ретранслятора:

https://<repeater-ip>/

Пример:

https://192.168.1.123/

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

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

Отправьте пароль методом POST на /login
сохраните возвращённый токен сессии
передавайте этот токен в заголовке 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
повторный вход даст новый токен

Конечные точки¶

`POST /login`¶

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

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

<admin-password>

Ответ:

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

Пример:

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

`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'

`GET /api/stats`¶

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

Заголовки:

X-Auth-Token: <token>

Пример:

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
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

Типовые сценарии использования¶

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 для линий трендов.

Рекомендуемый шаблон:

запросите /api/stats
отобразите текущее состояние служб и сводные поля
запрашивайте один ряд тренда только по необходимости
обновляйте с интервалом 60 секунд или реже, если ретранслятор загружен

Это тот же базовый шаблон, что используется встроенной страницей /stats.

3. Использование API для быстрых проверок работоспособности¶

Поскольку /api/command возвращает вывод CLI напрямую, он хорошо подходит для небольших операционных проверок в скриптах или домашнем мониторинге.

Примеры:

убедиться, что у ретранслятора всё ещё есть Wi-Fi
проверить состояние подключения к MQTT-брокеру
убедиться, что веб-панель включена перед попыткой чтения статистики
проверить текущие настройки LoRa перед применением изменений

Пример:

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.

Это означает, что ваши собственные инструменты могут делать то же самое для специфичных для MeshCoreTel-firmware настроек, таких как:

поля идентификации ретранслятора
информация о владельце
переключатели MQTT-брокеров
метаданные владельца MQTT
LoRa-настройки, поддерживаемые 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 "Сводка:"
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: некорректное тело запроса при входе или выполнении команды

Если запросы статистики не удаются:

убедитесь, что веб-панель включена
убедитесь, что web.stats включён
убедитесь, что токен сессии всё ещё действителен
уменьшите частоту опроса, если устройство испытывает нехватку памяти

Практические рекомендации¶

отдавайте предпочтение /api/command, когда нужно точное соответствие CLI
отдавайте предпочтение /api/stats для панелей мониторинга и просмотра трендов
делайте опрос консервативным, особенно на ретрансляторах с двумя активными MQTT-соединениями
если вы закончили диагностику, рассмотрите отключение веб-панели командой set web off, чтобы максимизировать запас памяти на устройствах с ограниченными ресурсами

Веб-API ретранслятора¶

Область применения и доступность¶

Базовый URL¶

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

Рекомендации по производительности¶

Конечные точки¶

POST /login¶

POST /api/command¶

GET /api/stats¶

GET /api/stats?series=<name>¶

Типовые сценарии использования¶

1. Удалённый доступ к CLI¶

2. Создание легковесной панели статуса¶

3. Использование API для быстрых проверок работоспособности¶

4. Удалённые административные действия¶

5. Помощники удалённой конфигурации¶

Пример скрипта¶

Варианты ошибок¶

Практические рекомендации¶

`POST /login`¶

`POST /api/command`¶

`GET /api/stats`¶

`GET /api/stats?series=<name>`¶