Merge pull request #71 from Gentleman1983/13-documentation-of-special…

…-fields-for-influxdb 13 documentation of special fields for influxdb
Gentleman1983 · Mar 10, 2024 · 5ba2fe7 · 5ba2fe7
2 parents d91a0c0 + b01d183
commit 5ba2fe7
Show file tree

Hide file tree

Showing 4 changed files with 83 additions and 61 deletions.
diff --git a/.github/workflows/pylint.yml b/.github/workflows/pylint.yml
@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.12"]
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ This document provides an overview to the changes on the different releases...
 * Publishing task to Dockerhub should publish [SBOM](https://www.cisa.gov/sbom), too ([#57](https://github.com/Gentleman1983/ginlong_solis_api_connector/issues/57))
 * Add Mend renovate bot to repository ([#56](https://github.com/Gentleman1983/ginlong_solis_api_connector/issues/56))
 * Fixed parsing issues regarding api update from March 4th, 2024. ([#68](https://github.com/Gentleman1983/ginlong_solis_api_connector/issues/68))
+* Pinned the data units regarding the dynamic units on Ginlong API. ([#13](https://github.com/Gentleman1983/ginlong_solis_api_connector/issues/13))
 
 ## 2.4.0
 * Added `CHANGELOG.md` document to have central document for changes. ([#38](https://github.com/Gentleman1983/ginlong_solis_api_connector/issues/38))

diff --git a/Mapping.md b/Mapping.md
@@ -1,37 +1,37 @@
 # Mapping internal data / REST endpoints
 This table helps to define which Solis REST API endpoints provide which information used for monitoring.
 
-| fieldKey                 | fieldType | REST endpoint  | API                          |
-|--------------------------|-----------|----------------|------------------------------|
-| AC_Current               | float     | inverterDetail | (iAc1+iAc2+iAc3)/3           |                         
-| AC_Frequency             | float     | inverterDetail | fac                          |
-| AC_Power                 | float     | inverterDetail | pac                          |
-| AC_Voltage               | float     | inverterDetail | (uAc1+uAc2+uAc3)/3           |                         
-| Annual_Energy_Used       | float     | inverterYear   | energy - gridSellEnergy      |                         
-| Annual_Generation        | float     | inverterYear   | energy                       |
-| Battery_Charge_Percent   | float     |                |                              |                         
-| Consumption_Energy       | float     | inverterDetail | homeLoadTotalEnergy          |                         
-| Consumption_Power        | float     | inverterDetail | familyLoadPower              |                         
-| DC_Current1              | float     | inverterDetail | iPv1                         |
-| DC_Current2              | float     | inverterDetail | iPv2                         |
-| DC_Current3              | float     | inverterDetail | iPv3                         |
-| DC_Current4              | float     | inverterDetail | iPv4                         |
-| DC_Power_PV1             | float     | inverterDetail | pow1                         |
-| DC_Power_PV2             | float     | inverterDetail | pow2                         |
-| DC_Power_PV3             | float     | inverterDetail | pow3                         |
-| DC_Power_PV4             | float     | inverterDetail | pow4                         |
-| DC_Voltage_PV1           | float     | inverterDetail | uPv1                         |
-| DC_Voltage_PV2           | float     | inverterDetail | uPv2                         |
-| DC_Voltage_PV3           | float     | inverterDetail | uPv3                         |
-| DC_Voltage_PV4           | float     | inverterDetail | uPv4                         |
-| Daily_Energy_Used        | float     | inverterDetail | eToday - gridSellTodayEnergy |                         
-| Daily_Generation         | float     | inverterDetail | eToday                       |
-| Generation_Last_Month    | float     | inverterMonth  | energy                       |                         
-| Inverter_Temperature     | float     | inverterDetail | inverterTemperature          |
-| Monthly_Energy_Used      | float     | inverterMonth  | energy - gridSellEnergy      |                         
-| Monthly_Generation       | float     | inverterDetail | eMonth                       |
-| Power_Grid_Total_Power   | float     | inverterDetail | pSum                         |                         
-| Total_Energy_Purchased   | float     | inverterDetail | gridPurchasedTotalEnergy     | 
-| Total_Generation         | float     | inverterDetail | eTotal                       |     
-| Total_On_grid_Generation | float     | inverterDetail | gridSellTotalEnergy          |      
-| updateDate               | integer   | inverterDetail | dataTimestamp                |            
+| fieldKey                 | fieldType | Unit | REST endpoint    | API                          |
+|--------------------------|-----------|------|------------------|------------------------------|
+| AC_Current               | float     | A    | inverterDetail   | (iAc1+iAc2+iAc3)/3           |                         
+| AC_Frequency             | float     | Hz   | inverterDetail   | fac                          |
+| AC_Power                 | float     | W    | inverterDetail   | pac                          |
+| AC_Voltage               | float     | V    | inverterDetail   | (uAc1+uAc2+uAc3)/3           |                         
+| Annual_Energy_Used       | float     | kWh  | inverterDetail   | eYear - gridSellYearEnergy   |                         
+| Annual_Generation        | float     | kWh  | inverterDetail   | eYear                        |
+| Battery_Charge_Percent   | float     |      |                  |                              |                         
+| Consumption_Energy       | float     | kWh  | inverterDetail   | homeLoadTotalEnergy          |                         
+| Consumption_Power        | float     | W    | inverterDetail   | familyLoadPower              |                         
+| DC_Current1              | float     | A    | inverterDetail   | iPv1                         |
+| DC_Current2              | float     | A    | inverterDetail   | iPv2                         |
+| DC_Current3              | float     | A    | inverterDetail   | iPv3                         |
+| DC_Current4              | float     | A    | inverterDetail   | iPv4                         |
+| DC_Power_PV1             | float     | W    | inverterDetail   | pow1                         |
+| DC_Power_PV2             | float     | W    | inverterDetail   | pow2                         |
+| DC_Power_PV3             | float     | W    | inverterDetail   | pow3                         |
+| DC_Power_PV4             | float     | W    | inverterDetail   | pow4                         |
+| DC_Voltage_PV1           | float     | V    | inverterDetail   | uPv1                         |
+| DC_Voltage_PV2           | float     | V    | inverterDetail   | uPv2                         |
+| DC_Voltage_PV3           | float     | V    | inverterDetail   | uPv3                         |
+| DC_Voltage_PV4           | float     | V    | inverterDetail   | uPv4                         |
+| Daily_Energy_Used        | float     | kWh  | inverterDetail   | eToday - gridSellTodayEnergy |                         
+| Daily_Generation         | float     | kWh  | inverterDetail   | eToday                       |
+| Generation_Last_Month    | float     | kWh  | inverterYear[-2] | energy                       |                         
+| Inverter_Temperature     | float     | °C   | inverterDetail   | inverterTemperature          |
+| Monthly_Energy_Used      | float     | kWh  | inverterDetail   | eMonth - gridSellMonthEnergy |                         
+| Monthly_Generation       | float     | kWh  | inverterDetail   | eMonth                       |
+| Power_Grid_Total_Power   | float     | W    | inverterDetail   | pSum                         |                         
+| Total_Energy_Purchased   | float     | kWh  | inverterDetail   | gridPurchasedTotalEnergy     | 
+| Total_Generation         | float     | kWh  | inverterDetail   | eTotal                       |     
+| Total_On_grid_Generation | float     | kWh  | inverterDetail   | gridSellTotalEnergy          |      
+| updateDate               | integer   |      | inverterDetail   | dataTimestamp                |            
diff --git a/ginlong_solis_api_connector.py b/ginlong_solis_api_connector.py
@@ -82,6 +82,27 @@ def prettify_json(input_json) -> str:
         """prettifies json for better output readability"""
         return json.dumps(json.loads(input_json), indent=2)
 
+    def calculate_unit_multiplicator(expected_unit, inverter_unit):
+        fb_inv=inverter_unit[1]
+        fb_exp=expected_unit[1]
+        multiplicator = calculate_factor(fb_inv) / calculate_factor(fb_exp)
+        return multiplicator
+
+    def calculate_factor(fb_factor):
+        if fb_factor == "k":
+            factor = 1000
+        elif fb_factor == "M":
+            factor = 1000000
+        elif fb_factor == "G":
+            factor = 1000000000
+        elif fb_factor == "T":
+            factor = 1000000000000
+        elif fb_factor == "m":
+            factor = 1/1000
+        else:
+            factor = 1
+        return factor
+
     # == post ====================================================================
     def execute_request(target_url, data, headers, retries) -> str:
         """execute request and handle errors"""
@@ -231,7 +252,7 @@ def get_ac_current(inverter_data):
         return get_average_value(inverter_data, 'iAc1', 'iAc2', 'iAc3')
 
     def get_average_value(inverter_data, field_phase_1, field_phase_2, field_phase_3):
-        if int(inverter_data['acOutputType']) == 0 or override_single_phase_inverter == 'true':  # pylint: disable=line-too-long
+        if int(inverter_data['acOutputType']) == 0 or override_single_phase_inverter == 'true':
             average_value = float(inverter_data[field_phase_1])
         else:
             average_value = float((inverter_data[field_phase_1] + inverter_data[field_phase_2] + inverter_data[field_phase_3]) / 3)  # pylint: disable=line-too-long
@@ -269,36 +290,36 @@ def write_to_influx_db(inverter_data, inverter_month, inverter_year, inverter_al
             dict_year = inverter_year
             dict_all = inverter_all  # pylint: disable=unused-variable
 
-            dict_fields = {'DC_Voltage_PV1': float(dict_detail['uPv1']),
-                           'DC_Voltage_PV2': float(dict_detail['uPv2']),
-                           'DC_Voltage_PV3': float(dict_detail['uPv3']),
-                           'DC_Voltage_PV4': float(dict_detail['uPv4']),
-                           'DC_Current1': float(dict_detail['iPv1']),
-                           'DC_Current2': float(dict_detail['iPv2']),
-                           'DC_Current3': float(dict_detail['iPv3']),
-                           'DC_Current4': float(dict_detail['iPv4']),
+            dict_fields = {'DC_Voltage_PV1': float(dict_detail['uPv1'] * calculate_unit_multiplicator("V",dict_detail['uPv1Str'])),  # pylint: disable=line-too-long
+                           'DC_Voltage_PV2': float(dict_detail['uPv2'] * calculate_unit_multiplicator("V",dict_detail['uPv2Str'])),  # pylint: disable=line-too-long  # pylint: disable=line-too-long
+                           'DC_Voltage_PV3': float(dict_detail['uPv3'] * calculate_unit_multiplicator("V",dict_detail['uPv3Str'])),  # pylint: disable=line-too-long
+                           'DC_Voltage_PV4': float(dict_detail['uPv4'] * calculate_unit_multiplicator("V",dict_detail['uPv4Str'])),  # pylint: disable=line-too-long
+                           'DC_Current1': float(dict_detail['iPv1'] * calculate_unit_multiplicator("A",dict_detail['iPv1Str'])),  # pylint: disable=line-too-long
+                           'DC_Current2': float(dict_detail['iPv2'] * calculate_unit_multiplicator("A",dict_detail['iPv2Str'])),  # pylint: disable=line-too-long
+                           'DC_Current3': float(dict_detail['iPv3'] * calculate_unit_multiplicator("A",dict_detail['iPv3Str'])),  # pylint: disable=line-too-long
+                           'DC_Current4': float(dict_detail['iPv4'] * calculate_unit_multiplicator("A",dict_detail['iPv4Str'])),  # pylint: disable=line-too-long
                            'AC_Voltage': get_ac_voltage(dict_detail),
                            'AC_Current': get_ac_current(dict_detail),
-                           'AC_Power': float(dict_detail['pac'] * 1000),
+                           'AC_Power': float(dict_detail['pac'] * calculate_unit_multiplicator("W",dict_detail['pacStr'])),  # pylint: disable=line-too-long
                            'AC_Frequency': float(dict_detail['fac']),
-                           'DC_Power_PV1': float(dict_detail['pow1']),
-                           'DC_Power_PV2': float(dict_detail['pow2']),
-                           'DC_Power_PV3': float(dict_detail['pow3']),
-                           'DC_Power_PV4': float(dict_detail['pow4']),
+                           'DC_Power_PV1': float(dict_detail['pow1'] * calculate_unit_multiplicator("W",dict_detail['pow1Str'])),  # pylint: disable=line-too-long
+                           'DC_Power_PV2': float(dict_detail['pow2'] * calculate_unit_multiplicator("W",dict_detail['pow2Str'])),  # pylint: disable=line-too-long
+                           'DC_Power_PV3': float(dict_detail['pow3'] * calculate_unit_multiplicator("W",dict_detail['pow3Str'])),  # pylint: disable=line-too-long
+                           'DC_Power_PV4': float(dict_detail['pow4'] * calculate_unit_multiplicator("W",dict_detail['pow4Str'])),  # pylint: disable=line-too-long
                            'Inverter_Temperature': float(dict_detail['inverterTemperature']),
-                           'Daily_Generation': float(dict_detail['eToday']),
-                           'Monthly_Generation': float(dict_detail['eMonth']),
-                           'Annual_Generation': float(dict_detail['eYear']),
-                           'Total_Generation': float(dict_detail['eTotal'] * 1000),
+                           'Daily_Generation': float(dict_detail['eToday'] * calculate_unit_multiplicator("kWh",dict_detail['eTodayStr'])),  # pylint: disable=line-too-long
+                           'Monthly_Generation': float(dict_detail['eMonth'] * calculate_unit_multiplicator("kWh",dict_detail['eMonthStr'])),  # pylint: disable=line-too-long
+                           'Annual_Generation': float(dict_detail['eYear'] * calculate_unit_multiplicator("kWh",dict_detail['eYearStr'])),  # pylint: disable=line-too-long
+                           'Total_Generation': float(dict_detail['eTotal'] * calculate_unit_multiplicator("kWh",dict_detail['eTotalStr'])),  # pylint: disable=line-too-long
                            'Generation_Last_Month': get_last_month_generation(dict_year),
-                           'Power_Grid_Total_Power': float(dict_detail['psum'] * 1000),
-                           'Total_On_grid_Generation': float(dict_detail['gridSellTotalEnergy'] * 1000),  # pylint: disable=line-too-long
-                           'Total_Energy_Purchased': float(dict_detail['gridPurchasedTotalEnergy'] * 1000),  # pylint: disable=line-too-long
-                           'Consumption_Power': float(dict_detail['familyLoadPower'] * 1000),
-                           'Consumption_Energy': float(dict_detail['homeLoadTotalEnergy'] * 1000),
-                           'Daily_Energy_Used': float(dict_detail['eToday'] - dict_detail['gridSellTodayEnergy']),  # pylint: disable=line-too-long
-                           'Monthly_Energy_Used': float(dict_detail['eMonth'] - dict_detail['gridSellMonthEnergy']),  # pylint: disable=line-too-long
-                           'Annual_Energy_Used': float(dict_detail['eYear'] - dict_detail['gridSellYearEnergy']),  # pylint: disable=line-too-long
+                           'Power_Grid_Total_Power': float(dict_detail['psum'] * calculate_unit_multiplicator("W",dict_detail['psumStr'])),  # pylint: disable=line-too-long
+                           'Total_On_grid_Generation': float(dict_detail['gridSellTotalEnergy'] * calculate_unit_multiplicator("kWh",dict_detail['gridSellTotalEnergyStr'])),  # pylint: disable=line-too-long
+                           'Total_Energy_Purchased': float(dict_detail['gridPurchasedTotalEnergy'] * calculate_unit_multiplicator("kWh",dict_detail['gridPurchasedTotalEnergyStr'])),  # pylint: disable=line-too-long
+                           'Consumption_Power': float(dict_detail['familyLoadPower'] * calculate_unit_multiplicator("W",dict_detail['familyLoadPowerStr'])),  # pylint: disable=line-too-long
+                           'Consumption_Energy': float(dict_detail['homeLoadTotalEnergy'] * calculate_unit_multiplicator("kWh",dict_detail['homeLoadTotalEnergyStr'])),  # pylint: disable=line-too-long
+                           'Daily_Energy_Used': float(dict_detail['eToday'] * calculate_unit_multiplicator("kWh",dict_detail['eTodayStr']) - (dict_detail['gridSellTodayEnergy'] * calculate_unit_multiplicator("kWh",dict_detail['gridSellTodayEnergyStr']))),  # pylint: disable=line-too-long
+                           'Monthly_Energy_Used': float(dict_detail['eMonth'] * calculate_unit_multiplicator("kWh",dict_detail['eMonthStr']) - dict_detail['gridSellMonthEnergy'] * calculate_unit_multiplicator("kWh",dict_detail['gridSellMonthEnergyStr'])),  # pylint: disable=line-too-long
+                           'Annual_Energy_Used': float(dict_detail['eYear'] * calculate_unit_multiplicator("kWh",dict_detail['eYearStr']) - dict_detail['gridSellYearEnergy'] * calculate_unit_multiplicator("kWh",dict_detail['gridSellYearEnergyStr'])),  # pylint: disable=line-too-long
                            'updateDate': int(dict_detail['dataTimestamp'])
                            }