Skip to content

Hotspot API Server

Jump to bottom
Calin Crisan edited this page Aug 17, 2021 · 57 revisions

Table Of Contents

About

The Hotspot API Server is a small webserver written in Python that exposes an API dedicated to remote controlling the Chameleon OS.

The server lives at /opt/hotspot-api-server.

Authentication

Each request that requires authentication, must include an Authorization header containing HTTP basic auth data:

Authorization: Basic BASE64(<username:password>)

The username must always be admin.

API Calls

GET /summary

Returns a summary of the current hotspot state. Does not require authentication. Response body looks like this:

{
    "serial_number": "11068ec1",
    "os_prefix": "cham",
    "cpu_usage": 60, /* percent */
    "mem_used": 150, /* MB */
    "mem_total": 7192, /* MB */
    "storage_used": 58686, /* MB */
    "storage_total": 3205, /* MB */
    "temperature": 47, /* C */
    "miner_height": 762332,
    "miner_listen_addr": "/ip4/79.141.2.132/tcp/44158",
    "miner_listen_ok": true,
    "hotspot_name": "magnificent-midnight-wolf",
    "concentrator_model": "sx1302",
    "region": "EU868",
    "fw_version": "2021.03.09.0",
    "ecc_sn": "0123104236962a42ee",
    "swarm_key_mode": false,
    "address": "112axoWXqxrdT5Gd56iz7Mychkt9UU3EV3d9krTnkrLvodjJRYC2",
    "pub_key": "d0cfaae2f6157e55978e8a715a5117cd7a23b766d4419b762402d8de4839e0f8212a0c5120deca00c616fb1125617e8d7f6e47adff213349efc949735809d788",
    "eth_mac": "dc:a6:32:ad:aa:ff",
    "wlan_mac": "dc:a6:32:ad:ab:00",
    "uptime": 86400, /* seconds */
    "time": 1622664430 /* Unix timestamp, in seconds */
}

If the pretty=true query argument is passed, field names and their values are prepared for pretty printing.

If the quick=true query argument is passed, only values for fields that are immediately available will be returned.

GET /nettest

Performs a quick network connection analysis and returns the results. Does not require authentication. Response body looks like this:

{
    "download_speed": 2505.0, /* kBytes/s */
    "latency": 11, /* milliseconds */
    "public_ip": "79.114.24.84"
}

If download_speed=true, latency=true or public_ip=true query arguments are passed, only the corresponding parameter is tested and returned, the rest being set to null.

GET /selftest

Performs self tests and returns the results. Requires authentication.

Response body looks like this:

{
    "eth": true,
    "wlan": true,
    "bt": true,
    "ecc": true,
    "lora": true
}

GET /stats

Returns some stats about the hotspot. Does not require authentication. Response body looks like this:

{
    "blockchain_height": 862332,
    "rewards_1d": 8.32, /* HNT */
    "rewards_7d": 58.24, /* HNT */
    "rewards_30d": 249.6, /* HNT */
    "rewards_365d": 3036.8, /* HNT */
    "oracle_price": 14.123456 /* USD */
}

GET /activity

Returns the hotspot's recent activity. Does not require authentication. Response body looks like this:

[
    {
        "block": 868235,
        "time": 1622628182,
        "amount": 1974,
        "type": "rewards_v2"
    },
    ...
]

GET /config

Returns the current configuration. Requires authentication. Response body looks like this:

{
    "cpu_freq_max": 1500000, /* in kHz, null means default */
    "led_brightness": 50, /* from 0 to 100 */
    "led_ok_color": "green", /* red, green, blue, yellow, cyan, magenta, orange, white, off */
    "nat_external_ip": "72.012.123.234", /* can be null */
    "nat_external_port": 44159, /* can be null */
    "nat_internal_port": 44158, /* can be null */
    "pf_antenna_gain": 2.3, /* dBi */
    "pf_rssi_offset": -215.4, /* dBm */
    "pf_tx_power": 14 /* dB */,
    "remote_enabled": true
}

PATCH /config

Updates the configuration. Requires authentication. Request body looks like this:

{
    "cpu_freq_max": 1500000, /* in kHz, null means default */
    "led_brightness": 50, /* from 0 to 100 */
    "led_ok_color": "green", /* red, green, blue, yellow, cyan, magenta, orange, white, off */
    "nat_external_ip": "72.012.123.234", /* null disables */
    "nat_external_port": 44159, /* null disables */
    "nat_internal_port": 44158, /* null disables */
    "pf_antenna_gain": 2.3, /* dBi */
    "pf_rssi_offset": -215.4, /* dBm */
    "pf_tx_power": 14, /* dB */
    "password": "password1234",
    "old_password": "password123",
    "remote_enabled": true
}

All fields are optional. If a field is given as null, it will be restored to its default value.

If password is supplied, an additional old_password field must be included as well and must contain the current password.

POST /verify_password

Verifies a given password. Request body looks like this:

{
    "password": "password1234"
}

Returns 204 if password is valid and 200 (with a result message) otherwise.

POST /reboot

Reboots the unit. Requires authentication.

POST /pair

Enables temporary unit pairing mode. Requires authentication.

POST /resync

Forces a miner resynchronization. Requires authentication.

GET /fwupdate

Returns information about the currently running and latest firmware version. Requires authentication.

Request body looks like this:

{
    "current": "2021.07.09.0",
    "latest": "2021.07.09.0",
    "beta": false,
    "status": "idle"
}

Possible statuses are: idle, downloading, extracting, flashing boot, rebooting.

PATCH /fwupdate

Starts the firmware upgrade process. Requires authentication.

GET /logs/{name}

Returns the log indicated by name. Requires authentication.

If the optional max_lines query argument is supplied, the last indicated number of lines are returned (defaults to 1000).

The following logs are defined:

  • miner (/var/log/miner/console.log)
  • packet_forwarder (/var/log/packet_forwarder.log)
  • kernel (dmesg)
  • system (/var/log/messages)

POST /logs/start

Starts sending logs via MQTT. Logs will be sent until explicitly stopped or the unit is rebooted. Requires authentication.

See Logs Via MQTT.

POST /logs/stop

Stops sending logs via MQTT. See Logs Via MQTT.

Clone this wiki locally