From 073280638e6248cb40ddd5d03348fcc3cdd78e9d Mon Sep 17 00:00:00 2001 From: Jared Dohrman Date: Mon, 20 Apr 2026 12:39:27 +1000 Subject: [PATCH] docs: add API guide --- docs/api.md | 340 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + mkdocs.yml | 1 + 3 files changed, 342 insertions(+) create mode 100644 docs/api.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..cd2c995d --- /dev/null +++ b/docs/api.md @@ -0,0 +1,340 @@ +# Repeater Web API + +This page documents the local HTTPS API exposed by EastMesh `*_repeater_mqtt` builds that support the web panel. + +It is intended for: + +- lightweight automation on your local network +- dashboards or scripts that need current repeater status +- remote CLI access through the same authenticated path used by the web panel + +This is not a cloud API and not a separate backend service. The repeater firmware serves it directly. + +## Scope And Availability + +The API is available only when: + +- you are running a supported `*_repeater_mqtt` firmware build +- the repeater web panel is enabled and running +- you can reach the repeater over the local network +- you have authenticated with the repeater admin password + +The API is intended for trusted local-network administration. Do not expose it directly to the public internet. + +## Base URL + +Use the repeater's local HTTPS address: + +```text +https:/// +``` + +Example: + +```text +https://192.168.1.123/ +``` + +## Authentication + +The API uses the same admin password as the repeater CLI and web panel. + +1. `POST` the password to `/login` +2. store the returned session token +3. send that token in the `X-Auth-Token` header on later requests + +Example: + +```bash +TOKEN=$(curl -sk -X POST https:///login --data '') +``` + +Use the token: + +```bash +curl -sk https:///api/stats -H "X-Auth-Token: $TOKEN" +``` + +Notes: + +- the repeater uses a self-signed certificate, so most tools will need `-k` or equivalent +- if the session expires or is locked, requests return `401 Unauthorized` +- logging in again gives you a fresh token + +## Performance Guidance + +The API runs on the repeater itself, so polling frequency matters. + +If the repeater is also running two MQTT connections, avoid frequent API polling. The current EastMesh usage pattern is: + +- `60` second polling for stats +- on-demand requests for everything else + +That is the recommended baseline if you want to avoid overloading the board. Keep the request rate low, avoid bursty polling, and prefer manual refresh or event-triggered reads for heavier operations. + +Recommended practice: + +- poll `/api/stats` no more than once per minute +- avoid scraping multiple endpoints in parallel +- use on-demand calls for configuration reads and CLI actions +- close out your session when you are finished and stop polling when not actively using the data + +## Endpoints + +### `POST /login` + +Authenticate with the repeater admin password. + +Request body: + +```text + +``` + +Response: + +- plain-text session token on success +- `401` on bad password + +Example: + +```bash +curl -sk -X POST https:///login --data '' +``` + +### `POST /api/command` + +Run a repeater CLI command remotely. + +Headers: + +```text +X-Auth-Token: +``` + +Request body: + +```text +get wifi.status +``` + +Response: + +- plain-text CLI output +- `OK` if a command succeeds without returning text + +Example: + +```bash +curl -sk https:///api/command \ + -H "X-Auth-Token: $TOKEN" \ + --data 'get wifi.status' +``` + +### `GET /api/stats` + +Fetch the current summary payload used by the dedicated `/stats` page. + +Headers: + +```text +X-Auth-Token: +``` + +Example: + +```bash +curl -sk https:///api/stats \ + -H "X-Auth-Token: $TOKEN" +``` + +Notes: + +- this summary view is also what the repo's web panel requests first before loading trend series +- if `web.stats` is disabled, the endpoint returns `503 Service Unavailable` + +### `GET /api/stats?series=` + +Fetch one trend series. + +Supported series: + +- `battery` +- `memory` +- `signal` +- `noise_floor` +- `packets` + +Example: + +```bash +curl -sk "https:///api/stats?series=memory" \ + -H "X-Auth-Token: $TOKEN" +``` + +Notes: + +- use `?series=battery`, not just `?series` +- the built-in web panel loads these series sequentially rather than all at once to keep board memory pressure lower + +### `GET /api/stats?view=legacy` + +Fetch the older bundle-style stats payload. + +Example: + +```bash +curl -sk "https:///api/stats?view=legacy" \ + -H "X-Auth-Token: $TOKEN" +``` + +This exists for compatibility and troubleshooting. For new integrations, prefer the summary endpoint plus specific `series` requests. + +## Common Use Cases + +### 1. Remote CLI Access + +`/api/command` is the most flexible endpoint. It lets you run the same CLI commands accepted by the repeater. + +Examples: + +- `get wifi.status` +- `get mqtt.status` +- `get web.status` +- `get web.stats.status` +- `get repeat` +- `get radio` + +This is useful for: + +- remote diagnostics from a laptop or phone +- simple scripts that collect operational state +- admin tools that want to reuse existing CLI behavior instead of adding new firmware endpoints + +Example: + +```bash +curl -sk https:///api/command \ + -H "X-Auth-Token: $TOKEN" \ + --data 'get mqtt.status' +``` + +### 2. Build A Lightweight Status Dashboard + +Use `/api/stats` for summary information and one `series` call at a time for trend lines. + +Recommended pattern: + +1. fetch `/api/stats` +2. render current service state and summary fields +3. fetch one trend series only when needed +4. refresh at `60` second intervals, or slower if the repeater is busy + +This is the same basic pattern used by the built-in `/stats` page. + +### 3. Reuse The API For Quick Health Checks + +Because `/api/command` returns CLI output directly, it works well for small operational checks in scripts or home-lab monitoring. + +Examples: + +- confirm the repeater still has Wi-Fi +- check MQTT broker connection state +- verify that the web panel is enabled before attempting stats reads +- confirm current radio settings before applying changes + +Example: + +```bash +curl -sk https:///api/command \ + -H "X-Auth-Token: $TOKEN" \ + --data 'get web.status' +``` + +### 4. Remote Admin Actions + +The web panel also uses `/api/command` for operator actions, not just read-only queries. + +Examples: + +- `advert` +- `reboot` +- `start ota` +- `time ` +- `time.force ` + +These are powerful commands. Treat them the same way you would treat direct serial CLI access. + +Example: + +```bash +curl -sk https:///api/command \ + -H "X-Auth-Token: $TOKEN" \ + --data 'advert' +``` + +### 5. Remote Configuration Helpers + +The web panel saves settings by generating CLI commands and sending them through `/api/command`. + +That means your own tools can do the same for EastMesh-specific settings such as: + +- repeater identity fields +- owner info +- MQTT broker toggles +- EastMesh MQTT owner metadata +- radio settings supported by the repeater CLI + +This is a practical way to automate setup while preserving existing CLI semantics. + +## Example Script + +This shell example logs in, fetches summary stats, fetches one trend series, and runs a CLI command: + +```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 "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' +``` + +## Error Cases + +Common responses: + +- `401 Unauthorized`: missing or expired token +- `503 Service Unavailable`: stats are disabled +- `404 No stats data`: requested stats payload could not be built +- `400 Bad request`: malformed login or command request body + +If stats requests fail: + +1. confirm the web panel is enabled +2. confirm `web.stats` is enabled +3. confirm the session token is still valid +4. reduce polling frequency if the board is under memory pressure + +## Practical Recommendations + +- prefer `/api/command` when you need exact CLI parity +- prefer `/api/stats` for dashboards and trend views +- keep polling conservative, especially on repeaters with two active MQTT connections +- if you are finished with troubleshooting, consider disabling the web panel with `set web off` to maximize heap headroom on constrained boards diff --git a/docs/index.md b/docs/index.md index cf8f4793..438bc502 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,6 +17,7 @@ If you are just trying to pick a board or download firmware, start with: - [Download and Flash Releases](./releases.md) - [Migration From xJARiD/MeshCore](./migration.md) - [Use the Repeater Web Panel](./web-panel.md) +- [Use the Repeater Web API](./api.md) - [Custom CLI Commands](./custom-cli.md) ## Developer Notes diff --git a/mkdocs.yml b/mkdocs.yml index 4953dcf6..b672cf8d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,5 +40,6 @@ nav: - Releases: releases.md - Migration: migration.md - Web Panel: web-panel.md + - Repeater API: api.md - Local Builds: local-builds.md - Custom CLI: custom-cli.md