diff --git a/README.md b/README.md index 712d9da..5e47d1c 100644 --- a/README.md +++ b/README.md @@ -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. -- **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. +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. -- **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. +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. -- **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. +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. -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. +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. -# Fehlermeldungen für den wert `errorCode` +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. -Die Variable `globalError` wird als Bitmask verwendet, wobei jedes Bit eine bestimmte Fehlerbedingung repräsentiert. Hier sind die möglichen Fehlermeldungen und ihre Bedeutungen: +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. -## `ERROR_NONE` (0b0000000000000000) +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. -Kein Fehler. Das Gerät funktioniert ordnungsgemäß, es liegen keine Fehler vor. +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. -## `ERROR_MAX_CURRENT_EXCEEDED` (0b0000000000000001) +13. **`/css`** + - **Output:** Custom CSS styles. + - **Return:** CSS styles for the HTML pages. + - **Format:** CSS. + - **Purpose:** Provides style templates for the HTML pages. -Der maximale Stromverbrauch wurde überschritten. Möglicherweise liegt eine Überlastung des Geräts vor. +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_CURRENT_BELOW_MIN` (0b0000000000000010) +### Error codes in `errorCode` -Der aktuelle Stromverbrauch liegt unter dem zulässigen Minimum. Möglicherweise gibt es ein Problem mit der Stromzufuhr. +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_MAX_TEMP_EXCEEDED` (0b0000000000000100) +#### `ERROR_NONE` (0b0000000000000000) -Die maximale Temperatur wurde überschritten. Das Gerät könnte überhitzen. +No error. The device is functioning properly, there are no errors present. -## `ERROR_TEMP_BELOW_MIN` (0b0000000000001000) +#### `ERROR_MAX_CURRENT_EXCEEDED` (0b0000000000000001) -Die Temperatur liegt unterhalb des zulässigen Minimums. Es besteht die Gefahr von Unterkühlung oder anderen temperaturbedingten Problemen. +The maximum current consumption has been exceeded. There might be an overload condition on the device. -## `ERROR_MAX_HUMI_EXCEEDED` (0b0000000000010000) +#### `ERROR_CURRENT_BELOW_MIN` (0b0000000000000010) -Die maximale Luftfeuchtigkeit wurde überschritten. Dies könnte zu feuchtigkeitsbedingten Problemen führen. +The current consumption is below the permissible minimum. There may be an issue with the power supply. -## `ERROR_HUMI_BELOW_MIN` (0b0000000000100000) +#### `ERROR_MAX_TEMP_EXCEEDED` (0b0000000000000100) -Die Luftfeuchtigkeit liegt unter dem zulässigen Minimum. Es besteht die Gefahr von zu geringer Luftfeuchtigkeit. +The maximum temperature has been exceeded. The device could overheat. -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. +#### `ERROR_TEMP_BELOW_MIN` (0b0000000000001000) -# Used libraries (Arduino) +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); + ``` + +3. **Set Averaging:** + - Description: Sets the averaging mode to use 16 samples for building an average value. + - Code: `ina226.setAverage(2);` + +## 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.