Fix zone validation and improve zone ID guidance in config flow

Add zone ID validation against pyxantech device config in both config
flow and options flow, rejecting IDs outside the device's valid set.

Update UX text to clarify both zone formats: two-digit (11-18) for
most Xantech models (MRC88, MX88) and single-digit (1-8) for
standalone MRAUDIO8x8 units.

Require pyxantech>=0.10.7 which accepts alternative_zones.
Bump version to 0.3.2.

Author: rsnodgrass

custom_components/xantech/config_flow.py

@@ -24,7 +24,7 @@
     TextSelectorConfig,
     TextSelectorType,
 )
-from pyxantech import async_get_amp_controller
+from pyxantech import async_get_amp_controller, get_device_config
 from serial import SerialException
 import voluptuous as vol
 
@@ -44,6 +44,9 @@
 
 LOG = logging.getLogger(__name__)
 
+# type alias to reduce line length in signatures
+ZonesDict = dict[int, dict[str, str]]
+
 
 class XantechConfigFlow(ConfigFlow, domain=DOMAIN):
     """Handle a config flow for Xantech Multi-Zone Amplifier."""
@@ -115,7 +118,9 @@ async def async_step_zones(
         if user_input is not None:
             # parse zones configuration
             zones_text = user_input.get('zones_config', '')
-            zones = self._parse_zones_config(zones_text)
+            zones = self._parse_zones_config(
+                zones_text, self._data.get(CONF_AMP_TYPE)
+            )
 
             if not zones:
                 errors['base'] = 'invalid_zones'
@@ -197,12 +202,15 @@ async def async_step_sources(
             },
         )
 
-    def _parse_zones_config(self, text: str) -> dict[int, dict[str, str]]:
+    def _parse_zones_config(
+        self, text: str, amp_type: str | None = None,
+    ) -> ZonesDict:
         """Parse zone configuration text into structured dict.
 
         Format: 'zone_id: zone_name' per line
+        Validates zone IDs against device config when amp_type provided.
         """
-        zones: dict[int, dict[str, str]] = {}
+        zones: ZonesDict = {}
         for line in text.strip().split('\n'):
             line = line.strip()
             if not line or ':' not in line:
@@ -213,6 +221,18 @@ def _parse_zones_config(self, text: str) -> dict[int, dict[str, str]]:
                 zones[zone_id] = {'name': name.strip()}
             except ValueError:
                 continue
+
+        if amp_type and zones:
+            valid_zones = (
+                get_device_config(amp_type, 'zones') or {}
+            )
+            alt_zones = get_device_config(
+                amp_type, 'alternative_zones', log_missing=False,
+            ) or {}
+            all_valid = {**valid_zones, **alt_zones}
+            if any(z not in all_valid for z in zones):
+                return {}
+
         return zones
 
     def _parse_sources_config(self, text: str) -> dict[int, dict[str, str]]:
@@ -243,9 +263,11 @@ def _get_default_zones_text(self, amp_type: str) -> str:
         if amp_type == 'dax88':
             return (
                 '11: Living Room\n12: Kitchen\n13: Master Bedroom\n'
-                '14: Office\n15: Patio\n16: Dining Room\n17: Garage\n18: Basement'
+                '14: Office\n15: Patio\n16: Dining Room\n'
+                '17: Garage\n18: Basement'
             )
