Readme updated

This commit is contained in:
Kai Lauterbach 2024-02-08 16:07:25 +01:00
parent 571a268436
commit 880f41e049

251
README.md
View file

@ -1,99 +1,184 @@
## Webserver API
# Webserver und URLs
The web server is implemented on the ESP32 and provides various endpoints for operation and display of information. Here are the defined URLs and their functions:
Der Webserver ist auf dem ESP32 implementiert und bietet verschiedene Endpunkte für die Bedienung und Anzeige von Informationen. Hier sind die definierten URLs und ihre Funktionen:
### URL Paths:
- **Root Path ("/")**
- HTTP-Methode: GET
- Zeigt die Hauptseite mit allgemeinen Informationen an, einschließlich Links zu anderen Endpunkten.
1. **`/` (Root)**
- **Output:** HTML page with dynamic content.
- **Return:** Webpage with various data and options.
- **Format:** HTML.
- **Purpose:** Displays real-time data and provides options for configuration and control.
- **JSON Path ("/json")**
- HTTP-Methode: GET
- Liefert JSON-formatierte Daten mit Informationen über Busspannung, Strom, Leistung, Energie, Temperatur, Luftfeuchtigkeit und Fehlercode.
2. **`/json`**
- **Output:** JSON data.
- **Return:** JSON object with sensor values and configuration parameters.
- **Format:** JSON.
- **Purpose:** Provides sensor values and configuration settings in a machine-readable format.
Beispiel:
```
This is an example of a JSON object containing various measurement values and configuration parameters. Here is an explanation of the fields included:
```json
{
"busVoltage": 25.6,
"shuntVoltage": 0.0,
"current": 10.5,
"power": 268.8,
"energy": 134.4,
"temp": 28.5,
"humidity": 45.8,
"errorCode
"busVoltage": 12.35,
"shuntVoltage": 0.015,
"current": 0.5,
"power": 6.175,
"energy": 100.25,
"temperature": 25.5,
"humidity": 45,
"errorCode": 0,
"shuntValue": 0.0001,
"ina226Status": 3,
"ina226ShuntValue": 0.0002,
"ina226AlertFlag": 0,
"ina226AlertLimit": 0.1,
"ina226CurrentLSB": 0.0005
}
```
- **Config Path ("/config")**
- HTTP-Methode: GET
- Zeigt eine Konfigurationsseite an, auf der Benutzer Einstellungen für Temperatur, Luftfeuchtigkeit und Strombereiche ändern können.
- `busVoltage`: The voltage at the bus in volts.
- `shuntVoltage`: The voltage across the shunt resistor in volts.
- `current`: The current consumption in amperes.
- `power`: The power in watts.
- `energy`: The energy in watt-hours.
- `temperature`: The temperature in degrees Celsius.
- `humidity`: The humidity in percentage.
- `errorCode`: An error code indicating possible error conditions.
- `shuntValue`: The value of the shunt resistor in ohms.
- `ina226Status`: The status of the INA226 chip.
- `ina226ShuntValue`: The value of the shunt resistor according to the INA226 chip in ohms.
- `ina226AlertFlag`: A flag indicating whether a warning has been triggered by the INA226 chip.
- `ina226AlertLimit`: The limit value for alerts from the INA226 chip.
- `ina226CurrentLSB`: The value of the least significant bit (LSB) for the current according to the INA226 chip in amperes.
- **Save Config Path ("/saveConfig")**
- HTTP-Methode: PUT
- Behandelt die Anforderung zum Speichern der neuen Konfigurationsdaten, die durch die Konfigurationsseite festgelegt wurden.
3. **`/config`**
- **Output:** HTML page for configuration.
- **Return:** Webpage with form fields for configuring parameters.
- **Format:** HTML.
- **Purpose:** Allows users to customize device settings through a web interface.
Beispiel:
```
{
"temp_min": 20.0,
"temp_max": 30.0,
"humi_min": 40.0,
"humi_max": 60.0,
"current_min": -5.0,
"current_max": 5.0
}
4. **`/saveConfig`**
- **Output:** JSON response.
- **Return:** Confirmation message.
- **Format:** JSON.
- **Purpose:** Saves configuration changes submitted via the configuration form.
5. **`/demoMode1`**
- **Output:** Redirect to root.
- **Return:** Redirect to root after activating Demo Mode 1.
- **Format:** HTML.
- **Purpose:** Initiates Demo Mode 1, simulating a specific charging scenario.
6. **`/demoMode2`**
- **Output:** Redirect to root.
- **Return:** Redirect to root after activating Demo Mode 2.
- **Format:** HTML.
- **Purpose:** Initiates Demo Mode 2, simulating a specific charging scenario.
7. **`/demoMode3`**
- **Output:** Redirect to root.
- **Return:** Redirect to root after activating Demo Mode 3.
- **Format:** HTML.
- **Purpose:** Initiates Demo Mode 3, simulating a specific discharging scenario.
8. **`/resetESP`**
- **Output:** HTML page with restart message.
- **Return:** HTML page displaying the restart process.
- **Format:** HTML.
- **Purpose:** Initiates a restart of the ESP32 device.
9. **`/resetWifi`**
- **Output:** HTML page with reset message.
- **Return:** HTML page displaying the process to reset the Wi-Fi configuration.
- **Format:** HTML.
- **Purpose:** Resets the Wi-Fi configuration and restarts the device.
10. **`/updateFirmware`**
- **Output:** HTML page with firmware update options.
- **Return:** HTML page displaying firmware update options.
- **Format:** HTML.
- **Purpose:** Provides options for updating the device firmware.
11. **`/updateFirmwareAction`**
- **Output:** HTML page with update status.
- **Return:** HTML page displaying the firmware update process.
- **Format:** HTML.
- **Purpose:** Initiates the firmware update process and displays the current update status in real-time.
12. **`/readUpdateFirmwareStatus`**
- **Output:** HTML page with update status.
- **Return:** HTML page displaying the current firmware update status.
- **Format:** HTML.
- **Purpose:** Provides the current update status during the firmware update process in real-time.
13. **`/css`**
- **Output:** Custom CSS styles.
- **Return:** CSS styles for the HTML pages.
- **Format:** CSS.
- **Purpose:** Provides style templates for the HTML pages.
These URL paths form a basic API for interacting with the ESP32 device, allowing users to display real-time data, configure settings, initiate demo modes, and update the firmware.
### Error codes in `errorCode`
The variable `globalError` is used as a bitmask, where each bit represents a specific error condition. Here are the possible error codes and their meanings:
#### `ERROR_NONE` (0b0000000000000000)
No error. The device is functioning properly, there are no errors present.
#### `ERROR_MAX_CURRENT_EXCEEDED` (0b0000000000000001)
The maximum current consumption has been exceeded. There might be an overload condition on the device.
#### `ERROR_CURRENT_BELOW_MIN` (0b0000000000000010)
The current consumption is below the permissible minimum. There may be an issue with the power supply.
#### `ERROR_MAX_TEMP_EXCEEDED` (0b0000000000000100)
The maximum temperature has been exceeded. The device could overheat.
#### `ERROR_TEMP_BELOW_MIN` (0b0000000000001000)
The temperature is below the permissible minimum. There is a risk of hypothermia or other temperature-related issues.
#### `ERROR_MAX_HUMI_EXCEEDED` (0b0000000000010000)
The maximum humidity has been exceeded. This could lead to moisture-related problems.
#### `ERROR_HUMI_BELOW_MIN` (0b0000000000100000)
The humidity is below the permissible minimum. There is a risk of low humidity.
Please note that multiple errors can occur simultaneously as the bitmasks can be combined. For example, `ERROR_MAX_TEMP_EXCEEDED | ERROR_MAX_HUMI_EXCEEDED` could indicate that both the maximum temperature and humidity have been exceeded.
## Functions
### configureIna226()
The `configureIna226()` function configures the INA226 sensor with specific settings.
#### Steps:
1. **Set Minimal Shunt:**
- Description: Overwrites the INA226_ERR_SHUNT_LOW parameter with a minimal shunt value.
The ina226 library default values is 0.001.
- Code: `ina226.setMinimalShunt(0.0001);`
2. **Set Maximum Current Shunt:**
- Description: Sets the maximum current shunt value with normalization (3rd parameter set to true) to 3 floating-point accuracy.
- Code:
```cpp
ina226Status = ina226.setMaxCurrentShunt(current ampere,
shunt ohm, true);
```
- **Demo Mode 1 Path ("/demo1")**
- HTTP-Methode: GET
- Startet den Demo-Modus 1: Demonstriert einen lade-/entladezyklus ab der Hälfte der maximalen Kapazität mit variablem Strom bei 25,6A.
3. **Set Averaging:**
- Description: Sets the averaging mode to use 16 samples for building an average value.
- Code: `ina226.setAverage(2);`
- **Demo Mode 2 Path ("/demo2")**
- HTTP-Methode: GET
- Startet den Demo-Modus 2: Demonstriert einen ladezyklus ab 97% der maximalen Kapazität auf 100% mit 200A bei 25.6V.
- **Demo Mode 3 Path ("/demo3")**
- HTTP-Methode: GET
- Startet den Demo-Modus 3: Demonstriert einen entladezyklus ab 3% der maximalen Kapazität auf 0% mit -200A bei 25.6V.
Die HTML-Seiten werden dynamisch generiert und enthalten JavaScript für die Aktualisierung von Daten über AJAX-Anfragen. Die Konfigurationsseite ermöglicht es Benutzern, bestimmte Parameter über Schieberegler einzustellen und Änderungen zu speichern.
# Fehlermeldungen für den wert `errorCode`
Die Variable `globalError` wird als Bitmask verwendet, wobei jedes Bit eine bestimmte Fehlerbedingung repräsentiert. Hier sind die möglichen Fehlermeldungen und ihre Bedeutungen:
## `ERROR_NONE` (0b0000000000000000)
Kein Fehler. Das Gerät funktioniert ordnungsgemäß, es liegen keine Fehler vor.
## `ERROR_MAX_CURRENT_EXCEEDED` (0b0000000000000001)
Der maximale Stromverbrauch wurde überschritten. Möglicherweise liegt eine Überlastung des Geräts vor.
## `ERROR_CURRENT_BELOW_MIN` (0b0000000000000010)
Der aktuelle Stromverbrauch liegt unter dem zulässigen Minimum. Möglicherweise gibt es ein Problem mit der Stromzufuhr.
## `ERROR_MAX_TEMP_EXCEEDED` (0b0000000000000100)
Die maximale Temperatur wurde überschritten. Das Gerät könnte überhitzen.
## `ERROR_TEMP_BELOW_MIN` (0b0000000000001000)
Die Temperatur liegt unterhalb des zulässigen Minimums. Es besteht die Gefahr von Unterkühlung oder anderen temperaturbedingten Problemen.
## `ERROR_MAX_HUMI_EXCEEDED` (0b0000000000010000)
Die maximale Luftfeuchtigkeit wurde überschritten. Dies könnte zu feuchtigkeitsbedingten Problemen führen.
## `ERROR_HUMI_BELOW_MIN` (0b0000000000100000)
Die Luftfeuchtigkeit liegt unter dem zulässigen Minimum. Es besteht die Gefahr von zu geringer Luftfeuchtigkeit.
Bitte beachten Sie, dass mehrere Fehler gleichzeitig auftreten können, da die Bitmasken kombiniert werden können. Zum Beispiel könnte `ERROR_MAX_TEMP_EXCEEDED | ERROR_MAX_HUMI_EXCEEDED` darauf hinweisen, dass sowohl die maximale Temperatur als auch die maximale Luftfeuchtigkeit überschritten wurden.
# Used libraries (Arduino)
## Used libraries (Arduino)
WiFi at version 2.0.0
ESP32httpUpdate at version 2.1.145
@ -115,3 +200,5 @@ SPI at version 2.0.0
Adafruit SSD1306 at version 2.5.9
Adafruit Unified Sensor at version 1.1.14
Adafruit BME280 Library at version 2.2.4
Use the modified INA226 zip file from the repository to support shunt resistors down to 0.0001 Ohm.