Merge pull request #754 from cschlipf/passive-mode-timeout

Added support for Passive Mode Timeout

Author: wills106

custom_components/solax_modbus/plugin_sofar.py

@@ -105,10 +105,15 @@ class SofarModbusSensorEntityDescription(BaseModbusSensorEntityDescription):
 
 def value_function_passivemode(initval, descr, datadict):
     return [ (REGISTER_S32, datadict.get('passive_mode_grid_power', 0)),
-            (REGISTER_S32, datadict.get('passive_mode_battery_power_min', 0)), 
-            (REGISTER_S32, datadict.get('passive_mode_battery_power_max', 0)),
+             (REGISTER_S32, datadict.get('passive_mode_battery_power_min', 0)), 
+             (REGISTER_S32, datadict.get('passive_mode_battery_power_max', 0)),
            ]
 
+def value_function_passive_timeout(initval, descr, datadict):
+    return  [ ('passive_mode_timeout', datadict.get('passive_mode_timeout', datadict.get('passive_mode_timeout')), ),
+              ('passive_mode_timeout_action', datadict.get('passive_mode_timeout_action', datadict.get('passive_mode_timeout_action')), ), 
+            ]
+
 def value_function_refluxcontrol(initval, descr, datadict):
     return  [ ('reflux_control', datadict.get('reflux_control', datadict.get('ro_reflux_control')), ),
               ('reflux_power', datadict.get('reflux_power', 0), ), 
@@ -145,6 +150,14 @@ def value_function_toumode(initval, descr, datadict):
         write_method = WRITE_MULTI_MODBUS,
         value_function = value_function_passivemode,
     ),
+    SofarModbusButtonEntityDescription(
+        name = "Passive: Update Timeout",
+        key = "passive_mode_update_timeout",
+        register = 0x1184,
+        allowedtypes = HYBRID,
+        write_method = WRITE_MULTI_MODBUS,
+        value_function = value_function_passive_timeout,
+    ),
     SofarModbusButtonEntityDescription(
         name = "Sync RTC",
         key = "sync_rtc",
@@ -206,13 +219,14 @@ def value_function_toumode(initval, descr, datadict):
         device_class = NumberDeviceClass.POWER,
         unit = REGISTER_S32,
         fmt = "i",
-        native_max_value = 15000,
-        native_min_value = -15000,
+        native_max_value = 20000,
+        native_min_value = -20000,
         native_step = 100,
         initvalue = 0,
         allowedtypes = HYBRID,
         prevent_update = True,
         write_method = WRITE_DATA_LOCAL,
+        icon = "mdi:transmission-tower",
     ),
     SofarModbusNumberEntityDescription(
         name = "Passive: Minimum Batter Power",
@@ -221,13 +235,14 @@ def value_function_toumode(initval, descr, datadict):
         device_class = NumberDeviceClass.POWER,
         unit = REGISTER_S32,
         fmt = "i",
-        native_max_value = 15000,
-        native_min_value = -15000,
+        native_max_value = 20000,
+        native_min_value = -20000,
         native_step = 100,
         initvalue = 0,
         allowedtypes = HYBRID,
         prevent_update = True,
         write_method = WRITE_DATA_LOCAL,
+        icon = "mdi:battery-arrow-down",
     ),
     SofarModbusNumberEntityDescription(
         name = "Passive: Maximum Battery Power",
@@ -236,13 +251,14 @@ def value_function_toumode(initval, descr, datadict):
         device_class = NumberDeviceClass.POWER,
         unit = REGISTER_S32,
         fmt = "i",
-        native_max_value = 15000,
-        native_min_value = -15000,
+        native_max_value = 20000,
+        native_min_value = -20000,
         native_step = 100,
         initvalue = 0,
         allowedtypes = HYBRID,
         prevent_update = True,
         write_method = WRITE_DATA_LOCAL,
+        icon = "mdi:battery-arrow-up",
     ),
     SofarModbusNumberEntityDescription(
         name = "Reflux Power",
@@ -483,6 +499,36 @@ def value_function_toumode(initval, descr, datadict):
         entity_category = EntityCategory.CONFIG,
         icon = "mdi:battery-clock",
     ),
