ESP32_powerMC/README.md

# powerMC - Energy and Current Measurement System

An ESP32 based energy and current measurement system.

Most of the code is generated by ChatGPT.

## Webserver

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:

### URL Paths:

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.

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.

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": 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,
  "ina226CurrentLSB": 0.0005
}
```

- `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 of the attached battery.
- `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 which is used for configuration.
- `ina226Status`: The status of the INA226 initialization (setMaxCurrentShunt function call).
- `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 represents the smallest measurable current level that the INA226 chip can detect.

#### 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:

| Descriptive Name            | Value    | Meaning                                                  |
|:----------------------------|---------:|:---------------------------------------------------------|
| `ERROR_NONE`                | 0b00000000 | No error. The device is functioning properly, there are no errors present. |
| `ERROR_MAX_CURRENT_EXCEEDED`| 0b00000001 | The maximum current consumption has been exceeded. There might be an overload condition on the device. |
| `ERROR_CURRENT_BELOW_MIN`   | 0b00000010 | The current consumption is below the permissible minimum. There may be an issue with the power supply. |
| `ERROR_MAX_TEMP_EXCEEDED`   | 0b00000100 | The maximum temperature has been exceeded. The device could overheat. |
| `ERROR_TEMP_BELOW_MIN`      | 0b00001000 | The temperature is below the permissible minimum. There is a risk of hypothermia or other temperature-related issues. |
| `ERROR_MAX_HUMI_EXCEEDED`   | 0b00010000 | The maximum humidity has been exceeded. This could lead to moisture-related problems. |
| `ERROR_HUMI_BELOW_MIN`      | 0b00100000 | The humidity is below the permissible minimum. There is a risk of low humidity. |
|`ERROR_INA226_UNCONFIGURED`  | 0b10000000 | The configuration settings for the shunt voltage and maximum current exceed the limits of the INA226 library. |

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.

#### Error codes ina226Status

| descriptive name error        |  value   |  meaning  |
|:------------------------------|---------:|:----------|
| INA226_ERR_NONE               |  0x0000  | OK
| INA226_ERR_SHUNTVOLTAGE_HIGH  |  0x8000  | maxCurrent \* shunt > 80 mV 
| INA226_ERR_MAXCURRENT_LOW     |  0x8001  | maxCurrent < 0.001
| INA226_ERR_SHUNT_LOW          |  0x8002  | shunt      < 0.001
| INA226_ERR_NORMALIZE_FAILED   |  0x8003  | not possible to normalize.

#### Error codes ina226AlertLimit

| description alert register | value  | a.k.a.  |
|:---------------------------|-------:| -------:|
| INA226_SHUNT_OVER_VOLTAGE  | 0x8000 |  SOL    |
| INA226_SHUNT_UNDER_VOLTAGE | 0x4000 |  SUL    |
| INA226_BUS_OVER_VOLTAGE    | 0x2000 |  BOL    |
| INA226_BUS_UNDER_VOLTAGE   | 0x1000 |  BUL    |
| INA226_POWER_OVER_LIMIT    | 0x0800 |  POL    |
| INA226_CONVERSION_READY    | 0x0400 |         |

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.

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.

## 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
   - HTTPClient at version 2.0.0
   - WiFiClientSecure at version 2.0.0
   - Update at version 2.0.0
   - FS at version 2.0.0
   - SPIFFS at version 2.0.0
   - WebServer at version 2.0.0
   - ArduinoJson at version 7.0.2
   - WiFiManager at version 2.0.16-rc.2
   - DNSServer at version 2.0.0
   - EEPROM at version 2.0.0
   - Wire at version 2.0.0
   - INA226 at version 0.5.2 (zip file in repository modified by me)
   - Adafruit GFX Library at version 1.11.9
   - Adafruit BusIO at version 1.15.0
   - 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.