feat: enhance vehicle discovery metrics and improve user feedback

Author: enoch85

custom_components/ovms/config_flow/__init__.py

@@ -320,7 +320,11 @@ async def async_step_topic_discovery(self, user_input=None):
 
             topics_count = len(self.discovered_topics or [])
             metric_count = discovery_result.get("metric_count", topics_count)
-            discovery_quality = discovery_result.get("discovery_quality", "unknown")
+            vehicle_type = discovery_result.get("vehicle_type", "generic")
+            vehicle_name = discovery_result.get("vehicle_name", "Generic OVMS")
+            expected_count = discovery_result.get("expected_count", 196)
+            discovery_percentage = discovery_result.get("discovery_percentage", 0)
+            quality_indicator = discovery_result.get("quality_indicator", "❌")
 
             # Filter to show only metric topics in sample
             metric_topics = [t for t in self.discovered_topics if "/metric/" in t]
@@ -334,11 +338,13 @@ async def async_step_topic_discovery(self, user_input=None):
             sample_topics = topics_sample + [""] * (5 - len(topics_sample))
 
             _LOGGER.debug(
-                "Discovered %d topics (%d metrics, quality: %s): %s",
+                "Discovered %d topics (%d metrics). Vehicle: %s. Coverage: %d%% (%d/%d)",
                 topics_count,
                 metric_count,
-                discovery_quality,
-                topics_sample,
+                vehicle_name,
+                discovery_percentage,
+                metric_count,
+                expected_count,
             )
 
             # Extract potential vehicle IDs from discovered topics
@@ -354,22 +360,10 @@ async def async_step_topic_discovery(self, user_input=None):
             )
 
             self.debug_info["potential_vehicle_ids"] = list(potential_vehicle_ids)
-            self.debug_info["discovery_quality"] = discovery_quality
+            self.debug_info["vehicle_type"] = vehicle_type
+            self.debug_info["discovery_percentage"] = discovery_percentage
             _LOGGER.debug("Potential vehicle IDs: %s", potential_vehicle_ids)
 
-            # Generate quality message for user feedback
-            quality_messages = {
-                "excellent": "✅ Excellent - Your OVMS module is responding well with full metrics.",
-                "good": "✅ Good - Discovery completed successfully.",
-                "partial": "⚠️ Partial - Some metrics received. Additional entities may appear when module publishes more data.",
-                "minimal": "⚠️ Minimal - Very few metrics found. Ensure your OVMS module is online and publishing.",
-                "none": "❌ No metrics found. Check that your OVMS module is connected and configured for MQTT.",
-                "unknown": "Discovery completed.",
-            }
-            quality_message = quality_messages.get(
-                discovery_quality, quality_messages["unknown"]
-            )
-
             # Create a schema without the confirmation checkbox
             data_schema = vol.Schema({})
 
@@ -384,8 +378,10 @@ async def async_step_topic_discovery(self, user_input=None):
                 description_placeholders={
                     "topic_count": str(topics_count),
                     "metric_count": str(metric_count),
-                    "discovery_quality": discovery_quality,
-                    "quality_message": quality_message,
+                    "expected_count": str(expected_count),
+                    "vehicle_name": vehicle_name,
+                    "discovery_percentage": str(discovery_percentage),
+                    "quality_indicator": quality_indicator,
                     "sample_topic1": sample_topics[0],
                     "sample_topic2": sample_topics[1],
                     "sample_topic3": sample_topics[2],

custom_components/ovms/config_flow/topic_discovery.py

@@ -39,18 +39,137 @@
     METRIC_REQUEST_TOPIC_TEMPLATE,
     ACTIVE_DISCOVERY_TIMEOUT,
     LEGACY_DISCOVERY_TIMEOUT,
-    MINIMUM_DISCOVERY_TOPICS,
-    GOOD_DISCOVERY_TOPICS,
-    EXCELLENT_DISCOVERY_TOPICS,
+    MINIMUM_DISCOVERY_PERCENT,
+    GOOD_DISCOVERY_PERCENT,
+    GENERIC_VEHICLE_TYPE,
+    GENERIC_VEHICLE_NAME,
     LOGGER_NAME,
     ERROR_CANNOT_CONNECT,
     ERROR_TIMEOUT,
     ERROR_UNKNOWN,
 )
+from ..metrics.vehicles import VEHICLE_TYPE_PREFIXES, VEHICLE_TYPE_NAMES
 
 _LOGGER = logging.getLogger(LOGGER_NAME)
 
 
