diff --git a/README.md b/README.md index 271dc3b..e3b4aa0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ -# ODROID Remote HTTP Power Manager (OWPM) +# ODROID Power Mate -A web-based remote power and monitoring tool for ODROID Single Board Computers (SBCs), powered by an ESP32. This project provides a comprehensive web interface to control power, monitor real-time metrics, and access the serial console of your ODROID from any web browser on your local network. +A web-based remote power and monitoring tool for ODROID Single Board Computers (SBCs), powered by an ESP32-C3. + +This project provides a comprehensive web interface to control power, monitor real-time metrics, and access the serial console of your ODROID from any web browser on your local network. ## Features @@ -13,73 +15,59 @@ A web-based remote power and monitoring tool for ODROID Single Board Computers ( - Scan and connect to Wi-Fi networks (STA mode). - Enable Access Point mode (AP+STA) to connect directly to the device. - Configure static IP settings. -- **System Info**: View device uptime and connection status. -- **Customizable Theme**: Switch between light and dark modes, with the preference saved locally. ## Prerequisites Before you begin, ensure you have the following installed and configured on your system: -- **[ESP-IDF (Espressif IoT Development Framework)](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html)**: This project is developed and tested with ESP-IDF v5.x. +- **[ESP-IDF (Espressif IoT Development Framework)](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/get-started/index.html)**: This project is developed and tested with ESP-IDF v5.x. - **[Node.js and npm](https://nodejs.org/)**: Required to build the web application. Node.js LTS version (e.g., 18.x or later) is recommended. ## How to Build and Flash 1. **Clone the repository:** ```bash - git clone - cd odroid-remote-http + git clone https://git.sys114.com/shinys000114/odroid-power-mate.git + cd odroid-power-mate ``` - -2. **Build the Web Application:** - The web interface needs to be compiled before building the main firmware. - ```bash - cd page - npm install - npm run build - cd .. - ``` - -3. **Set up the ESP-IDF environment:** +2. **Set up the ESP-IDF environment:** Open a terminal and source the ESP-IDF export script. The path may vary depending on your installation location. ```bash . $HOME/esp/esp-idf/export.sh ``` - -4. **Set the target chip:** - Specify your ESP32 variant (e.g., `esp32`, `esp32s3`). - ```bash - idf.py set-target esp32 - ``` - -5. **(Optional) Configure the project:** +3. **(Optional) Configure the project:** You can configure project-specific settings, such as default Wi-Fi credentials, by running `menuconfig`. ```bash idf.py menuconfig ``` -6. **Build the project:** - This command compiles the application, bootloader, partition table, and embeds the compiled web page data. +4. **Build the project:** + This command compiles the application, bootloader, partition table, and web page data. ```bash idf.py build ``` -7. **Flash the firmware:** - Connect your ESP32 board to your computer and replace `/dev/ttyUSB0` with your device's serial port. +5. **Flash the firmware:** + Connect your `ODROID Power Mate` board to your computer and replace `/dev/ttyACM0` with your device's serial port. ```bash - idf.py -p /dev/ttyUSB0 flash + idf.py -p /dev/ttyACM0 flash ``` -8. **Monitor the output:** +6. **Monitor the output:** To view the serial logs from the device, use the `monitor` command. This is useful for finding the device's IP address after it connects to your Wi-Fi. ```bash - idf.py -p /dev/ttyUSB0 monitor + idf.py -p /dev/ttyACM0 monitor ``` To exit the monitor, press `Ctrl+]`. + Otherwise, you can use minicom + ```bash + minicom -D /dev/ttyACM0 -b 115200 + ``` + ## Usage -1. After flashing, the ESP32 will either connect to the pre-configured Wi-Fi network or start an Access Point (AP). +1. After flashing, the ESP32 will either connect to the pre-configured Wi-Fi network or start an Access Point (APSTA). 2. Check the serial monitor logs to find the IP address assigned to the device in STA mode, or the default AP address (usually `192.168.4.1`). 3. Open a web browser and navigate to the device's IP address. 4. You should now see the ODROID Remote control panel. \ No newline at end of file diff --git a/docs/API.md b/docs/API.md index 22f339a..0609a97 100644 --- a/docs/API.md +++ b/docs/API.md @@ -16,10 +16,10 @@ The server pushes messages to the client, which can be either JSON objects or ra #### 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}` | +| 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`: @@ -88,13 +88,12 @@ Sets the state of power relays or triggers a power action. You can send one or m ``` - **Request Fields**: - - `load_12v_on` (boolean, optional): Set the state of the 12V relay. - - `load_5v_on` (boolean, optional): Set the state of the 5V relay. - - `reset_trigger` (boolean, optional): If `true`, momentarily triggers the reset button. - - `power_trigger` (boolean, optional): If `true`, momentarily triggers the power button. + - `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. - **Success Response**: `204 No Content` -- **Error Response**: `400 Bad Request` if the request body is invalid. --- @@ -127,7 +126,12 @@ Retrieves the complete current network configuration. - `ssid` (string): The SSID of the connected network. - `mode` (string): The current Wi-Fi mode (`"sta"` or `"apsta"`). - `net_type` (string): The network type (`"dhcp"` or `"static"`). - - `ip` (object): Contains IP details. Present even if using DHCP (may show last-leased IP). + - `ip` (object): Contains IP configuration details. Present even if using DHCP (may show 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` @@ -152,14 +156,17 @@ 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.* ```json { - "net_type": "static", + "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**: `204 No Content` @@ -207,3 +214,18 @@ Scans for available Wi-Fi networks. - `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"`). + +--- + +### 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.