odroid-power-mate/docs/API.md

ODROID Remote API Documentation

This document outlines the HTTP REST and WebSocket APIs for communication between the web interface and the ESP32 device.

---

WebSocket API

The WebSocket API provides a full-duplex communication channel for real-time data, such as sensor metrics and the interactive serial console.

Endpoint: /ws

Note

: The server only accepts one WebSocket client at a time. Subsequent connection attempts will be rejected with a 403 Forbidden error until the active client disconnects.

Server-to-Client Messages

The server pushes messages to the client, which can be either JSON objects or raw binary data. JSON messages always contain a type field to identify the payload.

JSON Messages

Type	Description	Payload Example
sensor_data	Pushed periodically (e.g., every second) with the latest power metrics.	{"type":"sensor_data", "voltage":12.01, "current":1.52, "power":18.25, "uptime_sec":3600, "timestamp": 1672531200}
wifi_status	Pushed periodically or on change to update the current Wi-Fi connection status.	{"type":"wifi_status", "connected":true, "ssid":"MyHome_WiFi", "rssi":-65}

Field Descriptions:

• sensor_data:
  • voltage (float): The measured voltage in Volts (V).
  • current (float): The measured current in Amperes (A).
  • power (float): The calculated power in Watts (W).
  • uptime_sec (integer): The system uptime in seconds.
  • timestamp (integer): A Unix timestamp (seconds) of when the measurement was taken.
• wifi_status:
  • connected (boolean): true if connected to a Wi-Fi network, false otherwise.
  • ssid (string): The SSID of the connected network. Null if not connected.
  • rssi (integer): The Received Signal Strength Indicator in dBm. Null if not connected.

Raw Binary Data

• Description: Raw binary data from the ODROID's serial (UART) port is forwarded directly to the client. This is used to display the terminal output.
• Payload: (binary data)

Client-to-Server Messages

The client primarily sends raw binary data, which is interpreted as terminal input.

• Description: Raw binary data representing user input from the web terminal. This data is forwarded directly to the ODROID's serial (UART) port.
• Payload: (binary data)

---

HTTP REST API

The REST API is used for configuration and to trigger specific actions. All request and response bodies are in application/json format.

Endpoint: /api/control

Manages power relays and system actions.

GET /api/control

Retrieves the current status of the power relays.

• Success Response (200 OK)

  {
    "load_12v_on": true,
    "load_5v_on": false
  }
  

  • load_12v_on (boolean): The state of the main 12V power relay.
  • load_5v_on (boolean): The state of the 5V USB power relay.

POST /api/control

Sets the state of power relays or triggers a power action. You can send one or more commands in a single request.

• Request Body Examples:

  • To turn the main power on:

    { "load_12v_on": true }
    

  • To trigger a system reset:

    { "reset_trigger": true }
    

  • To toggle the power button:

    { "power_trigger": true }
    

• Request Fields:

  • load_12v_on (boolean, optional): Sets the state of the 12V relay.
  • load_5v_on (boolean, optional): Sets the state of the 5V relay.
  • reset_trigger (boolean, optional): If true, momentarily triggers the reset button (pulls the line low for 3 seconds). The action is triggered only on a true value.
  • power_trigger (boolean, optional): If true, momentarily triggers the power button (pulls the line low for 3 seconds). The action is triggered only on a true value.

• Success Response (200 OK): {"status":"ok"}

---

Endpoint: /api/setting

Manages all Wi-Fi, network, and system-related configurations.

GET /api/setting

Retrieves the complete current network and system configuration.

• Success Response (200 OK)

  {
    "connected": true,
    "ssid": "MyHome_WiFi",
    "rssi": -65,
    "mode": "apsta",
    "net_type": "static",
    "baudrate": "115200",
    "ip": {
        "ip": "192.168.1.100",
        "gateway": "192.168.1.1",
        "subnet": "255.255.255.0",
        "dns1": "8.8.8.8",
        "dns2": "8.8.4.4"
    }
  }
  