+def detect_vehicle_type(topics: Set[str]) -> tuple[str, str]:
+    """Detect vehicle type from discovered topics.
+
+    Looks for vehicle-specific metric prefixes (xvu., xse., xmg., xnl., xrt.)
+    in the topic paths to determine the vehicle type.
+
+    Args:
+        topics: Set of discovered MQTT topics
+
+    Returns:
+        Tuple of (vehicle_type_id, vehicle_type_name)
+        e.g., ("vw_eup", "VW e-UP!") or ("generic", "Generic OVMS")
+    """
+    for topic in topics:
+        # Extract metric path from topic (last part after /metric/)
+        if "/metric/" in topic:
+            metric_path = topic.split("/metric/")[-1]
+            # Check for vehicle-specific prefixes
+            for prefix, vehicle_type in VEHICLE_TYPE_PREFIXES.items():
+                if metric_path.startswith(prefix):
+                    vehicle_name = VEHICLE_TYPE_NAMES.get(vehicle_type, vehicle_type)
+                    _LOGGER.debug(
+                        "Detected vehicle type '%s' (%s) from topic: %s",
+                        vehicle_type,
+                        vehicle_name,
+                        topic,
+                    )
+                    return vehicle_type, vehicle_name
+
+    return GENERIC_VEHICLE_TYPE, GENERIC_VEHICLE_NAME
+
+
+def get_expected_metric_count(vehicle_type: str) -> int:
+    """Get the expected number of metrics for a vehicle type.
+
+    Calculates expected metrics by counting defined metrics from the metrics module.
+    This provides a dynamic count based on actual metric definitions.
+
+    Args:
+        vehicle_type: Vehicle type identifier (e.g., "vw_eup", "generic")
+
+    Returns:
+        Expected number of metrics for this vehicle type
+    """
+    # Import here to avoid circular imports
+    # pylint: disable=import-outside-toplevel
+    from ..metrics import METRIC_DEFINITIONS
+
+    # Common categories that apply to all vehicles
+    common_categories = [
+        "battery",
+        "charging",
+        "climate",
+        "door",
+        "location",
+        "motor",
+        "trip",
+        "device",
+        "diagnostic",
+        "power",
+        "network",
+        "system",
+        "tire",
+    ]
+
+    # Count common metrics
+    common_count = sum(
+        1 for v in METRIC_DEFINITIONS.values() if v.get("category") in common_categories
+    )
+
+    # Add vehicle-specific metrics if applicable
+    if vehicle_type != "generic":
+        vehicle_count = sum(
+            1 for v in METRIC_DEFINITIONS.values() if v.get("category") == vehicle_type
+        )
+        total = common_count + vehicle_count
+        _LOGGER.debug(
+            "Expected metrics for %s: %d common + %d vehicle-specific = %d total",
+            vehicle_type,
+            common_count,
+            vehicle_count,
+            total,
+        )
+        return total
+
+    _LOGGER.debug("Expected metrics for generic vehicle: %d common", common_count)
+    return common_count
+
+
+def calculate_discovery_percentage(
+    metric_count: int, expected_count: int
+) -> tuple[int, str]:
+    """Calculate discovery percentage and quality indicator.
+
+    Args:
+        metric_count: Number of metrics actually discovered
+        expected_count: Expected number of metrics for this vehicle type
+
+    Returns:
+        Tuple of (percentage, quality_indicator)
+        Quality indicator is emoji: ✅ (>=70%), ⚠️ (>=30%), ❌ (<30%)
+    """
+    if expected_count <= 0:
+        return 0, "❌"
+
+    percentage = min(100, int((metric_count / expected_count) * 100))
+
+    if percentage >= 70:
+        quality = "✅"
+    elif percentage >= 30:
+        quality = "⚠️"
+    else:
+        quality = "❌"
+
+    return percentage, quality
+
+
 def format_structure_prefix(config):
     """Format the topic structure prefix based on configuration."""
     try:
@@ -380,13 +499,25 @@ def count_metric_topics(topics):
         # Count only metric topics, not /client/ echoes (Issue 1 fix)
         metric_topics_before = count_metric_topics(discovered_topics)
 
-        # Check if retained messages already gave us enough metrics
+        # Get expected metrics for percentage calculation
+        # We detect vehicle type early to calculate thresholds
+        vehicle_type_early, _ = detect_vehicle_type(discovered_topics)
+        expected_count_early = get_expected_metric_count(vehicle_type_early)
+        retained_percentage = (
+            int((metric_topics_before / expected_count_early) * 100)
+            if expected_count_early > 0
+            else 0
+        )
+
+        # Check if retained messages already gave us enough metrics (percentage-based)
         # This happens when broker has retained messages from a running OVMS module
-        if metric_topics_before >= GOOD_DISCOVERY_TOPICS:
+        if retained_percentage >= GOOD_DISCOVERY_PERCENT:
             _LOGGER.info(
-                "%s - Already received %d metric topics from retained messages, skipping active discovery",
+                "%s - Already received %d metric topics (%d%%) from retained messages, "
+                "skipping active discovery",
                 log_prefix,
                 metric_topics_before,
+                retained_percentage,
             )
             active_discovery_succeeded = True
             debug_info["discovery_method"] = "retained"
