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` **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 ### 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. 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**: - **Request Fields**:
- `load_12v_on` (boolean, optional): Sets the state of the 12V relay. - `load_12v_on` (boolean, optional): Sets the state of the 12V relay.
- `load_5v_on` (boolean, optional): Sets the state of the 5V 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. - `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. 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)** - **Success Response (200 OK)**
```json ```json
{ {
"connected": true, "connected": true,
"ssid": "MyHome_WiFi", "ssid": "MyHome_WiFi",
"rssi": -65,
"mode": "apsta", "mode": "apsta",
"net_type": "static", "net_type": "static",
"baudrate": "115200",
"ip": { "ip": {
"ip": "192.168.1.100", "ip": "192.168.1.100",
"gateway": "192.168.1.1", "gateway": "192.168.1.1",
@@ -124,16 +128,18 @@ Retrieves the complete current network configuration.
- **Response Fields**: - **Response Fields**:
- `connected` (boolean): Current Wi-Fi connection state. - `connected` (boolean): Current Wi-Fi connection state.
- `ssid` (string): The SSID of the connected network. - `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"`). - `mode` (string): The current Wi-Fi mode (`"sta"` or `"apsta"`).
- `net_type` (string): The network type (`"dhcp"` or `"static"`). - `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. - `ip` (string): The device's IP address.
- `gateway` (string): The network gateway address. - `gateway` (string): The network gateway address.
- `subnet` (string): The network subnet mask. - `subnet` (string): The network subnet mask.
- `dns1` (string): The primary DNS server address. - `dns1` (string): The primary DNS server address.
- `dns2` (string): The secondary 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. 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" } { "net_type": "dhcp" }
``` ```
- **Request Body (for Static IP)**: - **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 ```json
{ {
"net_type": "static", "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)** - **Action: Configure Wi-Fi Mode (STA/APSTA)**
- **Request Body (for STA mode)**: - **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.* *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 ### General Error Responses
In case of an error, the server will respond with an appropriate HTTP status code. In case of an error, the server will respond with an appropriate HTTP status code.