Update API documentation

Signed-off-by: YoungSoo Shin <shinys000114@gmail.com>
This commit is contained in:
2025-08-27 12:57:21 +09:00
parent 0c1aa33fd0
commit 0b027365ea

View File

@@ -10,6 +10,8 @@ The WebSocket API provides a full-duplex communication channel for real-time dat
**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.
@@ -90,28 +92,30 @@ Sets the state of power relays or triggers a power action. You can send one or m
- **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. The action is triggered only on a `true` value.
- `power_trigger` (boolean, optional): If `true`, momentarily triggers the power button. The action is triggered only on a `true` value.
- `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**: `204 No Content`
- **Success Response (200 OK)**: `{"status":"ok"}`
---
### Endpoint: `/api/wifi`
### Endpoint: `/api/setting`
Manages all Wi-Fi and network-related configurations.
Manages all Wi-Fi, network, and system-related configurations.
#### `GET /api/wifi`
#### `GET /api/setting`
Retrieves the complete current network configuration.
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",
@@ -124,16 +128,18 @@ Retrieves the complete current network configuration.
- **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"`).
- `ip` (object): Contains IP configuration details. Present even if using DHCP (may show last-leased IP).
- `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/wifi`
#### `POST /api/setting`
This is a multi-purpose endpoint. The server determines the action based on the fields provided in the request body.
@@ -156,7 +162,7 @@ This is a multi-purpose endpoint. The server determines the action based on the
{ "net_type": "dhcp" }
```
- **Request Body (for Static IP)**:
*Note: The `ip` object structure is consistent with the `GET /api/wifi` response.*
*Note: The `ip` object structure is consistent with the `GET /api/setting` response.*
```json
{
"net_type": "static",
@@ -169,7 +175,9 @@ This is a multi-purpose endpoint. The server determines the action based on the
}
}
```
- **Success Response**: `204 No Content`
- **Success Response (200 OK)**:
- `{"status":"dhcp_config_applied"}`
- `{"status":"static_config_applied"}`
- **Action: Configure Wi-Fi Mode (STA/APSTA)**
- **Request Body (for STA mode)**:
@@ -185,7 +193,17 @@ This is a multi-purpose endpoint. The server determines the action based on the
}
```
*Note: `ap_password` is optional. If omitted, the AP will be open.*
- **Success Response**: `204 No Content`
- **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" }
```
---
@@ -217,6 +235,27 @@ Scans for available Wi-Fi networks.
---
### 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.