Веб-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
error_rate
core0_util
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.md 14 KB

Постоянная ссылка История Исходник

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

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

Базовый URL

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

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

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

`POST /login`

`POST /api/command`

`GET /api/stats`

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

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

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

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

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

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

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

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

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

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

api.md 14 KB Постоянная ссылка История Исходник

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

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

Базовый URL

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

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

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

POST /login

POST /api/command

GET /api/stats

GET /api/stats?series=<name>

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

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

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

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

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

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

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

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

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

api.md 14 KB

Постоянная ссылка История Исходник

`POST /login`

`POST /api/command`

`GET /api/stats`

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