Merge pull request #38 from xJARiD/develop

docs: add API guide

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://<repeater-ip>/
+```
+
+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://<repeater-ip>/login --data '<admin-password>')
+```
+
+Use the token:
+
+```bash
+curl -sk https://<repeater-ip>/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
+<admin-password>
+```
+
+Response:
+
+- plain-text session token on success
+- `401` on bad password
+
+Example:
+
+```bash
+curl -sk -X POST https://<repeater-ip>/login --data '<admin-password>'
+```
+
+### `POST /api/command`
+
+Run a repeater CLI command remotely.
+
+Headers:
+
+```text
+X-Auth-Token: <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://<repeater-ip>/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: <token>
+```
+
+Example:
+
+```bash
+curl -sk https://<repeater-ip>/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=<name>`
+
+Fetch one trend series.
+
+Supported series:
+
+- `battery`
+- `memory`
+- `signal`
+- `noise_floor`
+- `packets`
+
+Example:
+
+```bash
+curl -sk "https://<repeater-ip>/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://<repeater-ip>/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://<repeater-ip>/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://<repeater-ip>/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 <epoch>`
+- `time.force <epoch>`
+
+These are powerful commands. Treat them the same way you would treat direct serial CLI access.
+
+Example:
+
+```bash
+curl -sk https://<repeater-ip>/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

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

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