Merge pull request #1489 from infradom/main

Introduce defaults for scangroups in plugin declaration - plugin solax now uses scangroups

Author: wills106

custom_components/solax_modbus/__init__.py

@@ -119,6 +119,8 @@ class CoreModbusHub:
     REGISTER_ULSB16MSB16,
     REGISTER_WORDS,
     SCAN_GROUP_DEFAULT,
+    SCAN_GROUP_MEDIUM,
+    SCAN_GROUP_AUTO,
     # PLUGIN_PATH,
     SLEEPMODE_LASTAWAKE,
     CONF_TIME_OUT,
@@ -129,6 +131,8 @@ class CoreModbusHub:
     WRITE_MULTI_MODBUS,
     WRITE_SINGLE_MODBUS,
     WRITE_MULTISINGLE_MODBUS,
+    REG_HOLDING,
+    REG_INPUT,
 )
 
 PLATFORMS = [Platform.BUTTON, Platform.NUMBER, Platform.SELECT, Platform.SENSOR, Platform.SWITCH]
@@ -443,17 +447,32 @@ def loadLocalData(self):
 
     # end of save and load section
 
-    def entity_group(self, sensor):
+    def entity_group(self, sensor): # seems to be called for non-sensor entities also - strange
         # scan group
         g = getattr(sensor.entity_description, "scan_group", None)
         if not g:
-            g = SCAN_GROUP_DEFAULT
+            regtype = getattr(sensor.entity_description, "register_type", None)
+            if   regtype == REG_HOLDING: g = self.plugin.default_holding_scangroup
+            elif regtype == REG_INPUT:   g = self.plugin.default_input_scangroup
+            else: g = SCAN_GROUP_DEFAULT # should not occur
+
+        if g == SCAN_GROUP_AUTO:
+            unit = getattr(sensor.entity_description, "native_unit_of_measurement", None)
+            if unit in (  # slow changing values
+                    UnitOfEnergy.WATT_HOUR, 
+                    UnitOfEnergy.KILO_WATT_HOUR,
+                    UnitOfFrequency.HERTZ,
+                    UnitOfTemperature.CELSIUS,
+                    UnitOfTemperature.FAHRENHEIT,
+                    UnitOfTemperature.KELVIN,
+                    UnitOfTime.HOURS,
+                ): g = self.plugin.auto_slow_scangroup
+            else:  g = self.plugin.auto_default_scangroup
         # scan interval
         g = self.config.get(g, None)
         # when declared but not present in config, use default; this MUST exist
         if not g:
             g = self.config[SCAN_GROUP_DEFAULT]
-
         return g
 
     def device_group_key(self, device_info: DeviceInfo):
@@ -1123,8 +1142,8 @@ def rebuild_blocks(self, initial_groups): #, computedRegs):
                 hub_device_group.holdingBlocks = self.splitInBlocks(holdingRegs)
                 hub_device_group.inputBlocks = self.splitInBlocks(inputRegs)
                 #self.computedSensors = computedRegs # moved outside the loops
-                for i in hub_device_group.holdingBlocks: _LOGGER.info(f"{self._name} interval {interval} dev {device_name} returning holding block: 0x{i.start:x} 0x{i.end:x} {i.regs}")
-                for i in hub_device_group.inputBlocks: _LOGGER.info(f"{self._name} interval {interval} dev {device_name} returning input block: 0x{i.start:x} 0x{i.end:x} {i.regs}")
+                for i in hub_device_group.holdingBlocks: _LOGGER.info(f"{device_name} - interval {interval}s: adding holding block: {', '.join('0x{:x}'.format(num) for num in i.regs)}")
+                for i in hub_device_group.inputBlocks: _LOGGER.info(f"{device_name} - interval {interval}s: adding input block: {', '.join('0x{:x}'.format(num) for num in i.regs)}")
                 _LOGGER.debug(f"holdingBlocks: {hub_device_group.holdingBlocks}")
                 _LOGGER.debug(f"inputBlocks: {hub_device_group.inputBlocks}")
         self.blocks_changed = False

