# Веб-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`
- `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`, чтобы максимизировать запас памяти на устройствах с ограниченными ресурсами