Readme updated
This commit is contained in:
Kai Lauterbach
parent
571a268436
commit
880f41e049
1 changed files with 150 additions and 63 deletions
251
README.md
251
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 ("/")**
|
1. **`/` (Root)**
|
||||||
- HTTP-Methode: GET
|
- **Output:** HTML page with dynamic content.
|
||||||
- Zeigt die Hauptseite mit allgemeinen Informationen an, einschließlich Links zu anderen Endpunkten.
|
- **Return:** Webpage with various data and options.
|
||||||
|
- **Format:** HTML.
|
||||||
|
- **Purpose:** Displays real-time data and provides options for configuration and control.
|
||||||
|
|
||||||
- **JSON Path ("/json")**
|
2. **`/json`**
|
||||||
- HTTP-Methode: GET
|
- **Output:** JSON data.
|
||||||
- Liefert JSON-formatierte Daten mit Informationen über Busspannung, Strom, Leistung, Energie, Temperatur, Luftfeuchtigkeit und Fehlercode.
|
- **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,
|
"busVoltage": 12.35,
|
||||||
"shuntVoltage": 0.0,
|
"shuntVoltage": 0.015,
|
||||||
"current": 10.5,
|
"current": 0.5,
|
||||||
"power": 268.8,
|
"power": 6.175,
|
||||||
"energy": 134.4,
|
"energy": 100.25,
|
||||||
"temp": 28.5,
|
"temperature": 25.5,
|
||||||
"humidity": 45.8,
|
"humidity": 45,
|
||||||
"errorCode
|
"errorCode": 0,
|
||||||
|
"shuntValue": 0.0001,
|
||||||
|
"ina226Status": 3,
|
||||||
|
"ina226ShuntValue": 0.0002,
|
||||||
|
"ina226AlertFlag": 0,
|
||||||
|
"ina226AlertLimit": 0.1,
|
||||||
|
"ina226CurrentLSB": 0.0005
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- **Config Path ("/config")**
|
- `busVoltage`: The voltage at the bus in volts.
|
||||||
- HTTP-Methode: GET
|
- `shuntVoltage`: The voltage across the shunt resistor in volts.
|
||||||
- Zeigt eine Konfigurationsseite an, auf der Benutzer Einstellungen für Temperatur, Luftfeuchtigkeit und Strombereiche ändern können.
|
- `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")**
|
3. **`/config`**
|
||||||
- HTTP-Methode: PUT
|
- **Output:** HTML page for configuration.
|
||||||
- Behandelt die Anforderung zum Speichern der neuen Konfigurationsdaten, die durch die Konfigurationsseite festgelegt wurden.
|
- **Return:** Webpage with form fields for configuring parameters.
|
||||||
|
- **Format:** HTML.
|
||||||
|
- **Purpose:** Allows users to customize device settings through a web interface.
|
||||||
|
|
||||||
Beispiel:
|
4. **`/saveConfig`**
|
||||||
```
|
- **Output:** JSON response.
|
||||||
{
|
- **Return:** Confirmation message.
|
||||||
"temp_min": 20.0,
|
- **Format:** JSON.
|
||||||
"temp_max": 30.0,
|
- **Purpose:** Saves configuration changes submitted via the configuration form.
|
||||||
"humi_min": 40.0,
|
|
||||||
"humi_max": 60.0,
|
5. **`/demoMode1`**
|
||||||
"current_min": -5.0,
|
- **Output:** Redirect to root.
|
||||||
"current_max": 5.0
|
- **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")**
|
3. **Set Averaging:**
|
||||||
- HTTP-Methode: GET
|
- Description: Sets the averaging mode to use 16 samples for building an average value.
|
||||||
- Startet den Demo-Modus 1: Demonstriert einen lade-/entladezyklus ab der Hälfte der maximalen Kapazität mit variablem Strom bei 25,6A.
|
- Code: `ina226.setAverage(2);`
|
||||||
|
|
||||||
- **Demo Mode 2 Path ("/demo2")**
|
## Used libraries (Arduino)
|
||||||
- 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)
|
|
||||||
|
|
||||||
WiFi at version 2.0.0
|
WiFi at version 2.0.0
|
||||||
ESP32httpUpdate at version 2.1.145
|
ESP32httpUpdate at version 2.1.145
|
||||||
|
|
@ -115,3 +200,5 @@ SPI at version 2.0.0
|
||||||
Adafruit SSD1306 at version 2.5.9
|
Adafruit SSD1306 at version 2.5.9
|
||||||
Adafruit Unified Sensor at version 1.1.14
|
Adafruit Unified Sensor at version 1.1.14
|
||||||
Adafruit BME280 Library at version 2.2.4
|
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.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue