[mqtt.homeassistant] document which channels a component might have (o…

…penhab#17618) * [mqtt.homeassistant] document which channels a component might have Signed-off-by: Cody Cutrer <[email protected]>
KaaNee · Nov 8, 2024 · f9548d1 · f9548d1
1 parent b6a5abe
commit f9548d1
Show file tree

Hide file tree

Showing 21 changed files with 263 additions and 206 deletions.
diff --git a/bundles/org.openhab.binding.mqtt.homeassistant/README.md b/bundles/org.openhab.binding.mqtt.homeassistant/README.md
diff --git a/...ain/java/org/openhab/binding/mqtt/homeassistant/internal/component/AbstractComponent.java b/...ain/java/org/openhab/binding/mqtt/homeassistant/internal/component/AbstractComponent.java
@@ -27,6 +27,7 @@
 import org.openhab.binding.mqtt.generic.ChannelState;
 import org.openhab.binding.mqtt.generic.ChannelStateUpdateListener;
 import org.openhab.binding.mqtt.generic.MqttChannelStateDescriptionProvider;
+import org.openhab.binding.mqtt.generic.values.TextValue;
 import org.openhab.binding.mqtt.generic.values.Value;
 import org.openhab.binding.mqtt.homeassistant.generic.internal.MqttBindingConstants;
 import org.openhab.binding.mqtt.homeassistant.internal.ComponentChannel;
@@ -42,6 +43,7 @@
 import org.openhab.core.thing.Channel;
 import org.openhab.core.thing.ChannelUID;
 import org.openhab.core.thing.binding.generic.ChannelTransformation;
+import org.openhab.core.thing.type.AutoUpdatePolicy;
 import org.openhab.core.thing.type.ChannelDefinition;
 import org.openhab.core.thing.type.ChannelGroupDefinition;
 import org.openhab.core.thing.type.ChannelGroupType;
@@ -62,6 +64,7 @@
  */
 @NonNullByDefault
 public abstract class AbstractComponent<C extends AbstractChannelConfiguration> {
+    public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
 
     // Component location fields
     protected final ComponentConfiguration componentConfiguration;
@@ -152,7 +155,18 @@ public AbstractComponent(ComponentFactory.ComponentConfiguration componentConfig
         }
     }
 
+    protected void addJsonAttributesChannel() {
+        if (channelConfiguration.getJsonAttributesTopic() != null) {
+            buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
+                    componentConfiguration.getUpdateListener())
+                    .stateTopic(channelConfiguration.getJsonAttributesTopic(),
+                            channelConfiguration.getJsonAttributesTemplate())
+                    .withAutoUpdatePolicy(AutoUpdatePolicy.VETO).isAdvanced(true).build();
+        }
+    }
+
     protected void finalizeChannels() {
+        addJsonAttributesChannel();
         if (!newStyleChannels) {
             return;
         }

diff --git a/...src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/BinarySensor.java b/...src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/BinarySensor.java
@@ -16,7 +16,6 @@
 import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.binding.mqtt.generic.ChannelStateUpdateListener;
 import org.openhab.binding.mqtt.generic.values.OnOffValue;
-import org.openhab.binding.mqtt.generic.values.TextValue;
 import org.openhab.binding.mqtt.generic.values.Value;
 import org.openhab.binding.mqtt.homeassistant.internal.ComponentChannelType;
 import org.openhab.binding.mqtt.homeassistant.internal.config.dto.AbstractChannelConfiguration;
@@ -34,7 +33,6 @@
 @NonNullByDefault
 public class BinarySensor extends AbstractComponent<BinarySensor.ChannelConfiguration> {
     public static final String SENSOR_CHANNEL_ID = "sensor";
-    public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
 
     /**
      * Configuration class for MQTT component
@@ -59,11 +57,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
         protected String payloadOn = "ON";
         @SerializedName("payload_off")
         protected String payloadOff = "OFF";
-
-        @SerializedName("json_attributes_topic")
-        protected @Nullable String jsonAttributesTopic;
-        @SerializedName("json_attributes_template")
-        protected @Nullable String jsonAttributesTemplate;
     }
 
     public BinarySensor(ComponentFactory.ComponentConfiguration componentConfiguration, boolean newStyleChannels) {
@@ -76,13 +69,6 @@ public BinarySensor(ComponentFactory.ComponentConfiguration componentConfigurati
                 .stateTopic(channelConfiguration.stateTopic, channelConfiguration.getValueTemplate())
                 .withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
 
-        if (channelConfiguration.jsonAttributesTopic != null) {
-            buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
-                    componentConfiguration.getUpdateListener())
-                    .stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
-                    .withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
-        }
-
         finalizeChannels();
     }
 

diff --git a/...stant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Camera.java b/...stant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Camera.java
@@ -13,14 +13,9 @@
 package org.openhab.binding.mqtt.homeassistant.internal.component;
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
-import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.binding.mqtt.generic.values.ImageValue;
-import org.openhab.binding.mqtt.generic.values.TextValue;
 import org.openhab.binding.mqtt.homeassistant.internal.ComponentChannelType;
 import org.openhab.binding.mqtt.homeassistant.internal.config.dto.AbstractChannelConfiguration;
-import org.openhab.core.thing.type.AutoUpdatePolicy;
-
-import com.google.gson.annotations.SerializedName;
 
 /**
  * A MQTT camera, following the https://www.home-assistant.io/components/camera.mqtt/ specification.
@@ -32,7 +27,6 @@
 @NonNullByDefault
 public class Camera extends AbstractComponent<Camera.ChannelConfiguration> {
     public static final String CAMERA_CHANNEL_ID = "camera";
-    public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
 
     /**
      * Configuration class for MQTT component
@@ -43,11 +37,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
         }
 
         protected String topic = "";
-
-        @SerializedName("json_attributes_template")
-        protected @Nullable String jsonAttributesTemplate;
-        @SerializedName("json_attributes_topic")
-        protected @Nullable String jsonAttributesTopic;
     }
 
     public Camera(ComponentFactory.ComponentConfiguration componentConfiguration, boolean newStyleChannels) {
@@ -58,13 +47,6 @@ public Camera(ComponentFactory.ComponentConfiguration componentConfiguration, bo
         buildChannel(CAMERA_CHANNEL_ID, ComponentChannelType.IMAGE, value, getName(),
                 componentConfiguration.getUpdateListener()).stateTopic(channelConfiguration.topic).build();
 
-        if (channelConfiguration.jsonAttributesTopic != null) {
-            buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
-                    componentConfiguration.getUpdateListener())
-                    .stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
-                    .withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
-        }
-
         finalizeChannels();
     }
 }
diff --git a/...tant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Climate.java b/...tant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Climate.java
@@ -33,7 +33,6 @@
 import org.openhab.core.library.types.StringType;
 import org.openhab.core.library.unit.ImperialUnits;
 import org.openhab.core.library.unit.SIUnits;
-import org.openhab.core.thing.type.AutoUpdatePolicy;
 import org.openhab.core.types.Command;
 import org.openhab.core.types.State;
 
@@ -64,7 +63,6 @@ public class Climate extends AbstractComponent<Climate.ChannelConfiguration> {
     public static final String TEMPERATURE_LOW_CH_ID = "temperature-low";
     public static final String TEMPERATURE_LOW_CH_ID_DEPRECATED = "temperatureLow";
     public static final String POWER_CH_ID = "power";
-    public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
 
     public enum TemperatureUnit {
         @SerializedName("C")
@@ -150,11 +148,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
         protected @Nullable List<String> holdModes; // Are there default modes? Now the channel will be ignored without
                                                     // hold modes.
 
-        @SerializedName("json_attributes_template")
-        protected @Nullable String jsonAttributesTemplate;
-        @SerializedName("json_attributes_topic")
-        protected @Nullable String jsonAttributesTopic;
-
         @SerializedName("mode_command_template")
         protected @Nullable String modeCommandTemplate;
         @SerializedName("mode_command_topic")
@@ -298,12 +291,6 @@ ComponentChannelType.SWITCH, new OnOffValue(), updateListener, null,
         buildOptionalChannel(POWER_CH_ID, ComponentChannelType.SWITCH, new OnOffValue(), updateListener, null,
                 channelConfiguration.powerCommandTopic, null, null, null);
 
-        if (channelConfiguration.jsonAttributesTopic != null) {
-            buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
-                    componentConfiguration.getUpdateListener())
-                    .stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
-                    .withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
-        }
         finalizeChannels();
     }
 

diff --git a/...istant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Cover.java b/...istant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Cover.java
@@ -40,7 +40,6 @@
 public class Cover extends AbstractComponent<Cover.ChannelConfiguration> {
     public static final String COVER_CHANNEL_ID = "cover";
     public static final String STATE_CHANNEL_ID = "state";
-    public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
 
     /**
      * Configuration class for MQTT component
@@ -84,11 +83,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
         protected String stateOpening = "opening";
         @SerializedName("state_stopped")
         protected String stateStopped = "stopped";
-
-        @SerializedName("json_attributes_template")
-        protected @Nullable String jsonAttributesTemplate;
-        @SerializedName("json_attributes_topic")
-        protected @Nullable String jsonAttributesTopic;
     }
 
     @Nullable
@@ -166,12 +160,6 @@ public Cover(ComponentFactory.ComponentConfiguration componentConfiguration, boo
                     return true;
                 }).withAutoUpdatePolicy(optimistic ? AutoUpdatePolicy.RECOMMEND : null).build();
 
-        if (channelConfiguration.jsonAttributesTopic != null) {
-            buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
-                    componentConfiguration.getUpdateListener())
-                    .stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
-                    .withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
-        }
         finalizeChannels();
     }
 }
diff --git a/...istant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Event.java b/...istant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Event.java
@@ -16,7 +16,6 @@
 import java.util.List;
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
-import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.binding.mqtt.generic.ChannelStateUpdateListener;
 import org.openhab.binding.mqtt.generic.values.TextValue;
 import org.openhab.binding.mqtt.homeassistant.internal.ComponentChannelType;
@@ -36,7 +35,6 @@
 @NonNullByDefault
 public class Event extends AbstractComponent<Event.ChannelConfiguration> implements ChannelStateUpdateListener {
     public static final String EVENT_TYPE_CHANNEL_ID = "event-type";
-    public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
     private static final String EVENT_TYPE_TRANFORMATION = "{{ value_json.event_type }}";
 
     /**
@@ -52,12 +50,6 @@ public static class ChannelConfiguration extends AbstractChannelConfiguration {
 
         @SerializedName("event_types")
         protected List<String> eventTypes = new ArrayList();
-
-        @SerializedName("json_attributes_topic")
-        protected @Nullable String jsonAttributesTopic;
-
-        @SerializedName("json_attributes_template")
-        protected @Nullable String jsonAttributesTemplate;
     }
 
     private final HomeAssistantChannelTransformation transformation;
@@ -71,7 +63,13 @@ public Event(ComponentFactory.ComponentConfiguration componentConfiguration, boo
                 .stateTopic(channelConfiguration.stateTopic, channelConfiguration.getValueTemplate()).trigger(true)
                 .build();
 
-        if (channelConfiguration.jsonAttributesTopic != null) {
+        finalizeChannels();
+    }
+
+    // Overridden to use create it as a trigger channel
+    @Override
+    protected void addJsonAttributesChannel() {
+        if (channelConfiguration.getJsonAttributesTopic() != null) {
             // It's unclear from the documentation if the JSON attributes value is expected
             // to be the same as the main topic, and thus would always have an event_type
             // attribute (and thus could possibly be shared with multiple components).
@@ -81,11 +79,10 @@ public Event(ComponentFactory.ComponentConfiguration componentConfiguration, boo
             // the filtering below.
             buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.TRIGGER, new TextValue(), getName(),
                     componentConfiguration.getUpdateListener())
-                    .stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
-                    .trigger(true).build();
+                    .stateTopic(channelConfiguration.getJsonAttributesTopic(),
+                            channelConfiguration.getJsonAttributesTemplate())
+                    .isAdvanced(true).trigger(true).build();
         }
-
-        finalizeChannels();
     }
 
     @Override

diff --git a/...ssistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Fan.java b/...ssistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Fan.java
@@ -28,7 +28,6 @@
 import org.openhab.core.library.types.OnOffType;
 import org.openhab.core.library.types.PercentType;
 import org.openhab.core.thing.ChannelUID;
-import org.openhab.core.thing.type.AutoUpdatePolicy;
 import org.openhab.core.types.Command;
 import org.openhab.core.types.State;
 import org.openhab.core.types.UnDefType;
@@ -44,12 +43,12 @@
  */
 @NonNullByDefault
 public class Fan extends AbstractComponent<Fan.ChannelConfiguration> implements ChannelStateUpdateListener {
-    public static final String SWITCH_CHANNEL_ID = "fan";
+    public static final String SWITCH_CHANNEL_ID = "switch";
+    public static final String SWITCH_CHANNEL_ID_DEPRECATED = "fan";
     public static final String SPEED_CHANNEL_ID = "speed";
     public static final String PRESET_MODE_CHANNEL_ID = "preset-mode";
     public static final String OSCILLATION_CHANNEL_ID = "oscillation";
     public static final String DIRECTION_CHANNEL_ID = "direction";
-    public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
 
     /**
      * Configuration class for MQTT component
@@ -117,10 +116,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
         protected int speedRangeMax = 100;
         @SerializedName("speed_range_min")
         protected int speedRangeMin = 1;
-        @SerializedName("json_attributes_template")
-        protected @Nullable String jsonAttributesTemplate;
-        @SerializedName("json_attributes_topic")
-        protected @Nullable String jsonAttributesTopic;
     }
 
     private final OnOffValue onOffValue;
@@ -139,8 +134,8 @@ public Fan(ComponentFactory.ComponentConfiguration componentConfiguration, boole
         ChannelStateUpdateListener onOffListener = channelConfiguration.percentageCommandTopic == null
                 ? componentConfiguration.getUpdateListener()
                 : this;
-        onOffChannel = buildChannel(SWITCH_CHANNEL_ID, ComponentChannelType.SWITCH, onOffValue, "On/Off State",
-                onOffListener)
+        onOffChannel = buildChannel(newStyleChannels ? SWITCH_CHANNEL_ID : SWITCH_CHANNEL_ID_DEPRECATED,
+                ComponentChannelType.SWITCH, onOffValue, "On/Off State", onOffListener)
                 .stateTopic(channelConfiguration.stateTopic, channelConfiguration.getValueTemplate())
                 .commandTopic(channelConfiguration.commandTopic, channelConfiguration.isRetain(),
                         channelConfiguration.getQos(), channelConfiguration.commandTemplate)
@@ -202,13 +197,6 @@ public Fan(ComponentFactory.ComponentConfiguration componentConfiguration, boole
                     .inferOptimistic(channelConfiguration.optimistic).build();
         }
 
-        if (channelConfiguration.jsonAttributesTopic != null) {
-            buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
-                    componentConfiguration.getUpdateListener())
-                    .stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
-                    .withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
-        }
-
         finalizeChannels();
     }
 

diff --git a/...sistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Lock.java b/...sistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Lock.java
@@ -36,7 +36,6 @@
 public class Lock extends AbstractComponent<Lock.ChannelConfiguration> {
     public static final String LOCK_CHANNEL_ID = "lock";
     public static final String STATE_CHANNEL_ID = "state";
-    public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
 
     /**
      * Configuration class for MQTT component
@@ -68,11 +67,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
         protected String stateUnlocked = "UNLOCKED";
         @SerializedName("state_unlocking")
         protected String stateUnlocking = "UNLOCKING";
-
-        @SerializedName("json_attributes_template")
-        protected @Nullable String jsonAttributesTemplate;
-        @SerializedName("json_attributes_topic")
-        protected @Nullable String jsonAttributesTopic;
     }
 
     private boolean optimistic = false;
@@ -128,13 +122,6 @@ public Lock(ComponentFactory.ComponentConfiguration componentConfiguration, bool
                     return true;
                 }).build();
 
-        if (channelConfiguration.jsonAttributesTopic != null) {
-            buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
-                    componentConfiguration.getUpdateListener())
-                    .stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
-                    .withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
-        }
-
         finalizeChannels();
     }