custom_components/solax_modbus/const.py

@@ -92,6 +92,7 @@ class UnitOfReactivePower(StrEnum):
 SCAN_GROUP_DEFAULT = CONF_SCAN_INTERVAL  # default scan group, slow; should always work
 SCAN_GROUP_MEDIUM = CONF_SCAN_INTERVAL_MEDIUM  # medium speed scanning (energy, temp, soc...)
 SCAN_GROUP_FAST = CONF_SCAN_INTERVAL_FAST  # fast scanning (power,...)
+SCAN_GROUP_AUTO = "auto"  # _MEDIUM for temperatures, frequency and energy (kWh), otherwise _DEFAULT
 CONF_TIME_OUT = "time_out"
 DEFAULT_TIME_OUT = 5
 
@@ -151,6 +152,10 @@ class plugin_base:
     order16: int | None = None  # Endian.BIG or Endian.LITTLE
     order32: int | None = None
     inverter_model: str = None
+    default_holding_scangroup: str = SCAN_GROUP_DEFAULT  
+    default_input_scangroup: str = SCAN_GROUP_DEFAULT   # or SCAN_GROUP_AUTO
+    auto_default_scangroup: str = SCAN_GROUP_FAST, # only used when default_xxx_scangroup is set to SCAN_GROUP_AUTO
+    auto_slow_scangroup: str = SCAN_GROUP_MEDIUM, # only usedwhen default_xxx_scangroup is set to SCAN_GROUP_AUTO
 
     def isAwake(self, datadict):
         return True  # always awake by default
@@ -194,7 +199,7 @@ class BaseModbusSensorEntityDescription(SensorEntityDescription):
     blacklist: list = None
     register: int = -1  # initialize with invalid register
     rounding: int = 1
-    register_type: int = None  # REGISTER_HOLDING or REGISTER_INPUT or REG_DATA
+    register_type: int = None  # REG_HOLDING or REG_INPUT or REG_DATA
     unit: int = None  # e.g. REGISTER_U16
     scan_group: int = None  # <=0 -> default group
     internal: bool = False  # internal sensors are used for reading data only; used for computed, selects, etc

custom_components/solax_modbus/plugin_solax.py

@@ -4594,6 +4594,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
             0: "Disconnected",
             1: "Connected",
         },
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         allowedtypes=AC | HYBRID | GEN3 | GEN4 | GEN5 | GEN6,
         icon="mdi:state-machine",
@@ -4655,14 +4656,15 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         state_class=SensorStateClass.MEASUREMENT,
         register=0x1C,
         register_type=REG_INPUT,
-        allowedtypes=AC | HYBRID | GEN2 | GEN3 | GEN4,
+        allowedtypes=AC | HYBRID | GEN2 | GEN3 | GEN4 ,
     ),
     SolaXModbusSensorEntityDescription(
         name="Battery 1 Capacity",
         key="battery_1_capacity_charge",
         native_unit_of_measurement=PERCENTAGE,
         device_class=SensorDeviceClass.BATTERY,
         register=0x1C,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         allowedtypes=AC | HYBRID | GEN5 | GEN6,
     ),
@@ -4753,6 +4755,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         name="Battery Package Number",
         key="battery_package_number",
         register=0x22,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         entity_registry_enabled_default=False,
         allowedtypes=HYBRID | GEN2,
@@ -4762,6 +4765,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         key="battery_state_of_health",
         icon="mdi:battery-heart",
         register=0x23,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         native_unit_of_measurement=PERCENTAGE,
         entity_registry_enabled_default=False,
@@ -4786,6 +4790,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
         entity_registry_enabled_default=False,
         register=0x24,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -4798,6 +4803,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
         entity_registry_enabled_default=False,
         register=0x25,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5042,6 +5048,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
             1: "Unlocked",
             2: "Unlocked - Advanced",
         },
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         allowedtypes=AC | HYBRID,
         internal=True,