-        # default to xantech8
+        # xantech8: most models (MRC88, MX88) use 11-18 addressing;
+        # older MRAUDIO8x8 standalone units also accept 1-8
         return (
             '11: Living Room\n12: Kitchen\n13: Master Bedroom\n'
             '14: Office\n15: Patio\n16: Dining Room'
@@ -360,7 +382,8 @@ async def async_step_zones(
 
         if user_input is not None:
             zones_text = user_input.get('zones_config', '')
-            zones = self._parse_zones_config(zones_text)
+            amp_type = self.config_entry.data.get(CONF_AMP_TYPE)
+            zones = self._parse_zones_config(zones_text, amp_type)
 
             if not zones:
                 errors['base'] = 'invalid_zones'
@@ -437,9 +460,11 @@ async def async_step_sources(
             },
         )
 
-    def _parse_zones_config(self, text: str) -> dict[int, dict[str, str]]:
+    def _parse_zones_config(
+        self, text: str, amp_type: str | None = None,
+    ) -> ZonesDict:
         """Parse zone configuration text into structured dict."""
-        zones: dict[int, dict[str, str]] = {}
+        zones: ZonesDict = {}
         for line in text.strip().split('\n'):
             line = line.strip()
             if not line or ':' not in line:
@@ -450,6 +475,18 @@ def _parse_zones_config(self, text: str) -> dict[int, dict[str, str]]:
                 zones[zone_id] = {'name': name.strip()}
             except ValueError:
                 continue
+
+        if amp_type and zones:
+            valid_zones = (
+                get_device_config(amp_type, 'zones') or {}
+            )
+            alt_zones = get_device_config(
+                amp_type, 'alternative_zones', log_missing=False,
+            ) or {}
+            all_valid = {**valid_zones, **alt_zones}
+            if any(z not in all_valid for z in zones):
+                return {}
+
         return zones
 
     def _parse_sources_config(self, text: str) -> dict[int, dict[str, str]]:

custom_components/xantech/manifest.json

@@ -1,10 +1,10 @@
 {
     "domain": "xantech",
     "name": "Xantech Multi-Zone Audio",
-    "version": "0.3.1",
+    "version": "0.3.2",
     "documentation": "https://github.com/rsnodgrass/hass-xantech",
     "issue_tracker": "https://github.com/rsnodgrass/hass-xantech/issues",
-    "requirements": ["pyxantech>=0.10.5"],
+    "requirements": ["pyxantech>=0.10.7"],
     "homeassistant": "2025.2.0",
     "codeowners": ["@rsnodgrass"],
     "config_flow": true,

custom_components/xantech/strings.json

@@ -15,7 +15,7 @@
             },
             "zones": {
                 "title": "Name Your Zones",
-                "description": "Give each zone a friendly name. Zone IDs use standard addressing: first digit is the controller unit (1-3), second digit is the zone output (1-8). For example, 11-18 are zones on controller 1.",
+                "description": "Give each zone a friendly name.\n\nFor most Xantech models (MRC88, MX88), use two-digit zone IDs: first digit is the controller unit (1-3), second digit is the zone (1-8). For example, 11-18 for controller 1.\n\nStandalone MRAUDIO8x8 units also accept single-digit zones (1-8).",
                 "data": {
                     "zones_config": "Zone Configuration",
                     "enable_audio_controls": "Advanced audio controls"
@@ -39,7 +39,7 @@
         "error": {
             "cannot_connect": "Could not connect. Verify the serial port path and cable connection.",
             "unknown": "An unexpected error occurred.",
-            "invalid_zones": "Could not parse zones. Use format: 11: Living Room",
+            "invalid_zones": "Invalid zone IDs for this amplifier type. Check your model's documentation for valid zone numbers.",
             "invalid_sources": "Could not parse sources. Use format: 1: TV"
         },
         "abort": {
@@ -81,7 +81,7 @@
             },
             "zones": {
                 "title": "Edit Zones",
-                "description": "Update zone names. Zone IDs use standard addressing: first digit is the controller unit (1-3), second digit is the zone output (1-8).",
+                "description": "Update zone names. Most Xantech models use two-digit zone IDs (11-18 for controller 1). Standalone MRAUDIO8x8 units also accept 1-8.",
                 "data": {
                     "zones_config": "Zone Configuration"
                 },

custom_components/xantech/translations/en.json

@@ -15,7 +15,7 @@
             },
             "zones": {
                 "title": "Name Your Zones",
-                "description": "Give each zone a friendly name. Zone IDs use standard addressing: first digit is the controller unit (1-3), second digit is the zone output (1-8). For example, 11-18 are zones on controller 1.",
+                "description": "Give each zone a friendly name.\n\nFor most Xantech models (MRC88, MX88), use two-digit zone IDs: first digit is the controller unit (1-3), second digit is the zone (1-8). For example, 11-18 for controller 1.\n\nStandalone MRAUDIO8x8 units also accept single-digit zones (1-8).",
                 "data": {
                     "zones_config": "Zone Configuration"
                 },
@@ -37,7 +37,7 @@
         "error": {
             "cannot_connect": "Could not connect. Verify the serial port path and cable connection.",
             "unknown": "An unexpected error occurred.",
-            "invalid_zones": "Could not parse zones. Use format: 11: Living Room",
+            "invalid_zones": "Invalid zone IDs for this amplifier type. Check your model's documentation for valid zone numbers.",
             "invalid_sources": "Could not parse sources. Use format: 1: TV"
         },
         "abort": {
@@ -78,7 +78,7 @@
             },
             "zones": {
                 "title": "Edit Zones",
-                "description": "Update zone names. Zone IDs use standard addressing: first digit is the controller unit (1-3), second digit is the zone output (1-8).",
+                "description": "Update zone names. Most Xantech models use two-digit zone IDs (11-18 for controller 1). Standalone MRAUDIO8x8 units also accept 1-8.",
                 "data": {
                     "zones_config": "Zone Configuration"
                 },

tests/test_config_flow.py

@@ -12,7 +12,6 @@
 from custom_components.xantech.const import (
     CONF_AMP_TYPE,
     CONF_PORT,
-    CONF_SCAN_INTERVAL,
     DOMAIN,
 )
 
@@ -220,3 +219,43 @@ def test_options_flow_stores_config_entry_correctly() -> None:
     assert hasattr(flow, '_config_entry'), 'Flow must store entry in _config_entry'
     assert flow._config_entry is mock_entry
     assert flow._config_entry.data['port'] == '/dev/ttyUSB0'
+
+
+def test_xantech8_default_zones_use_double_digit() -> None:
+    """Test that xantech8 config flow defaults use double-digit zone IDs.
+
+    Most xantech8 models (MRC88, MX88) use two-digit addressing (11-18).
+    Standalone MRAUDIO8x8 also accepts 1-8, but defaults target the common case.
+    """
+    from custom_components.xantech.config_flow import XantechConfigFlow
+
+    flow = XantechConfigFlow()
+    defaults = flow._get_default_zones_text('xantech8')
+
+    for line in defaults.strip().split('\n'):
+        zone_id = int(line.split(':')[0].strip())
+        assert 11 <= zone_id <= 18, f'xantech8 default zone {zone_id} should be 11-18'
+
+
+def test_monoprice6_default_zones_use_double_digit() -> None:
+    """Test that monoprice6 config flow defaults use double-digit zone IDs."""
+    from custom_components.xantech.config_flow import XantechConfigFlow
+
+    flow = XantechConfigFlow()
+    defaults = flow._get_default_zones_text('monoprice6')
+
+    for line in defaults.strip().split('\n'):
+        zone_id = int(line.split(':')[0].strip())
+        assert zone_id >= 11, f'monoprice6 default zone {zone_id} should be >= 11'
+
+
+def test_dax88_default_zones_use_double_digit() -> None:
+    """Test that dax88 config flow defaults use double-digit zone IDs."""
+    from custom_components.xantech.config_flow import XantechConfigFlow
+
+    flow = XantechConfigFlow()
+    defaults = flow._get_default_zones_text('dax88')
+
+    for line in defaults.strip().split('\n'):
+        zone_id = int(line.split(':')[0].strip())
+        assert zone_id >= 11, f'dax88 default zone {zone_id} should be >= 11'