Skip to content

API.md

Latest commit

 

History

History
224 lines (178 loc) · 3.71 KB

API.md

File metadata and controls

224 lines (178 loc) · 3.71 KB

HTTP API

This firmware exposes a small HTTP API alongside the web UI.

All API routes:

  • are LAN-only
  • use the same HTTP Basic Auth as the web UI
  • use username admin
  • return JSON on success

Base URL examples:

  • http://192.168.1.42
  • http://heltec-ab12cd.local

Example auth:

curl -u admin:YOUR_PASSWORD http://192.168.1.42/api/stats

Endpoints

GET /api/temp

Returns only the die temperature plus basic identity.

Example:

{
  "die_temperature_c": 24,
  "firmware": "v0.8.0-heltec_v3",
  "hostname": "heltec-ab12cd"
}

GET /api/system

Returns basic device identity and live host connection info.

Example:

{
  "board": "Heltec WiFi LoRa 32 V3",
  "firmware": "v0.8.0-heltec_v3",
  "hostname": "heltec-ab12cd",
  "mdns": "heltec-ab12cd.local",
  "interface": "Wi-Fi",
  "current_ip": "192.168.1.42",
  "connected_client_ip": "192.168.1.10",
  "uptime_sec": 42,
  "uptime": "00:00:42",
  "die_temperature_c": 24
}

GET /api/radio

Returns the current live radio settings.

Example:

{
  "state": "RX/Idle",
  "standby": false,
  "auto_cad_enabled": false,
  "frequency_hz": 910525000,
  "frequency_mhz": 910.525,
  "bandwidth_hz": 62500,
  "bandwidth_khz": 62.5,
  "spreading_factor": 7,
  "coding_rate": 5,
  "tx_power_dbm": 22,
  "syncword": "0x3444",
  "syncword_value": 13380,
  "preamble_len": 17
}

GET /api/network

Returns live network status plus the saved network configuration.

Example:

{
  "mode": "static",
  "use_static_ip": true,
  "interface": "Wi-Fi",
  "live": true,
  "current_ip": "192.168.1.42",
  "subnet": "255.255.255.0",
  "gateway": "192.168.1.1",
  "dns1": "1.1.1.1",
  "dns2": "8.8.8.8",
  "tcp_port": 5055,
  "pymc_token_set": true,
  "saved": {
    "static_ip": "192.168.1.42",
    "subnet": "255.255.255.0",
    "gateway": "192.168.1.1",
    "dns1": "1.1.1.1",
    "dns2": "8.8.8.8"
  }
}

GET /api/stats

Returns the combined system, radio, counters, and network state in one response.

Top-level keys:

  • system
  • radio
  • counters
  • network

GET /api/config

Returns the saved editable configuration.

Example:

{
  "hostname": "heltec-ab12cd",
  "effective_hostname": "heltec-ab12cd",
  "tcp_token": "your-token",
  "tcp_port": 5055,
  "use_static_ip": true,
  "static_ip": "192.168.1.42",
  "subnet": "255.255.255.0",
  "gateway": "192.168.1.1",
  "dns1": "1.1.1.1",
  "dns2": "8.8.8.8"
}

POST /api/config

Updates saved config and reboots the modem.

Accepted top-level fields:

  • hostname
  • tcp_token
  • tcp_port
  • use_static_ip
  • network

network fields:

  • use_static_ip
  • static_ip
  • subnet
  • gateway
  • dns1
  • dns2

Notes:

  • fields you omit are left unchanged
  • set hostname to "" to reset to the default MAC-derived hostname
  • set tcp_token to "" to clear the pyMC token
  • if use_static_ip is true, static_ip, subnet, and gateway must be valid
  • a successful request always reboots the modem

Example:

curl -u admin:YOUR_PASSWORD \
  -H 'Content-Type: application/json' \
  -d '{
    "hostname": "heltec-ab12cd",
    "tcp_token": "meshpass",
    "network": {
      "use_static_ip": true,
      "static_ip": "192.168.1.42",
      "subnet": "255.255.255.0",
      "gateway": "192.168.1.1",
      "dns1": "1.1.1.1",
      "dns2": "8.8.8.8"
    }
  }' \
  http://192.168.1.42/api/config

Success response:

{
  "status": "saved",
  "rebooting": true,
  "config": {
    "...": "updated values"
  }
}

Error response:

{
  "error": "message here"
}

POST /api/reboot

Reboots the modem immediately.

Example:

curl -u admin:YOUR_PASSWORD -X POST http://192.168.1.42/api/reboot

Response:

{
  "status": "rebooting"
}