@@ -5053,6 +5060,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         device_class=SensorDeviceClass.VOLTAGE,
         entity_registry_enabled_default=False,
         register=0x66,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5065,6 +5073,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         device_class=SensorDeviceClass.VOLTAGE,
         entity_registry_enabled_default=False,
         register=0x67,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5074,6 +5083,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         name="Overload Fault Val",
         key="overload_fault_val",
         register=0x68,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         entity_registry_enabled_default=False,
         allowedtypes=AC | HYBRID,
@@ -5085,6 +5095,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0x69,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5247,6 +5258,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0x76,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5258,6 +5270,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
         device_class=SensorDeviceClass.CURRENT,
         register=0x77,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5327,6 +5340,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0x7E,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5338,6 +5352,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricCurrent.AMPERE,
         device_class=SensorDeviceClass.CURRENT,
         register=0x7F,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5358,6 +5373,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         key="eps_power_l3",
         native_unit_of_measurement=UnitOfApparentPower.VOLT_AMPERE,
         register=0x81,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         allowedtypes=AC | HYBRID | GEN3 | GEN4 | GEN5 | X3 | EPS,
     ),
@@ -5568,6 +5584,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
     SolaXModbusSensorEntityDescription(
         key="grid_export_limit",
         register=0x9C,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         unit=REGISTER_S32,
         allowedtypes=AC | HYBRID | GEN3,
@@ -5737,6 +5754,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0xBC,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.001,
         rounding=3,
@@ -5749,6 +5767,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0xBD,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.001,
         rounding=3,
@@ -5773,6 +5792,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=PERCENTAGE,
         state_class=SensorStateClass.MEASUREMENT,
         register=0xBF,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         entity_registry_enabled_default=False,
         allowedtypes=AC | HYBRID | GEN4 | GEN5,
@@ -5795,6 +5815,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0xC9,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5807,6 +5828,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0xCA,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5819,6 +5841,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0xCB,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5831,6 +5854,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=UnitOfElectricPotential.VOLT,
         device_class=SensorDeviceClass.VOLTAGE,
         register=0xCC,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         scale=0.1,
         rounding=1,
@@ -5956,6 +5980,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         device_class=SensorDeviceClass.REACTIVE_POWER,
         state_class=SensorStateClass.MEASUREMENT,
         register=0x10E,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         unit=REGISTER_S32,
         allowedtypes=AC | HYBRID | GEN4 | GEN5,
@@ -5967,6 +5992,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         device_class=SensorDeviceClass.REACTIVE_POWER,
         state_class=SensorStateClass.MEASUREMENT,
         register=0x110,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         unit=REGISTER_S32,
         allowedtypes=AC | HYBRID | GEN4 | GEN5,
@@ -6089,6 +6115,7 @@ def value_function_battery_voltage_cell_difference(initval, descr, datadict):
         native_unit_of_measurement=PERCENTAGE,
         device_class=SensorDeviceClass.BATTERY,
         register=0x12E,
+        scan_group = SCAN_GROUP_DEFAULT,
         register_type=REG_INPUT,
         allowedtypes=HYBRID | GEN5,
     ),
@@ -8716,4 +8743,8 @@ def localDataCallback(self, hub):
     order16=Endian.BIG,
     order32=Endian.LITTLE,
     auto_block_ignore_readerror=True,
+    default_holding_scangroup=SCAN_GROUP_MEDIUM, 
+    default_input_scangroup=SCAN_GROUP_AUTO, # SCAN_GROUP_MEDIUM for slow changing units like temperature, kWh, ...
+    auto_default_scangroup=SCAN_GROUP_FAST,
+    auto_slow_scangroup=SCAN_GROUP_MEDIUM,
 )

docs/developer_guide.md

@@ -90,8 +90,32 @@ Documentation to be completed ...
 
 ## Scan groups for differentiated polling
 Some inverter plugins use different scan groups (to differentiate between slowly changing sensor entities and entities that are updated frequently?)