+    SofarModbusSelectEntityDescription(
+        name = "Passive: Timeout",
+        key = "passive_mode_timeout",
+        unit = REGISTER_U16,
+        write_method = WRITE_DATA_LOCAL,
+        option_dict =  {
+                0: "Disabled",
+                300: "5 Minutes",
+                600: "10 Minutes",
+                900: "15 Minutes",
+                1800: "30 Minutes",
+                3600: "60 Minutes",
+                5400: "90 Minutes",
+                7200: "120 Minutes",
+            },
+        allowedtypes = HYBRID,
+        icon = "mdi:timer",
+    ),
+    SofarModbusSelectEntityDescription(
+        name = "Passive: Timeout Action",
+        key = "passive_mode_timeout_action",
+        unit = REGISTER_U16,
+        write_method = WRITE_DATA_LOCAL,
+        option_dict =  {
+                0: "Force Standby",
+                1: "Return to Previous Mode",
+            },
+        allowedtypes = HYBRID,
+        icon = "mdi:timer-cog",
+    ),
     ###
     #
     #  Normal select types
@@ -558,6 +604,7 @@ def value_function_toumode(initval, descr, datadict):
             },
         allowedtypes = HYBRID,
         write_method = WRITE_MULTISINGLE_MODBUS,
+        icon = "mdi:battery-charging-60",
     ),
     # Timing Charge Start
     # Timing Charge End
@@ -569,7 +616,7 @@ def value_function_toumode(initval, descr, datadict):
 
 
 
-# ================================= Sennsor Declarations ============================================================
+# ================================= Sensor Declarations ============================================================
 
 SENSOR_TYPES: list[SofarModbusSensorEntityDescription] = [ 
 
@@ -936,6 +983,7 @@ def value_function_toumode(initval, descr, datadict):
         newblock = True,
         unit = REGISTER_STR,
         wordcount=7,
+        entity_category = EntityCategory.DIAGNOSTIC,
         allowedtypes = HYBRID | PV,
     ),
     SofarModbusSensorEntityDescription(
@@ -944,6 +992,7 @@ def value_function_toumode(initval, descr, datadict):
         register = 0x44D,
         unit = REGISTER_STR,
         wordcount=2,
+        entity_category = EntityCategory.DIAGNOSTIC,
         allowedtypes = HYBRID | PV,
     ),
     SofarModbusSensorEntityDescription(
@@ -952,6 +1001,7 @@ def value_function_toumode(initval, descr, datadict):
         register = 0x44F,
         unit = REGISTER_STR,
         wordcount=12,
+        entity_category = EntityCategory.DIAGNOSTIC,
         allowedtypes = HYBRID | PV,
     ),
 ###
@@ -2889,36 +2939,47 @@ def value_function_toumode(initval, descr, datadict):
         allowedtypes = HYBRID,
     ),
     SofarModbusSensorEntityDescription(
-        name = "Passive Mode Timeout",
-        key = "passive_mode_timeout",
+        name = "RO: Passive: Timeout",
+        key = "ro_passive_mode_timeout",
         register = 0x1184,
-        entity_registry_enabled_default =  False,
+        allowedtypes = HYBRID,
+        entity_category = EntityCategory.DIAGNOSTIC,
+    ),
+    SofarModbusSensorEntityDescription(
+        name = "Passive: Timeout Action",
+        key = "ro_passive_mode_timeout_action",
+        register = 0x1185,
+        scale = { 0: "Force Standby",
+                  1: "Return to Previous Mode", },
         allowedtypes = HYBRID,
         entity_category = EntityCategory.DIAGNOSTIC,
     ),
     SofarModbusSensorEntityDescription(
         name = "Passive: Desired Grid Power",
-        key = "ro_passive_mode_gdes",
+        key = "passive_mode_grid_power",
         unit = REGISTER_S32,
+        entity_registry_enabled_default =  False,
         register = 0x1187,
-        #entity_registry_enabled_default =  False,
         allowedtypes = HYBRID,
+        entity_category = EntityCategory.DIAGNOSTIC,
     ),
     SofarModbusSensorEntityDescription(
         name = "Passive: Minimum Battery Power",
-        key = "ro_passive_mode_lower",
+        key = "passive_mode_battery_power_min",
         unit = REGISTER_S32,
         register = 0x1189,
-        #entity_registry_enabled_default =  False,
+        entity_registry_enabled_default =  False,
         allowedtypes = HYBRID,
+        entity_category = EntityCategory.DIAGNOSTIC,
     ),
     SofarModbusSensorEntityDescription(
         name = "Passive: Maximum Battery Power",
-        key = "ro_passive_mode_upper",
+        key = "passive_mode_battery_power_max",
         unit = REGISTER_S32,
         register = 0x118B,
-        #entity_registry_enabled_default =  False,
+        entity_registry_enabled_default =  False,
         allowedtypes = HYBRID,
+        entity_category = EntityCategory.DIAGNOSTIC,
     ),
 ]
 

