[homeassistant] Support device-level configuration (#20225)

* [homeassistant] Support device-level configuration

Signed-off-by: Cody Cutrer <cody@cutrer.us>

Author: ccutrer

bundles/org.openhab.binding.homeassistant/README.md

@@ -8,6 +8,26 @@ Each component will be represented as a Channel Group, with the attributes of th
 
 Any device that publishes the component configuration under the `homeassistant` prefix in MQTT will have their components automatically discovered and added to the Inbox.
 You can also manually create a Thing, and provide the individual component topics, as well as a different discovery prefix.
+[Device Discovery](https://www.home-assistant.io/integrations/mqtt/#device-discovery-payload) is supported as well.
+
+## Example
+
+### Things file
+
+```java
+Bridge mqtt:broker:mybroker [ host="192.168.1.10", secure=false ] {
+	// 1) Single component configuration; channels won't be created until config is received from the MQTT broker
+	Thing homeassistant:device:kitchen_button [ topics="button/kitchen_button/restart" ]
+
+	// 2) Device-level configuration topic; channels won't be created until config is received from the MQTT broker
+	Thing homeassistant:device:kitchen_device [ topics="device/kitchen" ]
+
+	// 3) Device-level configuration with full JSON in deviceConfig
+	// Channels are restored from deviceConfig immediately, so the Thing is usable
+	// even before the retained MQTT discovery message is received from the broker.
+	Thing homeassistant:device:kitchen_cached [ topics="device/kitchen", deviceConfig="{\"dev\":{\"ids\":\"ea334450945afc\",\"name\":\"Kitchen\"},\"o\":{\"name\":\"bla2mqtt\",\"sw\":\"2.1\"},\"cmps\":{\"temperature\":{\"p\":\"sensor\",\"device_class\":\"temperature\",\"unit_of_measurement\":\"°C\",\"value_template\":\"{{ value_json.temperature}}\",\"unique_id\":\"temp01ae_t\"},\"humidity\":{\"p\":\"sensor\",\"device_class\":\"humidity\",\"unit_of_measurement\":\"%\",\"value_template\":\"{{ value_json.humidity}}\",\"unique_id\":\"temp01ae_h\"}},\"state_topic\":\"sensorKitchen/state\",\"qos\":2}" ]
+}
+```
 
 ## Supported Components and Channels
 

bundles/org.openhab.binding.homeassistant/src/main/java/org/openhab/binding/homeassistant/internal/DiscoverComponents.java

@@ -14,6 +14,7 @@
 
 import java.lang.ref.WeakReference;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ScheduledExecutorService;
@@ -25,6 +26,7 @@
 import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.binding.homeassistant.internal.component.AbstractComponent;
 import org.openhab.binding.homeassistant.internal.component.ComponentFactory;
+import org.openhab.binding.homeassistant.internal.config.dto.MqttComponentConfig;
 import org.openhab.binding.homeassistant.internal.exception.ConfigurationException;
 import org.openhab.binding.homeassistant.internal.exception.UnsupportedComponentException;
 import org.openhab.binding.mqtt.generic.AvailabilityTracker;
@@ -64,6 +66,7 @@ public class DiscoverComponents implements MqttMessageSubscriber {
     protected @Nullable ComponentDiscovered discoveredListener;
     private int discoverTime;
     private Set<String> topics = new HashSet<>();
+    private final Set<HaID> knownDeviceComponents = new HashSet<>();
 
     /**
      * Implement this to get notified of new components
@@ -72,6 +75,8 @@ public static interface ComponentDiscovered {
         void componentDiscovered(HaID homeAssistantTopicID, AbstractComponent<?> component);
 
         void componentRemoved(HaID homeAssistantTopicID);
+
+        void deviceConfigUpdated(HaID homeAssistantTopicID, String configPayload);
     }
 
     /**
@@ -95,35 +100,70 @@ public DiscoverComponents(ThingUID thingUID, ScheduledExecutorService scheduler,
     }
 
     @Override
-    public void processMessage(String topic, byte[] payload) {
+    public synchronized void processMessage(String topic, byte[] payload) {
         if (!topic.endsWith("/config")) {
             return;
         }
 
         HaID haID = new HaID(topic);
         String config = new String(payload);
-        AbstractComponent<?> component = null;
         ComponentDiscovered discoveredListener = this.discoveredListener;
-
         if (config.length() > 0) {
             try {
-                component = ComponentFactory.createComponent(thingUID, haID, config, updateListener, linkageChecker,
-                        tracker, scheduler, gson, python, unitProvider);
-                component.setConfigSeen();
+                List<MqttComponentConfig> parsedComponentConfigs = python.processDiscoveryConfig(haID.toShortTopic(),
+                        config);
+                boolean migrationMessage = parsedComponentConfigs.stream()
+                        .anyMatch(MqttComponentConfig::isMigrateDiscovery);
+                if (migrationMessage) {
+                    // Just treat a migration message as the component disappearing -
+                    // openHAB doesn't destroy Items when a Channel disappears, so we
+                    // don't need to worry about keeping a sentinel around for components
+                    // that are about to show up again under a device component.
+                    if (HomeAssistantBindingConstants.DEVICE_COMPONENT.equals(haID.component)) {
+                        if (discoveredListener != null) {
+                            knownDeviceComponents.forEach(discoveredListener::componentRemoved);
+                        }
+                        knownDeviceComponents.clear();
+                    } else if (discoveredListener != null) {
+                        discoveredListener.componentRemoved(haID);
+                    }
+                    return;
+                }
 
-                logger.trace("Found HomeAssistant component {}", haID);
+                List<AbstractComponent<?>> components = ComponentFactory.createComponent(thingUID, haID, config,
+                        parsedComponentConfigs, updateListener, linkageChecker, tracker, scheduler, gson, python,
+                        unitProvider);
+                components.forEach(component -> component.setConfigSeen());
+
+                logger.trace("Found Home Assistant component {}", haID);
 
                 if (discoveredListener != null) {
-                    discoveredListener.componentDiscovered(haID, component);
+                    if (HomeAssistantBindingConstants.DEVICE_COMPONENT.equals(haID.component)) {
+                        discoveredListener.deviceConfigUpdated(haID, config);
+                        Set<HaID> currentComponents = components.stream().map(AbstractComponent::getHaID)
+                                .collect(Collectors.toSet());
+                        knownDeviceComponents.stream().filter(component -> !currentComponents.contains(component))
+                                .forEach(discoveredListener::componentRemoved);
+                        components.stream().filter(component -> !knownDeviceComponents.contains(component.getHaID()))
+                                .forEach(component -> discoveredListener.componentDiscovered(component.getHaID(),
+                                        component));
+                        knownDeviceComponents.clear();
+                        knownDeviceComponents.addAll(currentComponents);
+                    } else {
+                        components.forEach(component -> discoveredListener.componentDiscovered(haID, component));
+                    }
                 }
             } catch (UnsupportedComponentException e) {
-                logger.warn("HomeAssistant discover error: thing {} component type is unsupported: {}", haID.objectID,
-                        haID.component);
+                logger.warn("Home Assistant discovery error: component {} is unsupported", haID.toShortTopic());
             } catch (ConfigurationException e) {
-                logger.warn("HomeAssistant discover error: invalid configuration of thing {} component {}: {}",
-                        haID.objectID, haID.component, e.getMessage());
+                logger.warn("Home Assistant discovery error: invalid configuration of component {}: {}",
+                        haID.toShortTopic(), e.getMessage());
             }
         } else if (discoveredListener != null) {
+            if (HomeAssistantBindingConstants.DEVICE_COMPONENT.equals(haID.component)) {
+                knownDeviceComponents.forEach(discoveredListener::componentRemoved);
+                knownDeviceComponents.clear();
+            }
             discoveredListener.componentRemoved(haID);
         }
     }
@@ -176,13 +216,14 @@ private void subscribeSuccess() {
         }
     }
 
-    private @Nullable Void subscribeFail(Throwable e) {
+    private synchronized @Nullable Void subscribeFail(Throwable e) {
         final ScheduledFuture<?> scheduledFuture = this.stopDiscoveryFuture;
         if (scheduledFuture != null) { // Cancel timeout
             scheduledFuture.cancel(false);
             this.stopDiscoveryFuture = null;
         }
         this.discoveredListener = null;
+        this.knownDeviceComponents.clear();
         final MqttBrokerConnection connection = connectionRef.get();
         if (connection != null) {
             this.topics.stream().forEach(t -> connection.unsubscribe(t, this));

bundles/org.openhab.binding.homeassistant/src/main/java/org/openhab/binding/homeassistant/internal/HaID.java

@@ -81,7 +81,7 @@ public HaID() {
      * @param nodeID The node ID (can be the empty string)
      * @param component The component ID
      */
-    private HaID(String baseTopic, String objectID, String nodeID, String component) {
+    public HaID(String baseTopic, String objectID, String nodeID, String component) {
         this.baseTopic = baseTopic;
         this.objectID = objectID;
         this.nodeID = nodeID;

bundles/org.openhab.binding.homeassistant/src/main/java/org/openhab/binding/homeassistant/internal/HandlerConfiguration.java

@@ -28,6 +28,7 @@
 @NonNullByDefault
 public class HandlerConfiguration {
     public static final String PROPERTY_BASETOPIC = "basetopic";
+    public static final String PROPERTY_DEVICE_CONFIG = "deviceConfig";
     public static final String PROPERTY_TOPICS = "topics";
     public static final String DEFAULT_BASETOPIC = "homeassistant";
     /**
@@ -64,14 +65,20 @@ public class HandlerConfiguration {
      *
      */
     public List<String> topics;
+    public String deviceConfig = "";
 
     public HandlerConfiguration() {
-        this(DEFAULT_BASETOPIC, Collections.emptyList());
+        this(DEFAULT_BASETOPIC, Collections.emptyList(), "");
     }
 
     public HandlerConfiguration(String basetopic, List<String> topics) {
+        this(basetopic, topics, "");
+    }
+
+    public HandlerConfiguration(String basetopic, List<String> topics, String deviceConfig) {
         this.basetopic = basetopic;
         this.topics = topics;
+        this.deviceConfig = deviceConfig;
     }
 
     /**
@@ -83,6 +90,7 @@ public HandlerConfiguration(String basetopic, List<String> topics) {
     public <T extends Map<String, Object>> T appendToProperties(T properties) {
         properties.put(PROPERTY_BASETOPIC, basetopic);
         properties.put(PROPERTY_TOPICS, topics);
+        properties.put(PROPERTY_DEVICE_CONFIG, deviceConfig);
         return properties;
     }
 }

bundles/org.openhab.binding.homeassistant/src/main/java/org/openhab/binding/homeassistant/internal/HomeAssistantBindingConstants.java

@@ -27,6 +27,8 @@ public class HomeAssistantBindingConstants {
     public static final String LEGACY_BINDING_ID = "mqtt";
     public static final String BINDING_ID = "homeassistant";
 
+    public static final String DEVICE_COMPONENT = "device";
+
     // List of all Thing Type UIDs
     public static final ThingTypeUID LEGACY_MQTT_HOMEASSISTANT_THING = new ThingTypeUID(LEGACY_BINDING_ID,
             "homeassistant");

bundles/org.openhab.binding.homeassistant/src/main/java/org/openhab/binding/homeassistant/internal/HomeAssistantPythonBridge.java

@@ -29,6 +29,7 @@
 import org.graalvm.polyglot.Value;
 import org.graalvm.python.embedding.GraalPyResources;
 import org.graalvm.python.embedding.VirtualFileSystem;
+import org.openhab.binding.homeassistant.internal.config.dto.MqttComponentConfig;
 import org.openhab.binding.homeassistant.internal.exception.ConfigurationException;
 import org.openhab.core.OpenHAB;
 import org.osgi.service.component.annotations.Activate;
@@ -148,23 +149,20 @@ public String renderValueTemplate(Value template, Object payload, String default
         return renderValueTemplateWithVariablesMeth.execute(template, payload, defaultValue, variables).asString();
     }
 
-    public Map<String, @Nullable Object> processDiscoveryConfig(String component, String payload) {
+    public List<MqttComponentConfig> processDiscoveryConfig(String topic, String payload) {
         try {
             @SuppressWarnings("unchecked")
-            Map<String, @Nullable Object> config = (Map<String, @Nullable Object>) toJava(
-                    processDiscoveryConfigMeth.execute(component, payload));
-            if (config == null) {
+            List<Value> configs = (List<Value>) toJava(processDiscoveryConfigMeth.execute(topic, payload));
+            if (configs == null || configs.isEmpty()) {
                 throw new ConfigurationException("Invalid configuration");
             }
-            return config;
-
+            return configs.stream().map(c -> new MqttComponentConfig(this, c)).toList();
         } catch (PolyglotException e) {
-            throw new ConfigurationException(
-                    "Failed to process discovery config for " + component + ": " + e.getMessage());
+            throw new ConfigurationException("Failed to process discovery config for " + topic + ": " + e.getMessage());
         }
     }
 
-    private @Nullable Object toJava(Value value) {
+    public @Nullable Object toJava(Value value) {
         if (value.isNull()) {
             return null;
         }

bundles/org.openhab.binding.homeassistant/src/main/java/org/openhab/binding/homeassistant/internal/component/AbstractComponent.java

@@ -128,8 +128,7 @@ public BigDecimal getDefaultPrecision() {
      * @param singleChannelComponent if this component only ever has one channel, so should never be in a group
      */
     public AbstractComponent(ComponentFactory.ComponentContext componentContext, Class<C> clazz) {
-        this(componentContext, AbstractComponentConfiguration.create(componentContext.getPython(),
-                componentContext.getHaID().component, componentContext.getConfigJSON(), clazz));
+        this(componentContext, AbstractComponentConfiguration.create(componentContext.getDiscoveryPayload(), clazz));
     }
 
     /**
@@ -208,11 +207,13 @@ protected void finalizeChannels() {
         if (channels.size() == 1) {
             groupId = null;
             channels.values().forEach(c -> c.resetUID(buildChannelUID(componentId), getName()));
-        } else {
+        }
+
+        if (componentContext.shouldPersistChannelConfiguration()) {
             // only the first channel needs to persist the configuration
-            channels.values().stream().skip(1).forEach(c -> {
-                c.clearConfiguration();
-            });
+            channels.values().stream().skip(1).forEach(ComponentChannel::clearConfiguration);
+        } else {
+            channels.values().forEach(ComponentChannel::clearConfiguration);
         }
     }