62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
# Web Interface and REST API
|
|
|
|
This document describes the web interfaces provided by the firmware.
|
|
|
|
## Static Web UI
|
|
|
|
The device serves a static web interface (built using React, located in `../web-basic/dist` during development) from its root URL (`/`).
|
|
|
|
- **URL:** `http://<device-ip>/`
|
|
- **Functionality:** Provides a user interface for monitoring and potentially controlling the device. All dynamic data is fetched via the REST API described below.
|
|
|
|
## REST API
|
|
|
|
The device exposes a RESTful API for programmatic interaction under the `/api/v1/` path.
|
|
|
|
The API specification follows the OpenAPI 3.0 standard and can be viewed:
|
|
|
|
- **Live Docs (Swagger UI):** `http://<device-ip>/api-docs` (Serves Swagger UI interface)
|
|
- **Specification File:** `http://<device-ip>/api/swagger.yaml`
|
|
|
|
### Endpoints
|
|
|
|
#### System
|
|
|
|
* **`GET /api/v1/system/info`**
|
|
* **Description:** Retrieves general system information, including firmware version, board name, uptime, and a list of components registered with the Modbus manager.
|
|
* **Response:** JSON object containing system details and an array of component objects (`id`, `name`, `startAddress`, `count`).
|
|
|
|
* **`GET /api/v1/system/logs`**
|
|
* **Description:** Retrieves recent system log messages captured in an internal buffer.
|
|
* **Response:** JSON array of strings, with each string being a log line (oldest first, up to 300 lines).
|
|
|
|
#### Coils
|
|
|
|
* **`GET /api/v1/coils`**
|
|
* **Description:** Retrieves the status of all registered Modbus coils.
|
|
* **Response:** JSON object `{ "coils": [ { "address": <int>, "value": <bool> }, ... ] }`.
|
|
* **`GET /api/v1/coils?address=<addr>`**
|
|
* **Description:** Retrieves the status of a specific Modbus coil by its address.
|
|
* **Response:** JSON object `{ "address": <int>, "value": <bool> }` or `404 Not Found`.
|
|
* **`POST /api/v1/coils/<addr>?value=<0|1|true|false>`**
|
|
* **Description:** Sets the state of a specific Modbus coil.
|
|
* **Response:** JSON object `{ "success": true, "address": <int>, "value": <bool> }` or error status (`400`, `404`).
|
|
|
|
#### Registers
|
|
|
|
* **`GET /api/v1/registers`**
|
|
* **Description:** Retrieves the value of all registered Modbus holding registers.
|
|
* **Response:** JSON object `{ "registers": [ { "address": <int>, "value": <int> }, ... ] }`.
|
|
* **`GET /api/v1/registers?address=<addr>`**
|
|
* **Description:** Retrieves the value of a specific Modbus holding register by its address.
|
|
* **Response:** JSON object `{ "address": <int>, "value": <int> }` or `404 Not Found`.
|
|
* **`POST /api/v1/registers/<addr>?value=<number>`**
|
|
* **Description:** Sets the value of a specific Modbus holding register.
|
|
* **Response:** JSON object `{ "success": true, "address": <int>, "value": <int> }` or error status (`400`, `404`).
|
|
|
|
|
|
## Notes
|
|
|
|
* The REST API relies on the `ModbusManager` to interact with underlying components. Ensure `ModbusManager` is initialized correctly.
|
|
* The endpoints for writing individual coils/registers (`POST /coils/{addr}`, `POST /registers/{addr}`) are currently non-functional due to suspected routing issues in the web server library.
|
|
* Error handling is basic; more specific HTTP status codes could be implemented based on Modbus exception codes or internal errors. |