• Response Fields:
  • connected (boolean): Current Wi-Fi connection state.
  • ssid (string): The SSID of the connected network.
  • rssi (integer): The Received Signal Strength Indicator in dBm. Only present if connected.
  • mode (string): The current Wi-Fi mode ("sta" or "apsta").
  • net_type (string): The network type ("dhcp" or "static").
  • baudrate (string): The current UART baud rate.
  • ip (object): Contains IP configuration details. Present even if using DHCP (may show the last-leased IP).
    • ip (string): The device's IP address.
    • gateway (string): The network gateway address.
    • subnet (string): The network subnet mask.
    • dns1 (string): The primary DNS server address.
    • dns2 (string): The secondary DNS server address.

POST /api/setting

This is a multi-purpose endpoint. The server determines the action based on the fields provided in the request body.

• Action: Connect to a Wi-Fi Network

  • Request Body:

    {
      "ssid": "MyHome_WiFi",
      "password": "my_secret_password"
    }
    

  • Success Response (200 OK):

    { "status": "connection_initiated" }
    

• Action: Configure Network Type (DHCP/Static)

  • Request Body (for DHCP):

    { "net_type": "dhcp" }
    

  • Request Body (for Static IP): Note: The ip object structure is consistent with the GET /api/setting response.

    {
      "net_type": "static",
      "ip": {
        "ip": "192.168.1.100",
        "gateway": "192.168.1.1",
        "subnet": "255.255.255.0",
        "dns1": "8.8.8.8",
        "dns2": "8.8.4.4"
      }
    }
    

  • Success Response (200 OK):
    • {"status":"dhcp_config_applied"}
    • {"status":"static_config_applied"}

• Action: Configure Wi-Fi Mode (STA/APSTA)

  • Request Body (for STA mode):

    { "mode": "sta" }
    

  • Request Body (for AP+STA mode):

    {
        "mode": "apsta",
        "ap_ssid": "ODROID-Remote-AP",
        "ap_password": "hardkernel"
    }
    

    Note: ap_password is optional. If omitted, the AP will be open.
  • Success Response (200 OK): {"status":"mode_switch_initiated"}

• Action: Configure UART Baud Rate

  • Request Body:

    { "baudrate": "115200" }
    

  • Success Response (200 OK):

    { "status": "baudrate_updated" }
    

---

Endpoint: /api/wifi/scan

Scans for available Wi-Fi networks.

GET /api/wifi/scan

• Success Response (200 OK): Returns a JSON array of found networks.

  [
    {
      "ssid": "MyHome_WiFi",
      "rssi": -55,
      "authmode": "WPA2_PSK"
    },
    {
      "ssid": "GuestNetwork",
      "rssi": -78,
      "authmode": "OPEN"
    }
  ]
  

• Response Fields:
  • ssid (string): The network's Service Set Identifier.
  • rssi (integer): Signal strength in dBm.
  • authmode (string): The authentication mode (e.g., "OPEN", "WPA_PSK", "WPA2_PSK").

---

Endpoint: /datalog.csv

Provides access to the historical sensor data log.

GET /datalog.csv

• Description: Downloads a CSV file containing the history of sensor data readings (voltage, current, power). The log is rotated when it reaches its maximum size (1MB).
• Success Response (200 OK): The body of the response is the CSV file content.
• Response Headers:
  • Content-Type: text/csv
  • Content-Disposition: attachment; filename="datalog.csv"
• CSV Format:

  timestamp,voltage,current,power
  1672531200,12.01,1.52,18.25
  1672531201,12.02,1.53,18.39
  ...
  

---

General Error Responses

In case of an error, the server will respond with an appropriate HTTP status code.

• 400 Bad Request: The request is malformed, contains invalid parameters, or is otherwise incorrect. The response body may contain a JSON object with more details.

  {
    "error": "Invalid request body"
  }
  

• 404 Not Found: The requested endpoint does not exist.
• 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.