docs/sofar-operation-modes.md

@@ -1,7 +1,5 @@
 # Sofar Modes of Operation
 
-WARNING: Work in progress, some of this information may be inaccurate. Use at your own risk
-
 WARNING: most of the writeable parameters are written to EEPROM of the inverter after each modification. EEPROM has a limited (typically 100000) number of write cycles, so be careful that your automations do not modify these parameters too frequently.
 
 The modes are controlled through "Charger Use Mode", where you can choose one of the following modes by simply selecting one of these values:
@@ -58,25 +56,20 @@ _TBD: Describe how to use Timing Mode with the Integration_
 The passive mode is designed for controlling the inverter with external energy management systems and allows fine control over its operations. So as you are using Home Assistant, this might be the most interesting mode for you besides the default "Self Use" mode.
 
 When the inverter is in "Passive Mode" it can be controlled through:
-- **Passive: Desired Grid Power**: _Number in Watt_. 
-
-  Set the desired power that is taken from the Grid. The system will try to achieve this level within the boundaries of the current consumption, the current production, and the boundaries set by the battery parameters below. Positive values indicate power flow from grid to the system (grid consumption). Negative values indicate power flow from system to the grid (feed-in).
-
-- **Passive: Maximum Battery Power**: _Number in Watt_. 
 
-  Limit the maximum battery power. Must be greater than or equal to "Passive Minimum Battery Power". Positive values indicate charging, negative values indicate discharging.
+- **Passive: Desired Grid Power**: _Number in Watt_. Set the desired power that is taken from the Grid. The system will try to achieve this level within the boundaries of the current consumption, the current production, and the boundaries set by the battery parameters below. Positive values indicate power flow from grid to the system (grid consumption). Negative values indicate power flow from system to the grid (feed-in). Note that after changing the value in this field you have two minutes to commit the new value to the system using the button below. After two minutes the value will be restored to the value that's stored in the system.
 
-- **Passive: Minimum Battery Power**: _Number in Watt_. 
+- **Passive: Maximum Battery Power**: _Number in Watt_. Limit the maximum battery power. Must be greater than or equal to "Passive Minimum Battery Power". Positive values indicate charging, negative values indicate discharging. Note that after changing the value in this field you have two minutes to commit the new value to the system using the button below. After two minutes the value will be restored to the value that's stored in the system.
 
-  Limit the minimum battery power. Must be less than or equal to "Passive Maximum Battery Power". Positive values indicate charging, negative values indicate discharging.
+- **Passive: Minimum Battery Power**: _Number in Watt_. Limit the minimum battery power. Must be less than or equal to "Passive Maximum Battery Power". Positive values indicate charging, negative values indicate discharging. Note that after changing the value in this field you have two minutes to commit the new value to the system using the button below. After two minutes the value will be restored to the value that's stored in the system.
 
-- **Passive: Update Battery Charge/Discharge**: _Button_.
-  
-  After changing "Desired Grid Power", "Maximum Battery Power", or "Minimum Battery Power" this button must be pressed to commit these values to the system. Without pressing this button after changing one or multiple of these values nothing will happen.
+- **Passive: Update Battery Charge/Discharge**: _Button_. After changing "Desired Grid Power", "Maximum Battery Power", or "Minimum Battery Power" this button must be pressed to commit these values to the system. Without pressing this button after changing one or multiple of these values nothing will happen.
 
 Let's have a look at some examples that illustrate how you can use these values to control the energy flow of your inverter:
 
-### Same Operation like "Self Use"
+### Examples
+
+#### Same Operation like "Self Use"
 
 You might rather want to just set the "Self Use" mode, but here is what it would look like it "Passive Mode":
 
@@ -90,7 +83,7 @@ Result:
 
 System tries to pull no energy from the grid. If that is not possible it discharges the battery. In case there is enough PV generation it charges the battery or feeds-in the excess power to the grid. System operates just like in "Self Use".
 
-### Limit Battery Charging Power
+#### Limit Battery Charging Power
 
 You want to limit the charging power to 2kWh to allow more power for other consumers, e.g. charging your car. Useful for example, if you have a 3 phased charger, which requires at least 4.3 kW to start charging, however the PV production is not enough to cover battery charging and minimum power to start charging the car.
 
