Skip to content

Commit f52cede

Browse files
ccutrerccutrer
authoredOct 26, 2024
[mqtt.homeassistant] document which channels a component might have (openhab#17618)
* [mqtt.homeassistant] document which channels a component might have Signed-off-by: Cody Cutrer <cody@cutrer.us>
1 parent fd4284a commit f52cede

File tree

21 files changed

+263
-206
lines changed

21 files changed

+263
-206
lines changed
 

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

+176-22
Large diffs are not rendered by default.

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

+14
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
import org.openhab.binding.mqtt.generic.ChannelState;
2828
import org.openhab.binding.mqtt.generic.ChannelStateUpdateListener;
2929
import org.openhab.binding.mqtt.generic.MqttChannelStateDescriptionProvider;
30+
import org.openhab.binding.mqtt.generic.values.TextValue;
3031
import org.openhab.binding.mqtt.generic.values.Value;
3132
import org.openhab.binding.mqtt.homeassistant.generic.internal.MqttBindingConstants;
3233
import org.openhab.binding.mqtt.homeassistant.internal.ComponentChannel;
@@ -42,6 +43,7 @@
4243
import org.openhab.core.thing.Channel;
4344
import org.openhab.core.thing.ChannelUID;
4445
import org.openhab.core.thing.binding.generic.ChannelTransformation;
46+
import org.openhab.core.thing.type.AutoUpdatePolicy;
4547
import org.openhab.core.thing.type.ChannelDefinition;
4648
import org.openhab.core.thing.type.ChannelGroupDefinition;
4749
import org.openhab.core.thing.type.ChannelGroupType;
@@ -62,6 +64,7 @@
6264
*/
6365
@NonNullByDefault
6466
public abstract class AbstractComponent<C extends AbstractChannelConfiguration> {
67+
public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
6568

6669
// Component location fields
6770
protected final ComponentConfiguration componentConfiguration;
@@ -152,7 +155,18 @@ public AbstractComponent(ComponentFactory.ComponentConfiguration componentConfig
152155
}
153156
}
154157

158+
protected void addJsonAttributesChannel() {
159+
if (channelConfiguration.getJsonAttributesTopic() != null) {
160+
buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
161+
componentConfiguration.getUpdateListener())
162+
.stateTopic(channelConfiguration.getJsonAttributesTopic(),
163+
channelConfiguration.getJsonAttributesTemplate())
164+
.withAutoUpdatePolicy(AutoUpdatePolicy.VETO).isAdvanced(true).build();
165+
}
166+
}
167+
155168
protected void finalizeChannels() {
169+
addJsonAttributesChannel();
156170
if (!newStyleChannels) {
157171
return;
158172
}

‎bundles/org.openhab.binding.mqtt.homeassistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/BinarySensor.java

-14
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@
1616
import org.eclipse.jdt.annotation.Nullable;
1717
import org.openhab.binding.mqtt.generic.ChannelStateUpdateListener;
1818
import org.openhab.binding.mqtt.generic.values.OnOffValue;
19-
import org.openhab.binding.mqtt.generic.values.TextValue;
2019
import org.openhab.binding.mqtt.generic.values.Value;
2120
import org.openhab.binding.mqtt.homeassistant.internal.ComponentChannelType;
2221
import org.openhab.binding.mqtt.homeassistant.internal.config.dto.AbstractChannelConfiguration;
@@ -34,7 +33,6 @@
3433
@NonNullByDefault
3534
public class BinarySensor extends AbstractComponent<BinarySensor.ChannelConfiguration> {
3635
public static final String SENSOR_CHANNEL_ID = "sensor";
37-
public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
3836

3937
/**
4038
* Configuration class for MQTT component
@@ -59,11 +57,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
5957
protected String payloadOn = "ON";
6058
@SerializedName("payload_off")
6159
protected String payloadOff = "OFF";
62-
63-
@SerializedName("json_attributes_topic")
64-
protected @Nullable String jsonAttributesTopic;
65-
@SerializedName("json_attributes_template")
66-
protected @Nullable String jsonAttributesTemplate;
6760
}
6861

6962
public BinarySensor(ComponentFactory.ComponentConfiguration componentConfiguration, boolean newStyleChannels) {
@@ -76,13 +69,6 @@ public BinarySensor(ComponentFactory.ComponentConfiguration componentConfigurati
7669
.stateTopic(channelConfiguration.stateTopic, channelConfiguration.getValueTemplate())
7770
.withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
7871

79-
if (channelConfiguration.jsonAttributesTopic != null) {
80-
buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
81-
componentConfiguration.getUpdateListener())
82-
.stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
83-
.withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
84-
}
85-
8672
finalizeChannels();
8773
}
8874

‎bundles/org.openhab.binding.mqtt.homeassistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Camera.java

-18
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,9 @@
1313
package org.openhab.binding.mqtt.homeassistant.internal.component;
1414

1515
import org.eclipse.jdt.annotation.NonNullByDefault;
16-
import org.eclipse.jdt.annotation.Nullable;
1716
import org.openhab.binding.mqtt.generic.values.ImageValue;
18-
import org.openhab.binding.mqtt.generic.values.TextValue;
1917
import org.openhab.binding.mqtt.homeassistant.internal.ComponentChannelType;
2018
import org.openhab.binding.mqtt.homeassistant.internal.config.dto.AbstractChannelConfiguration;
21-
import org.openhab.core.thing.type.AutoUpdatePolicy;
22-
23-
import com.google.gson.annotations.SerializedName;
2419

2520
/**
2621
* A MQTT camera, following the https://www.home-assistant.io/components/camera.mqtt/ specification.
@@ -32,7 +27,6 @@
3227
@NonNullByDefault
3328
public class Camera extends AbstractComponent<Camera.ChannelConfiguration> {
3429
public static final String CAMERA_CHANNEL_ID = "camera";
35-
public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
3630

3731
/**
3832
* Configuration class for MQTT component
@@ -43,11 +37,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
4337
}
4438

4539
protected String topic = "";
46-
47-
@SerializedName("json_attributes_template")
48-
protected @Nullable String jsonAttributesTemplate;
49-
@SerializedName("json_attributes_topic")
50-
protected @Nullable String jsonAttributesTopic;
5140
}
5241

5342
public Camera(ComponentFactory.ComponentConfiguration componentConfiguration, boolean newStyleChannels) {
@@ -58,13 +47,6 @@ public Camera(ComponentFactory.ComponentConfiguration componentConfiguration, bo
5847
buildChannel(CAMERA_CHANNEL_ID, ComponentChannelType.IMAGE, value, getName(),
5948
componentConfiguration.getUpdateListener()).stateTopic(channelConfiguration.topic).build();
6049

61-
if (channelConfiguration.jsonAttributesTopic != null) {
62-
buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
63-
componentConfiguration.getUpdateListener())
64-
.stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
65-
.withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
66-
}
67-
6850
finalizeChannels();
6951
}
7052
}

‎bundles/org.openhab.binding.mqtt.homeassistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Climate.java

-13
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@
3333
import org.openhab.core.library.types.StringType;
3434
import org.openhab.core.library.unit.ImperialUnits;
3535
import org.openhab.core.library.unit.SIUnits;
36-
import org.openhab.core.thing.type.AutoUpdatePolicy;
3736
import org.openhab.core.types.Command;
3837
import org.openhab.core.types.State;
3938

@@ -64,7 +63,6 @@ public class Climate extends AbstractComponent<Climate.ChannelConfiguration> {
6463
public static final String TEMPERATURE_LOW_CH_ID = "temperature-low";
6564
public static final String TEMPERATURE_LOW_CH_ID_DEPRECATED = "temperatureLow";
6665
public static final String POWER_CH_ID = "power";
67-
public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
6866

6967
public enum TemperatureUnit {
7068
@SerializedName("C")
@@ -150,11 +148,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
150148
protected @Nullable List<String> holdModes; // Are there default modes? Now the channel will be ignored without
151149
// hold modes.
152150

153-
@SerializedName("json_attributes_template")
154-
protected @Nullable String jsonAttributesTemplate;
155-
@SerializedName("json_attributes_topic")
156-
protected @Nullable String jsonAttributesTopic;
157-
158151
@SerializedName("mode_command_template")
159152
protected @Nullable String modeCommandTemplate;
160153
@SerializedName("mode_command_topic")
@@ -298,12 +291,6 @@ ComponentChannelType.SWITCH, new OnOffValue(), updateListener, null,
298291
buildOptionalChannel(POWER_CH_ID, ComponentChannelType.SWITCH, new OnOffValue(), updateListener, null,
299292
channelConfiguration.powerCommandTopic, null, null, null);
300293

301-
if (channelConfiguration.jsonAttributesTopic != null) {
302-
buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
303-
componentConfiguration.getUpdateListener())
304-
.stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
305-
.withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
306-
}
307294
finalizeChannels();
308295
}
309296

‎bundles/org.openhab.binding.mqtt.homeassistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Cover.java

-12
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,6 @@
4040
public class Cover extends AbstractComponent<Cover.ChannelConfiguration> {
4141
public static final String COVER_CHANNEL_ID = "cover";
4242
public static final String STATE_CHANNEL_ID = "state";
43-
public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
4443

4544
/**
4645
* Configuration class for MQTT component
@@ -84,11 +83,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
8483
protected String stateOpening = "opening";
8584
@SerializedName("state_stopped")
8685
protected String stateStopped = "stopped";
87-
88-
@SerializedName("json_attributes_template")
89-
protected @Nullable String jsonAttributesTemplate;
90-
@SerializedName("json_attributes_topic")
91-
protected @Nullable String jsonAttributesTopic;
9286
}
9387

9488
@Nullable
@@ -166,12 +160,6 @@ public Cover(ComponentFactory.ComponentConfiguration componentConfiguration, boo
166160
return true;
167161
}).withAutoUpdatePolicy(optimistic ? AutoUpdatePolicy.RECOMMEND : null).build();
168162

169-
if (channelConfiguration.jsonAttributesTopic != null) {
170-
buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
171-
componentConfiguration.getUpdateListener())
172-
.stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
173-
.withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
174-
}
175163
finalizeChannels();
176164
}
177165
}

‎bundles/org.openhab.binding.mqtt.homeassistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Event.java

+10-13
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@
1616
import java.util.List;
1717

1818
import org.eclipse.jdt.annotation.NonNullByDefault;
19-
import org.eclipse.jdt.annotation.Nullable;
2019
import org.openhab.binding.mqtt.generic.ChannelStateUpdateListener;
2120
import org.openhab.binding.mqtt.generic.values.TextValue;
2221
import org.openhab.binding.mqtt.homeassistant.internal.ComponentChannelType;
@@ -36,7 +35,6 @@
3635
@NonNullByDefault
3736
public class Event extends AbstractComponent<Event.ChannelConfiguration> implements ChannelStateUpdateListener {
3837
public static final String EVENT_TYPE_CHANNEL_ID = "event-type";
39-
public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
4038
private static final String EVENT_TYPE_TRANFORMATION = "{{ value_json.event_type }}";
4139

4240
/**
@@ -52,12 +50,6 @@ public static class ChannelConfiguration extends AbstractChannelConfiguration {
5250

5351
@SerializedName("event_types")
5452
protected List<String> eventTypes = new ArrayList();
55-
56-
@SerializedName("json_attributes_topic")
57-
protected @Nullable String jsonAttributesTopic;
58-
59-
@SerializedName("json_attributes_template")
60-
protected @Nullable String jsonAttributesTemplate;
6153
}
6254

6355
private final HomeAssistantChannelTransformation transformation;
@@ -71,7 +63,13 @@ public Event(ComponentFactory.ComponentConfiguration componentConfiguration, boo
7163
.stateTopic(channelConfiguration.stateTopic, channelConfiguration.getValueTemplate()).trigger(true)
7264
.build();
7365

74-
if (channelConfiguration.jsonAttributesTopic != null) {
66+
finalizeChannels();
67+
}
68+
69+
// Overridden to use create it as a trigger channel
70+
@Override
71+
protected void addJsonAttributesChannel() {
72+
if (channelConfiguration.getJsonAttributesTopic() != null) {
7573
// It's unclear from the documentation if the JSON attributes value is expected
7674
// to be the same as the main topic, and thus would always have an event_type
7775
// attribute (and thus could possibly be shared with multiple components).
@@ -81,11 +79,10 @@ public Event(ComponentFactory.ComponentConfiguration componentConfiguration, boo
8179
// the filtering below.
8280
buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.TRIGGER, new TextValue(), getName(),
8381
componentConfiguration.getUpdateListener())
84-
.stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
85-
.trigger(true).build();
82+
.stateTopic(channelConfiguration.getJsonAttributesTopic(),
83+
channelConfiguration.getJsonAttributesTemplate())
84+
.isAdvanced(true).trigger(true).build();
8685
}
87-
88-
finalizeChannels();
8986
}
9087

9188
@Override

‎bundles/org.openhab.binding.mqtt.homeassistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Fan.java

+4-16
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@
2828
import org.openhab.core.library.types.OnOffType;
2929
import org.openhab.core.library.types.PercentType;
3030
import org.openhab.core.thing.ChannelUID;
31-
import org.openhab.core.thing.type.AutoUpdatePolicy;
3231
import org.openhab.core.types.Command;
3332
import org.openhab.core.types.State;
3433
import org.openhab.core.types.UnDefType;
@@ -44,12 +43,12 @@
4443
*/
4544
@NonNullByDefault
4645
public class Fan extends AbstractComponent<Fan.ChannelConfiguration> implements ChannelStateUpdateListener {
47-
public static final String SWITCH_CHANNEL_ID = "fan";
46+
public static final String SWITCH_CHANNEL_ID = "switch";
47+
public static final String SWITCH_CHANNEL_ID_DEPRECATED = "fan";
4848
public static final String SPEED_CHANNEL_ID = "speed";
4949
public static final String PRESET_MODE_CHANNEL_ID = "preset-mode";
5050
public static final String OSCILLATION_CHANNEL_ID = "oscillation";
5151
public static final String DIRECTION_CHANNEL_ID = "direction";
52-
public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
5352

5453
/**
5554
* Configuration class for MQTT component
@@ -117,10 +116,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
117116
protected int speedRangeMax = 100;
118117
@SerializedName("speed_range_min")
119118
protected int speedRangeMin = 1;
120-
@SerializedName("json_attributes_template")
121-
protected @Nullable String jsonAttributesTemplate;
122-
@SerializedName("json_attributes_topic")
123-
protected @Nullable String jsonAttributesTopic;
124119
}
125120

126121
private final OnOffValue onOffValue;
@@ -139,8 +134,8 @@ public Fan(ComponentFactory.ComponentConfiguration componentConfiguration, boole
139134
ChannelStateUpdateListener onOffListener = channelConfiguration.percentageCommandTopic == null
140135
? componentConfiguration.getUpdateListener()
141136
: this;
142-
onOffChannel = buildChannel(SWITCH_CHANNEL_ID, ComponentChannelType.SWITCH, onOffValue, "On/Off State",
143-
onOffListener)
137+
onOffChannel = buildChannel(newStyleChannels ? SWITCH_CHANNEL_ID : SWITCH_CHANNEL_ID_DEPRECATED,
138+
ComponentChannelType.SWITCH, onOffValue, "On/Off State", onOffListener)
144139
.stateTopic(channelConfiguration.stateTopic, channelConfiguration.getValueTemplate())
145140
.commandTopic(channelConfiguration.commandTopic, channelConfiguration.isRetain(),
146141
channelConfiguration.getQos(), channelConfiguration.commandTemplate)
@@ -202,13 +197,6 @@ public Fan(ComponentFactory.ComponentConfiguration componentConfiguration, boole
202197
.inferOptimistic(channelConfiguration.optimistic).build();
203198
}
204199

205-
if (channelConfiguration.jsonAttributesTopic != null) {
206-
buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
207-
componentConfiguration.getUpdateListener())
208-
.stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
209-
.withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
210-
}
211-
212200
finalizeChannels();
213201
}
214202

‎bundles/org.openhab.binding.mqtt.homeassistant/src/main/java/org/openhab/binding/mqtt/homeassistant/internal/component/Lock.java

-13
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,6 @@
3636
public class Lock extends AbstractComponent<Lock.ChannelConfiguration> {
3737
public static final String LOCK_CHANNEL_ID = "lock";
3838
public static final String STATE_CHANNEL_ID = "state";
39-
public static final String JSON_ATTRIBUTES_CHANNEL_ID = "json-attributes";
4039

4140
/**
4241
* Configuration class for MQTT component
@@ -68,11 +67,6 @@ static class ChannelConfiguration extends AbstractChannelConfiguration {
6867
protected String stateUnlocked = "UNLOCKED";
6968
@SerializedName("state_unlocking")
7069
protected String stateUnlocking = "UNLOCKING";
71-
72-
@SerializedName("json_attributes_template")
73-
protected @Nullable String jsonAttributesTemplate;
74-
@SerializedName("json_attributes_topic")
75-
protected @Nullable String jsonAttributesTopic;
7670
}
7771

7872
private boolean optimistic = false;
@@ -128,13 +122,6 @@ public Lock(ComponentFactory.ComponentConfiguration componentConfiguration, bool
128122
return true;
129123
}).build();
130124

131-
if (channelConfiguration.jsonAttributesTopic != null) {
132-
buildChannel(JSON_ATTRIBUTES_CHANNEL_ID, ComponentChannelType.STRING, new TextValue(), "JSON Attributes",
133-
componentConfiguration.getUpdateListener())
134-
.stateTopic(channelConfiguration.jsonAttributesTopic, channelConfiguration.jsonAttributesTemplate)
135-
.withAutoUpdatePolicy(AutoUpdatePolicy.VETO).build();
136-
}
137-
138125
finalizeChannels();
139126
}
140127

0 commit comments

Comments
 (0)
Please sign in to comment.