feat(sensors): expose Spoolman extra-field metadata on HA sensors

Fetches /api/v1/field/spool from Spoolman and uses the reported
field_type and unit to set device_class, state_class, native unit
and a sensible icon on dynamic SpoolExtraField sensors. Numeric
fields become MEASUREMENT, datetime fields TIMESTAMP, and units
like %, degC/degF, g/kg, mm/m map to the matching HA device class.

The metadata is matched on unit/field_type instead of the user-chosen
field name, so it works regardless of locale. The shape of
spool['extra'][key] is unchanged (still the raw value), so existing
templates and automations are not broken.

Closes #837 (rework)

Author: Disane87

custom_components/spoolman/classes/spoolman_api.py

@@ -59,6 +59,31 @@ async def backup(self):
             _LOGGER.debug("SpoolmanAPI: backup response %s", response)
             return response
 
+    async def get_extra_fields(self, entity_type):
+        """Return extra-field metadata for the given entity type (e.g. ``spool``).
+
+        Returns a dict keyed by field key with ``name``, ``field_type``, ``unit``,
+        ``choices`` and ``multi_choice`` so the integration can set proper HA
+        device classes / units / state classes on dynamic extra-field sensors.
+        """
+        _LOGGER.debug("SpoolmanAPI: get_extra_fields(%s)", entity_type)
+        url = f"{self.base_url}/field/{entity_type}"
+        session = await self._get_session()
+        async with session.get(url) as response:
+            response.raise_for_status()
+            payload = await response.json()
+            _LOGGER.debug("SpoolmanAPI: get_extra_fields response %s", payload)
+            return {
+                item["key"]: {
+                    "name": item.get("name"),
+                    "field_type": item.get("field_type"),
+                    "unit": item.get("unit"),
+                    "choices": item.get("choices"),
+                    "multi_choice": item.get("multi_choice"),
+                }
+                for item in payload
+            }
+
     async def get_spools(self, params):
         """Return a list of all spools."""
         _LOGGER.debug("SpoolmanAPI: get_spools")

custom_components/spoolman/coordinator.py

@@ -58,6 +58,12 @@ async def _async_update_data(self):
                 {"allow_archived": show_archived}
             )
             filaments = await self.spoolman_api.get_filaments({})
+            try:
+                spool_extra_fields = await self.spoolman_api.get_extra_fields("spool")
+            except Exception as exception:
+                # Older Spoolman versions or transient errors: degrade gracefully.
+                _LOGGER.debug("Could not fetch spool extra-field metadata: %s", exception)
+                spool_extra_fields = {}
         except asyncio.CancelledError:
             # Task was cancelled (e.g., during shutdown), re-raise to let coordinator handle it
             _LOGGER.debug("Data update was cancelled")
@@ -97,7 +103,11 @@ async def _async_update_data(self):
             _LOGGER.error(f"Error processing Klipper API data: {exception}")
             # Continue returning spools even if Klipper processing fails
 
-        return {"spools": spools, "filaments": filaments}
+        return {
+            "spools": spools,
+            "filaments": filaments,
+            "extra_fields": {"spool": spool_extra_fields},
+        }
 
     async def async_cleanup_extra_fields(self):
         """Cleanup orphaned extra field entities - can be called externally."""

custom_components/spoolman/sensors/spool_extra_field.py

@@ -5,7 +5,11 @@
 import logging
 from typing import Any
 
-from homeassistant.components.sensor import SensorEntity
+from homeassistant.components.sensor import (
+    SensorDeviceClass,
+    SensorEntity,
+    SensorStateClass,
+)
 from homeassistant.core import callback
 from homeassistant.helpers.device_registry import DeviceInfo
 from homeassistant.helpers.entity import generate_entity_id
@@ -15,6 +19,33 @@
 
 _LOGGER = logging.getLogger(__name__)
 
+_NUMERIC_FIELD_TYPES = {"integer", "float"}
+
+# Map normalized Spoolman unit strings to (device_class, icon).
+# Matched on the unit reported by Spoolman, not on the user-chosen field name,
+# so it works regardless of locale.
+_UNIT_DEVICE_CLASS = {
+    "%": (SensorDeviceClass.HUMIDITY, "mdi:water-percent"),
+    "°c": (SensorDeviceClass.TEMPERATURE, "mdi:thermometer"),
+    "°f": (SensorDeviceClass.TEMPERATURE, "mdi:thermometer"),
+    "k": (SensorDeviceClass.TEMPERATURE, "mdi:thermometer"),
+    "g": (SensorDeviceClass.WEIGHT, "mdi:weight-gram"),
+    "kg": (SensorDeviceClass.WEIGHT, "mdi:weight-kilogram"),
+    "mm": (SensorDeviceClass.DISTANCE, "mdi:ruler"),
+    "m": (SensorDeviceClass.DISTANCE, "mdi:ruler"),
+}
+
+
+def _device_class_for(field_type: str | None, unit: str | None) -> tuple[Any, str]:
+    """Pick a device class + icon based on Spoolman field metadata."""
+    if field_type == "datetime":
+        return SensorDeviceClass.TIMESTAMP, "mdi:calendar"
+    if unit:
+        match = _UNIT_DEVICE_CLASS.get(unit.strip().lower())
+        if match:
+            return match
+    return None, "mdi:tag-outline"
+
 
 class SpoolExtraField(CoordinatorEntity, SensorEntity):
     """Sensor for spool extra field - dynamically created for each extra field."""
@@ -42,6 +73,19 @@ def __init__(
         else:
             spool_name = f"Spoolman Spool {self._spool['id']}"
 
+        # Pull metadata reported by Spoolman (`/api/v1/field/spool`) so we can
+        # set proper device class / unit / state class. Falls back to a derived
+        # display name and a plain icon when metadata isn't available.
+        field_meta = (
+            (coordinator.data or {})
+            .get("extra_fields", {})
+            .get("spool", {})
+            .get(field_key, {})
+        )
+        display_name = field_meta.get("name") or field_key.replace("_", " ").title()
+        field_type = field_meta.get("field_type")
+        unit = field_meta.get("unit")
+
         # Create entity ID with the field key
         # e.g., sensor.spoolman_spool_1_extra_humidity
         safe_field_key = field_key.lower().replace(" ", "_").replace("-", "_")
@@ -52,8 +96,19 @@ def __init__(
         )
         self._attr_unique_id = f"spoolman_{self._entry.entry_id}_spool_{spool_data['id']}_extra_{safe_field_key}"
         self._attr_has_entity_name = False
-        self._attr_name = f"{spool_name} Extra {field_key.replace('_', ' ').title()}"
-        self._attr_icon = "mdi:tag-outline"
+        self._attr_name = f"{spool_name} Extra {display_name}"
+
+        device_class, icon = _device_class_for(field_type, unit)
+        if device_class is not None:
+            self._attr_device_class = device_class
+        self._attr_icon = icon
+
+        if field_type in _NUMERIC_FIELD_TYPES:
+            self._attr_state_class = SensorStateClass.MEASUREMENT
+
+        if unit:
+            self._attr_native_unit_of_measurement = unit
+
         self._attr_device_info = DeviceInfo(
             identifiers={(DOMAIN, self.config[CONF_URL], f"spool_{self._spool['id']}")}  # type: ignore[arg-type]
         )
@@ -91,6 +146,7 @@ def state(self) -> Any:
         # Convert value to string if it's a complex type
         if isinstance(value, dict | list):
             import json
+
             return json.dumps(value)
 
         return value