@@ -104,7 +97,7 @@ Result:
 
 System operates like in "Self Use", however the battery is charged with a maximum of 2 kWh that can be consumed by other power consumers. 
 
-### Prevent Battery Discharging
+#### Prevent Battery Discharging
 
 You want to charge the battery with the PV generation, but would like to prevent it from discharging. E.g. in the winter you want to enforce a full charge cycle over the course of multiple days with little power generation while avoiding pulling extra power from the grid for charging the battery.
 
@@ -120,7 +113,7 @@ Result:
 - If PV generation is larger than consumption, battery will be charged with up to 10 kW. If your battery cannot be charged with 10 kW it will automatically be charged with the maximum amount of power the battery can handle (BTS-5K: 2.5 kWh per module). Excess power will be fed-in to the grid.
 - If PV generation is less than consumption, power will be pulled from the grid. Battery will not be discharged.
 
-### Force Battery Charging
+#### Force Battery Charging
 
 You want to load the battery with a at least 3.5 kWh, but a maximum of 5 kWh.
 
@@ -136,7 +129,7 @@ Result:
 
 Note: Battery management will override the minimum battery power of course. So when the battery is nearly full, charging power will still be reduced even below the value of "Minimum Battery Power" and when the battery is full, charging will be stopped.
 
-### Provide Feed-in Power If Possible
+#### Provide Feed-in Power If Possible
 
 As long as possible you want to prioritize feeding-in at least 1 kW to the grid. Maybe you have the luxury that you get a higher price for feeding in energy than consuming it.
 
@@ -149,9 +142,19 @@ Values:
 Result:
 
 - If PV generation is less than the sum of 1 kW and the consumption of all power consumers, the difference will be fed-in to the grid. Battery will not be discharged.
-- If PV generation is more than the sum of 1kW and the consumption of all power consumers, 1 kW will be fed-in to the grid. Additional power will be used to charge the battery up to its maximum charging power. If PV generation exceeds the maximum charging power it will also be ged in
+- If PV generation is more than the sum of 1kW and the consumption of all power consumers, 1 kW will be fed-in to the grid. Additional power will be used to charge the battery up to its maximum charging power. If PV generation exceeds the maximum charging power additional excess power will be fed-in to the grid.
+
+**IMPORTANT:** Check your local regulations. Many grid operators do not permit feeding in power from the battery to the grid. If you set minimum battery power to negative values, while setting "Desired Grid Power" and/or "Maximum Battery Power" to negative values, you are potentially feeding in power from the battery. While this is technically possible in "Passive Mode" and actually works it might be prohibited by law.
+
+### Timeout and Timeout Action
+
+When in passive mode the inverter can perform a configurable action after it did not receive any communication for longer than a configurable time. This may not be important for automation, however if set to non-default values, it could lead to unexpected side effects.
+
+- **Passive: Timeout**: _Default: Disabled_. The timeout after which the configured timeout action will be executed. Note that the displayed value in this field does not necessarily reflect the current value that is set in the inverter. See the entity "RO: Passive: Timeout" for checking the current value, which will be displayed in number of seconds, where 0 means 'Disabled'.
+
+- **Passive: Timeout Action**: _Default: Force Standby". The timeout action that will be executed after which the configured timeout has passed. By default "Force Standby" is selected. "Return to Previous Mode" will set the previously selected "Charger Use Mode", i.e. if the inverter was switched from "Self Use" into "Passive Mode" the inverter will switch back to "Self Use" after not receiving any communication for the configured "Passive: Timeout". Note that the displayed value in this field does not necessarily reflect the current value that is set in the inverter. See the entity "RO: Passive: Timeout Action" for checking the current value.
 
-**IMPORTANT:** Check your local regulations. Many grid operators do not permit feeding in power from the battery to the grid. If you set minimum battery power to negative values, while setting "Desired Grid Power" and/or "Maximum Battery Power" to negative values, you are potentially feeding in power from the battery. While this is possible in "Passive Mode" and actually works it might be prohibited by law.
+- **Passive: Update Timeout**: _Button_. After chaning "Passive: Timeout" or "Passive: Timeout Action" this button must be pressed to commit the values to the system. Please allow the system several minutes to reflect the changes in the corresponding read-only values.
 
 
 ## Off-Grid (EPS)