-To be documented ...
-
+This is determined by the presence of attribute scan_group on sensor entities.
+The scan_group attribute can take following values: SCAN_GROUP_DEFAULT, SCAN_GROUP_MEDIUM,  SCAN_GROUP_FAST or SCAN_GROUP_AUTO
+If no scan_group is specified, the plugin-specific default will be used. There can be a different default for holding and input registers. See the plugin declaration at the end of your plugin. Example: 
+```
+plugin_instance = solax_plugin(
+    plugin_name="SolaX",
+    plugin_manufacturer="SolaX Power",
+    SENSOR_TYPES=SENSOR_TYPES_MAIN,
+    NUMBER_TYPES=NUMBER_TYPES,
+    BUTTON_TYPES=BUTTON_TYPES,
+    SELECT_TYPES=SELECT_TYPES,
+    SWITCH_TYPES=[],
+    block_size=100,
+    order16=Endian.BIG,
+    order32=Endian.LITTLE,
+    auto_block_ignore_readerror=True,
+    default_holding_scangroup=SCAN_GROUP_DEFAULT, 
+    default_input_scangroup=SCAN_GROUP_AUTO,
+    auto_default_scangroup=SCAN_GROUP_FAST,
+    auto_slow_scangroup=SCAN_GROUP_MEDIUM,
+)
+``` 
+The actual polling speed for each group is determined during initial or subsequent configuration of the intergration (config_flow).
+If the 3 polling group times are set to the same value, the system will act as if there is only one scangroup (they are merged together by interval time)
+
+If SCAN_GROUP_AUTO is chosen for `default_input_scangroup` or `default_holding_scangroup`, entities without a `scan_group` declararation will get the value specified in `plugin.auto_slow_scangroup` if their native unit is slowly changing like temperatures or kWh .., otherwise the value specified in `plugin.auto_default_scangroup`
 
 
 ## Autorepeat mechanism for buttons

docs/solax-mode1-modbus-power-control.md

@@ -19,12 +19,14 @@ The work described here uses mode 1 from the Solax KB document: [KB document : S
 A similar autorepeat mechanism is under development for mode 8
 
 ### Note:
-For people using external tasks to control the power, the _remotecontrol_xxx_direct_ versions of the entities could be used. This is outside the scope if this wiki page.
+ - For people using external tasks to control the power, the _remotecontrol_xxx_direct_ versions of the entities could be used. This is outside the scope if this wiki page.
+ - If you use modbus power control autorepeat loops, make sure the polling interval for the fastest scangroup is sufficiently low e.g. 3-5 seconds, otherwise the values are updated too slowly. A too short interval can overload your system or modbus communication bus. Some people can go as low as 1 second, but it is safer to have more margin.
 
 ***
 ## Solax Gen4 approach - Mode 1
 ***
 
+
 The Solax Gen4 inverters and higher use a modbus write_multiple_registers command.
 On the Gen4, these actions are not stored in EEPROM, so they can be executed frequently.
 The integration hides this complexity and implements one button to trigger a single or repeated update(s). The action behind this button is configurable through 6 parameter entities.

docs/solax-mode8-modbus-power-control.md

@@ -21,6 +21,7 @@ A similar autorepeat mechanism is available for mode 1; see the dedicated wiki p
 * For people using external tasks to control the power, the _remotecontrol_xxx_direct_ versions of the entities could be used. This is outside the scope if this wiki page.
 * Although the addition of Mode 8 in new firmwares is a big enhancement, we still feel there is a missing mode that focusses on the grid interface and can limit the PV in case of negative prices. Our Mode 8 autorepeat loop tries to emulate this, but can only adjust every polling cycle, a firmware based solution could react faster.
 * This mechanism will only work on the most recent firmware versions; previous versions do not support mode 8 or 9. I am running Firmware: DSP v1.52 ARM v1.50 at the time of my testing
+* If you use modbus power control autorepeat loops, make sure the polling interval for the fastest scangroup is sufficiently low e.g. 3-5 seconds, otherwise the values are updated too slowly. A too short interval can overload your system or modbus communication bus. Some people can go as low as 1 second, but it is safer to have more margin.
 
 
 ### KNOWN ISSUES: (Work in progress):