271 lines
8.9 KiB
Markdown
271 lines
8.9 KiB
Markdown
# 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)**
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{ "load_12v_on": true }
|
|
```
|
|
- To trigger a system reset:
|
|
```json
|
|
{ "reset_trigger": true }
|
|
```
|
|
- To toggle the power button:
|
|
```json
|
|
{ "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)**
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"ssid": "MyHome_WiFi",
|
|
"password": "my_secret_password"
|
|
}
|
|
```
|
|
- **Success Response (200 OK)**:
|
|
```json
|
|
{ "status": "connection_initiated" }
|
|
```
|
|
|
|
- **Action: Configure Network Type (DHCP/Static)**
|
|
- **Request Body (for DHCP)**:
|
|
```json
|
|
{ "net_type": "dhcp" }
|
|
```
|
|
- **Request Body (for Static IP)**:
|
|
*Note: The `ip` object structure is consistent with the `GET /api/setting` response.*
|
|
```json
|
|
{
|
|
"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)**:
|
|
```json
|
|
{ "mode": "sta" }
|
|
```
|
|
- **Request Body (for AP+STA mode)**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{ "baudrate": "115200" }
|
|
```
|
|
- **Success Response (200 OK)**:
|
|
```json
|
|
{ "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.
|
|
```json
|
|
[
|
|
{
|
|
"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**:
|
|
```csv
|
|
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.
|
|
```json
|
|
{
|
|
"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.
|