fix: SPH time slots are labelled as the inverter numbers them (#386)

Protocol V1.39 and the Growatt app agree on what these registers are. The control
names did not:

  1080-1088   Grid First 1/2/3   displayed as "Grid First Period 7/8/9"
  1100-1108   Bat First 1/2/3    displayed as "AC Charge Time Period N"

The reporter had to work the mapping out by experiment - setting a slot in Home
Assistant and watching which one moved in the app - and then reasonably concluded
the 7/8/9 entities were MOD leftovers wrongly carried into the SPH profile. They
are not. They are Grid First 1-3 under a wrong number, and he withdrew that theory
himself after finding they work.

The second block was true but unhelpful. "AC Charge Time Period" describes what
Battery First does rather than naming the group the app shows, so there was no way
to tell which of the app's schedules an entity belonged to.

Display names only. The control names stay as they are, because entity IDs derive
from them and renaming would break every automation referencing one - too high a
price for a labelling error. Same remedy as #362.

select.py now honours the 'label' key that time.py already read. Start and end are
time entities while enable is a select, so a label read by one platform and not
the other would have left every third entity still mislabelled.

Not changed, per the maintainer: slots 4-6 at 1017-1034. This reporter's firmware
accepts writes there and immediately reverts them, but the registers are properly
documented and other firmware may implement them - and a user who does not have
them can disable the entities. Recorded in the entity reference with the firmware
version that rejects them.

Also documented: Battery First and Grid First are two independent schedules that
run concurrently without conflict, confirmed by running one of each for several
hours. That was not written down anywhere.

1053 tests pass.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 0xAHA

RELEASENOTES.md

@@ -4,6 +4,19 @@
 
 ---
 
+## Unreleased
+
+Merged to `main`, not yet in any release.
+
+- **SPH time-slot entities are now named after the slot the inverter actually uses.** The
+  three Grid First slots displayed as "Grid First Period 7/8/9" but are slots **1, 2 and 3**
+  in the Growatt app and in the protocol, and the Battery First slots displayed as "AC Charge
+  Time Period" with no indication of which app group they belonged to. Entity IDs are
+  unchanged, so automations keep working - only the displayed names are corrected. Reported
+  by @Vict20. (#386)
+
+---
+
 ## v1.6.6 (pre-release)
 
 Issues: #361, #384, #385

custom_components/growatt_modbus/const.py

@@ -595,6 +595,16 @@
         'desc': 'System enable control (SPH HU models)'
     },
 
+    # Battery First time slots 1-3, registers 1100-1108 (#386).
+    #
+    # Protocol V1.39 calls these "Bat First Start/Stop Time 1..3" and the Growatt app shows
+    # them under Battery First, so that is what the labels say. They were previously
+    # displayed as "AC Charge Time Period N", which is true in effect - Battery First is the
+    # charge schedule - but gave no clue which of the app's groups they correspond to.
+    #
+    # The control names keep their existing form. Renaming them would change entity IDs and
+    # break automations, which is too high a price for a labelling error; only the display
+    # name is corrected. Same remedy as #362.
     # AC Charge Time Period Controls (hex-packed: hours*256 + minutes, e.g. 06:00 = 0x0600 = 1536)
     # These are SPH AC-charge scheduling slots (registers 1100-1108), distinct from
     # the Battery First / Grid First extended slots at 1017-1088.
@@ -603,15 +613,15 @@
         'scale': 1,
         'valid_range': (0, 5947),
         'unit': '',
-        'label': 'AC Charge Time Period 1 Start',
+        'label': 'Battery First Period 1 Start',
         'desc': 'AC charge period 1 start time (hex-packed: hours*256+minutes, e.g. 06:00 = 0x0600 = 1536)'
     },
     'time_period_1_end': {
         'register': 1101,
         'scale': 1,
         'valid_range': (0, 5947),
         'unit': '',
-        'label': 'AC Charge Time Period 1 End',
+        'label': 'Battery First Period 1 End',
         'desc': 'AC charge period 1 end time (hex-packed: hours*256+minutes, e.g. 22:00 = 0x1600 = 5632)'
     },
     'time_period_1_enable': {
@@ -622,23 +632,23 @@
             0: 'Disabled',
             1: 'Enabled'
         },
-        'label': 'AC Charge Time Period 1 Enable',
+        'label': 'Battery First Period 1 Enable',
         'desc': 'Enable AC charge time period 1'
     },
     'time_period_2_start': {
         'register': 1103,
         'scale': 1,
         'valid_range': (0, 5947),
         'unit': '',
-        'label': 'AC Charge Time Period 2 Start',
+        'label': 'Battery First Period 2 Start',
         'desc': 'AC charge period 2 start time (hex-packed: hours*256+minutes)'
     },
     'time_period_2_end': {
         'register': 1104,
         'scale': 1,
         'valid_range': (0, 5947),
         'unit': '',
-        'label': 'AC Charge Time Period 2 End',
+        'label': 'Battery First Period 2 End',
         'desc': 'AC charge period 2 end time (hex-packed: hours*256+minutes)'
     },
     'time_period_2_enable': {
@@ -649,23 +659,23 @@
             0: 'Disabled',
             1: 'Enabled'
         },