@@ -501,59 +632,65 @@ def count_metric_topics(topics):
         except Exception as ex:  # pylint: disable=broad-except
             _LOGGER.debug("%s - Error disconnecting: %s", log_prefix, ex)
 
-        # Return the results with quality assessment (Issue 2 & 3 fix)
+        # Process discovery results
         topics_count = len(discovered_topics)
         metric_topics = [t for t in discovered_topics if "/metric/" in t]
         metric_count = len(metric_topics)
 
-        # Determine discovery quality for user feedback
-        if metric_count >= EXCELLENT_DISCOVERY_TOPICS:
-            discovery_quality = "excellent"
-        elif metric_count >= GOOD_DISCOVERY_TOPICS:
-            discovery_quality = "good"
-        elif metric_count >= MINIMUM_DISCOVERY_TOPICS:
-            discovery_quality = "partial"
-        elif metric_count > 0:
-            discovery_quality = "minimal"
-        else:
-            discovery_quality = "none"
+        # Detect vehicle type and calculate expected metrics
+        vehicle_type, vehicle_name = detect_vehicle_type(discovered_topics)
+        expected_count = get_expected_metric_count(vehicle_type)
+        discovery_percentage, quality_indicator = calculate_discovery_percentage(
+            metric_count, expected_count
+        )
 
         debug_info["topics_count"] = topics_count
         debug_info["metric_count"] = metric_count
-        debug_info["discovery_quality"] = discovery_quality
+        debug_info["vehicle_type"] = vehicle_type
+        debug_info["vehicle_name"] = vehicle_name
+        debug_info["expected_count"] = expected_count
+        debug_info["discovery_percentage"] = discovery_percentage
         debug_info["discovered_topics"] = (
             list(discovered_topics)
             if len(discovered_topics) < 50
             else list(discovered_topics)[:50]
         )
 
         _LOGGER.debug(
-            "%s - Discovery complete. Found %d topics (%d metric topics, quality: %s): %s",
+            "%s - Discovery complete. Found %d topics (%d metric topics). "
+            "Vehicle: %s. Coverage: %d%% (%d/%d expected)",
             log_prefix,
             topics_count,
             metric_count,
-            discovery_quality,
-            list(metric_topics)[:10],
+            vehicle_name,
+            discovery_percentage,
+            metric_count,
+            expected_count,
         )
 
-        # Add warning if few metric topics found
+        # Build result
         result = {
             "success": True,
             "discovered_topics": discovered_topics,
             "topic_count": topics_count,
             "metric_count": metric_count,
-            "discovery_quality": discovery_quality,
+            "vehicle_type": vehicle_type,
+            "vehicle_name": vehicle_name,
+            "expected_count": expected_count,
+            "discovery_percentage": discovery_percentage,
+            "quality_indicator": quality_indicator,
             "debug_info": debug_info,
         }
 
-        if metric_count < MINIMUM_DISCOVERY_TOPICS:
+        if discovery_percentage < MINIMUM_DISCOVERY_PERCENT:
             result["warning"] = "few_topics"
             _LOGGER.warning(
-                "%s - Only %d metric topics found (minimum recommended: %d). "
+                "%s - Only %d metric topics found (%d%%, minimum recommended: %d%%). "
                 "Check that your OVMS module is online and publishing metrics.",
                 log_prefix,
                 metric_count,
-                MINIMUM_DISCOVERY_TOPICS,
+                discovery_percentage,
+                MINIMUM_DISCOVERY_PERCENT,
             )
 
         return result

custom_components/ovms/const.py

@@ -172,11 +172,15 @@
 ACTIVE_DISCOVERY_TIMEOUT = 10  # seconds to wait after requesting metrics
 LEGACY_DISCOVERY_TIMEOUT = 60  # fallback timeout for older firmware
 
-# Discovery quality thresholds
-# Minimum metric topics needed for a "good" discovery (excludes /client/ topics)
-MINIMUM_DISCOVERY_TOPICS = 10  # Below this, show warning to user
-GOOD_DISCOVERY_TOPICS = 50  # Considered a good discovery
-EXCELLENT_DISCOVERY_TOPICS = 100  # Excellent discovery with most metrics
+# Discovery thresholds (percentage-based)
+# These are percentages of expected metrics for the detected vehicle type
+MINIMUM_DISCOVERY_PERCENT = 5  # Below this, show warning to user
+# Threshold for skipping active discovery when enough retained messages exist
+GOOD_DISCOVERY_PERCENT = 25  # Skip active discovery if this percentage already found
+
+# Generic vehicle fallback (vehicle-specific values are in metrics/vehicles/)
+GENERIC_VEHICLE_TYPE = "generic"
+GENERIC_VEHICLE_NAME = "Generic OVMS"
 
 # Logger
 LOGGER_NAME = "custom_components.ovms"