-        'label': 'AC Charge Time Period 2 Enable',
+        'label': 'Battery First Period 2 Enable',
         'desc': 'Enable AC charge time period 2'
     },
     'time_period_3_start': {
         'register': 1106,
         'scale': 1,
         'valid_range': (0, 5947),
         'unit': '',
-        'label': 'AC Charge Time Period 3 Start',
+        'label': 'Battery First Period 3 Start',
         'desc': 'AC charge period 3 start time (hex-packed: hours*256+minutes)'
     },
     'time_period_3_end': {
         'register': 1107,
         'scale': 1,
         'valid_range': (0, 5947),
         'unit': '',
-        'label': 'AC Charge Time Period 3 End',
+        'label': 'Battery First Period 3 End',
         'desc': 'AC charge period 3 end time (hex-packed: hours*256+minutes)'
     },
     'time_period_3_enable': {
@@ -676,7 +686,7 @@
             0: 'Disabled',
             1: 'Enabled'
         },
-        'desc': 'Enable time period 3'
+        'label': 'Battery First Period 3 Enable', 'desc': 'Enable time period 3'
     },
 
     # SPH GEN3 Battery First extended time slots 4-6 (registers 1017-1025)
@@ -702,15 +712,15 @@
     'grid_first_time_period_6_enable': {'register': 1034, 'scale': 1, 'valid_range': (0, 1), 'options': {0: 'Disabled', 1: 'Enabled'}, 'desc': 'Enable Grid First period 6'},
 
     # SPH GEN3 Grid First extended time slots 7-9 (registers 1080-1088)
-    'grid_first_time_period_7_start': {'register': 1080, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'desc': 'Grid First period 7 start (hex-packed: hours*256+minutes)'},
-    'grid_first_time_period_7_end':   {'register': 1081, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'desc': 'Grid First period 7 end (hex-packed: hours*256+minutes)'},
-    'grid_first_time_period_7_enable': {'register': 1082, 'scale': 1, 'valid_range': (0, 1), 'options': {0: 'Disabled', 1: 'Enabled'}, 'desc': 'Enable Grid First period 7'},
-    'grid_first_time_period_8_start': {'register': 1083, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'desc': 'Grid First period 8 start (hex-packed: hours*256+minutes)'},
-    'grid_first_time_period_8_end':   {'register': 1084, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'desc': 'Grid First period 8 end (hex-packed: hours*256+minutes)'},
-    'grid_first_time_period_8_enable': {'register': 1085, 'scale': 1, 'valid_range': (0, 1), 'options': {0: 'Disabled', 1: 'Enabled'}, 'desc': 'Enable Grid First period 8'},
-    'grid_first_time_period_9_start': {'register': 1086, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'desc': 'Grid First period 9 start (hex-packed: hours*256+minutes)'},
-    'grid_first_time_period_9_end':   {'register': 1087, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'desc': 'Grid First period 9 end (hex-packed: hours*256+minutes)'},
-    'grid_first_time_period_9_enable': {'register': 1088, 'scale': 1, 'valid_range': (0, 1), 'options': {0: 'Disabled', 1: 'Enabled'}, 'desc': 'Enable Grid First period 9'},
+    'grid_first_time_period_7_start': {'register': 1080, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'label': 'Grid First Period 1 Start', 'desc': 'Grid First period 1 start (hex-packed: hours*256+minutes)'},
+    'grid_first_time_period_7_end':   {'register': 1081, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'label': 'Grid First Period 1 End', 'desc': 'Grid First period 1 end (hex-packed: hours*256+minutes)'},
+    'grid_first_time_period_7_enable': {'register': 1082, 'scale': 1, 'valid_range': (0, 1), 'options': {0: 'Disabled', 1: 'Enabled'}, 'label': 'Grid First Period 1 Enable', 'desc': 'Enable Grid First period 7'},
+    'grid_first_time_period_8_start': {'register': 1083, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'label': 'Grid First Period 2 Start', 'desc': 'Grid First period 2 start (hex-packed: hours*256+minutes)'},
+    'grid_first_time_period_8_end':   {'register': 1084, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'label': 'Grid First Period 2 End', 'desc': 'Grid First period 2 end (hex-packed: hours*256+minutes)'},
+    'grid_first_time_period_8_enable': {'register': 1085, 'scale': 1, 'valid_range': (0, 1), 'options': {0: 'Disabled', 1: 'Enabled'}, 'label': 'Grid First Period 2 Enable', 'desc': 'Enable Grid First period 8'},
+    'grid_first_time_period_9_start': {'register': 1086, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'label': 'Grid First Period 3 Start', 'desc': 'Grid First period 3 start (hex-packed: hours*256+minutes)'},
+    'grid_first_time_period_9_end':   {'register': 1087, 'scale': 1, 'valid_range': (0, 5947), 'unit': '', 'label': 'Grid First Period 3 End', 'desc': 'Grid First period 3 end (hex-packed: hours*256+minutes)'},
+    'grid_first_time_period_9_enable': {'register': 1088, 'scale': 1, 'valid_range': (0, 1), 'options': {0: 'Disabled', 1: 'Enabled'}, 'label': 'Grid First Period 3 Enable', 'desc': 'Enable Grid First period 9'},
 
     # MIN TL-X / TL-XH / MIC: fallback output power cap when export limitation control fails
     'export_limit_failed_power_rate': {

custom_components/growatt_modbus/select.py

@@ -240,8 +240,17 @@ def __init__(
         self._control_name = control_name
         self._control_config = control_config
 
-        # Generate friendly name (e.g., "output_config" -> "Output Config")
-        friendly_name = control_name.replace('_', ' ').title()
+        # Generate friendly name (e.g., "output_config" -> "Output Config"), unless the
+        # control carries an explicit label.
+        #
+        # The label exists because a few control names do not describe what the register
+        # actually is. The SPH time-slot blocks are the clearest case (#386): the registers
+        # at 1080-1088 are named ..._7/8/9 here but Protocol V1.39 calls them Grid First
+        # 1/2/3, which is also what the Growatt app shows. A reporter had to work that out by
+        # experiment. The names cannot be changed without changing entity IDs and breaking
+        # everyone's automations, so the display name is corrected instead - the same remedy
+        # used for two SPH controls in #362.
+        friendly_name = control_config.get('label') or control_name.replace('_', ' ').title()
         self._attr_name = friendly_name
 
         # Set icon based on control type

docs/controls/entity-reference.md

@@ -46,15 +46,29 @@ All writes use **read-back verification** — after writing, the integration rea
 | Charge Power Rate | Number | 1090 | 0–100 % | Maximum battery charge power rate |
 | Charge Stop SOC | Number | 1091 | 0–100 % | SOC level at which charging stops |
 | System Enable | Select | 1008 | Disabled (0), Enabled (1) | System enable control (HU models only) |
-| Time Period 1 Start | Number | 1100 | 0–2359 (HHMM) | Charge/discharge period 1 start time |
-| Time Period 1 End | Number | 1101 | 0–2359 (HHMM) | Charge/discharge period 1 end time |
-| Time Period 1 Enable | Select | 1102 | Disabled (0), Enabled (1) | Enable/disable period 1 |
-| Time Period 2 Start | Number | 1103 | 0–2359 (HHMM) | Charge/discharge period 2 start time |
-| Time Period 2 End | Number | 1104 | 0–2359 (HHMM) | Charge/discharge period 2 end time |
-| Time Period 2 Enable | Select | 1105 | Disabled (0), Enabled (1) | Enable/disable period 2 |
-| Time Period 3 Start | Number | 1106 | 0–2359 (HHMM) | Charge/discharge period 3 start time |
-| Time Period 3 End | Number | 1107 | 0–2359 (HHMM) | Charge/discharge period 3 end time |
-| Time Period 3 Enable | Select | 1108 | Disabled (0), Enabled (1) | Enable/disable period 3 |
+| Battery First Period 1 Start | Time | 1100 | HH:MM | Charge schedule slot 1 start |
+| Battery First Period 1 End | Time | 1101 | HH:MM | Charge schedule slot 1 end |
+| Battery First Period 1 Enable | Select | 1102 | Disabled (0), Enabled (1) | Enable charge slot 1 |
+| Battery First Period 2/3 | Time / Select | 1103-1108 | as above | Charge schedule slots 2 and 3 |
+| Grid First Period 1 Start | Time | 1080 | HH:MM | Discharge/export schedule slot 1 start |
+| Grid First Period 1 End | Time | 1081 | HH:MM | Discharge/export schedule slot 1 end |
+| Grid First Period 1 Enable | Select | 1082 | Disabled (0), Enabled (1) | Enable discharge slot 1 |
+| Grid First Period 2/3 | Time / Select | 1083-1088 | as above | Discharge schedule slots 2 and 3 |
+| Battery First / Grid First 4-6 | Time / Select | 1017-1034 | as above | Extra slots - see the note below |
+
+**Two independent schedules.** Battery First (1100-1108) is the charge schedule and Grid
+First (1080-1088) is the discharge/export schedule. They run concurrently and do not
+conflict - confirmed on an SPH 3600 running one of each simultaneously for several hours
+([#386](https://github.com/0xAHA/Growatt_ModbusTCP/issues/386)).
+
+The slot numbers shown match the Growatt app and Protocol V1.39. The underlying entity IDs
+use an older numbering (`grid_first_time_period_7/8/9` for Grid First 1-3, `time_period_*`
+for Battery First), which is kept so existing automations continue to work.
+
+**Slots 4-6 (registers 1017-1034) are documented but may not be implemented on your
+firmware.** They are mapped because the protocol defines them, but at least one SPH 3600
+(RAAA191904/ZCBA-0004) accepts the write and immediately reverts the register. If yours does
+that, disable the entities - other firmware may well support them.
 
 **Notes:**
 - All SPH variants share the same 1000+ register range — controls apply across 3–6kW, 7–10kW, and HU variants automatically.

tests/test_sph_time_slot_labels.py

@@ -0,0 +1,81 @@
+"""SPH time-slot entities must be named after the slot the inverter actually uses (#386).
+
+Protocol V1.39 and the Growatt app agree on what these registers are. The control names did
+not, and a reporter had to determine the mapping by experiment - setting a slot in Home
+Assistant and seeing which one moved in the app.
+
+| Registers | Protocol V1.39 | Control name |
+|---|---|---|
+| 1080-1088 | Grid First 1 / 2 / 3 | grid_first_time_period_7/8/9 |
+| 1100-1108 | Bat First 1 / 2 / 3  | time_period_1/2/3 |
+
+The names are left alone deliberately. Renaming would change entity IDs and break existing
+automations, which is too high a price for a labelling error - the same reasoning as #362,
+where two SPH controls were relabelled rather than renamed. Only the display name is fixed.
+"""
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+_const = importlib.import_module("growatt_under_test.const")
+W = _const.WRITABLE_REGISTERS
+
+# register -> what the protocol and the app both call it
+EXPECTED = {
+    1080: "Grid First Period 1 Start", 1081: "Grid First Period 1 End",
+    1082: "Grid First Period 1 Enable",
+    1083: "Grid First Period 2 Start", 1084: "Grid First Period 2 End",
+    1085: "Grid First Period 2 Enable",
+    1086: "Grid First Period 3 Start", 1087: "Grid First Period 3 End",
+    1088: "Grid First Period 3 Enable",
+    1100: "Battery First Period 1 Start", 1101: "Battery First Period 1 End",
+    1102: "Battery First Period 1 Enable",
+    1103: "Battery First Period 2 Start", 1104: "Battery First Period 2 End",
+    1105: "Battery First Period 2 Enable",
+    1106: "Battery First Period 3 Start", 1107: "Battery First Period 3 End",
+    1108: "Battery First Period 3 Enable",
+}
+
+BY_REGISTER = {cfg["register"]: (name, cfg) for name, cfg in W.items() if "register" in cfg}
+
+
+@pytest.mark.parametrize("register,label", sorted(EXPECTED.items()))
+def test_the_slot_is_labelled_as_the_inverter_numbers_it(register, label):
+    name, cfg = BY_REGISTER[register]
+    assert cfg.get("label") == label, (
+        f"register {register} ({name}) displays as {cfg.get('label') or name!r}, but the "
+        f"protocol and the Growatt app both call it {label!r}"
+    )
+
+
+@pytest.mark.parametrize("register", sorted(EXPECTED))
+def test_control_names_are_not_renamed(register):
+    """The other half of the decision. Correcting the label must not become a rename -
+    entity IDs derive from the control name and automations reference them."""
+    name, _ = BY_REGISTER[register]
+    if 1080 <= register <= 1088:
+        assert name.startswith("grid_first_time_period_"), f"{register} was renamed to {name}"
+    else:
+        assert name.startswith("time_period_"), f"{register} was renamed to {name}"
+
+
+def test_both_platforms_honour_the_label():
+    """Start/end are time entities and enable is a select. A label read by one and not the
+    other would leave every third entity still mislabelled."""
+    from pathlib import Path
+    base = Path(__file__).parent.parent / "custom_components" / "growatt_modbus"
+    for platform in ("time.py", "select.py"):
+        source = (base / platform).read_text(encoding="utf-8")
+        assert "control_config.get('label')" in source, (
+            f"{platform} ignores the label, so its entities keep the misleading name"
+        )
+
+
+def test_the_4_to_6_slots_are_left_alone():
+    """Those registers are documented and correctly named; one firmware rejects writes to
+    them. Other firmware may not, and a user can disable the entities - so they stay."""
+    for n in (4, 5, 6):
+        assert f"grid_first_time_period_{n}_start" in W
+        assert f"batt_first_time_period_{n}_start" in W