diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index af0f99c2c1e..53e1fc9383d 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -55,6 +55,118 @@ An empty payload will cause a previously discovered device to be deleted. The `` level can be used by clients to only subscribe to their own (command) topics by using one wildcard topic like `/+//+/set`. +A base topic `~` may be defined in the payload to conserve memory when the same topic base is used multiple times. +In the value of configuration variables ending with `_topic`, `~` will be replaced with the base topic, if the `~` occurs at the beginning or end of the value. + +Configuration variable names in the discovery payload may be abbreviated to conserve memory when sending a discovery message from memory constrained devices. + +Supported abbreviations: +``` + 'aux_cmd_t': 'aux_command_topic', + 'aux_stat_tpl': 'aux_state_template', + 'aux_stat_t': 'aux_state_topic', + 'avty_t': 'availability_topic', + 'away_mode_cmd_t': 'away_mode_command_topic', + 'away_mode_stat_tpl': 'away_mode_state_template', + 'away_mode_stat_t': 'away_mode_state_topic', + 'bri_cmd_t': 'brightness_command_topic', + 'bri_scl': 'brightness_scale', + 'bri_stat_t': 'brightness_state_topic', + 'bri_val_tpl': 'brightness_value_template', + 'clr_temp_cmd_t': 'color_temp_command_topic', + 'clr_temp_stat_t': 'color_temp_state_topic', + 'clr_temp_val_tpl': 'color_temp_value_template', + 'cmd_t': 'command_topic', + 'curr_temp_t': 'current_temperature_topic', + 'dev_cla': 'device_class', + 'fx_cmd_t': 'effect_command_topic', + 'fx_list': 'effect_list', + 'fx_stat_t': 'effect_state_topic', + 'fx_val_tpl': 'effect_value_template', + 'exp_aft': 'expire_after', + 'fan_mode_cmd_t': 'fan_mode_command_topic', + 'fan_mode_stat_tpl': 'fan_mode_state_template', + 'fan_mode_stat_t': 'fan_mode_state_topic', + 'frc_upd': 'force_update', + 'hold_cmd_t': 'hold_command_topic', + 'hold_stat_tpl': 'hold_state_template', + 'hold_stat_t': 'hold_state_topic', + 'ic': 'icon', + 'init': 'initial', + 'json_attr': 'json_attributes', + 'max_temp': 'max_temp', + 'min_temp': 'min_temp', + 'mode_cmd_t': 'mode_command_topic', + 'mode_stat_tpl': 'mode_state_template', + 'mode_stat_t': 'mode_state_topic', + 'name': 'name', + 'on_cmd_type': 'on_command_type', + 'opt': 'optimistic', + 'osc_cmd_t': 'oscillation_command_topic', + 'osc_stat_t': 'oscillation_state_topic', + 'osc_val_tpl': 'oscillation_value_template', + 'pl_arm_away': 'payload_arm_away', + 'pl_arm_home': 'payload_arm_home', + 'pl_avail': 'payload_available', + 'pl_cls': 'payload_close', + 'pl_disarm': 'payload_disarm', + 'pl_hi_spd': 'payload_high_speed', + 'pl_lock': 'payload_lock', + 'pl_lo_spd': 'payload_low_speed', + 'pl_med_spd': 'payload_medium_speed', + 'pl_not_avail': 'payload_not_available', + 'pl_off': 'payload_off', + 'pl_on': 'payload_on', + 'pl_open': 'payload_open', + 'pl_osc_off': 'payload_oscillation_off', + 'pl_osc_on': 'payload_oscillation_on', + 'pl_stop': 'payload_stop', + 'pl_unlk': 'payload_unlock', + 'pow_cmd_t': 'power_command_topic', + 'ret': 'retain', + 'rgb_cmd_tpl': 'rgb_command_template', + 'rgb_cmd_t': 'rgb_command_topic', + 'rgb_stat_t': 'rgb_state_topic', + 'rgb_val_tpl': 'rgb_value_template', + 'send_if_off': 'send_if_off', + 'set_pos_tpl': 'set_position_template', + 'set_pos_t': 'set_position_topic', + 'spd_cmd_t': 'speed_command_topic', + 'spd_stat_t': 'speed_state_topic', + 'spd_val_tpl': 'speed_value_template', + 'spds': 'speeds', + 'stat_clsd': 'state_closed', + 'stat_off': 'state_off', + 'stat_on': 'state_on', + 'stat_open': 'state_open', + 'stat_t': 'state_topic', + 'stat_val_tpl': 'state_value_template', + 'swing_mode_cmd_t': 'swing_mode_command_topic', + 'swing_mode_stat_tpl': 'swing_mode_state_template', + 'swing_mode_stat_t': 'swing_mode_state_topic', + 'temp_cmd_t': 'temperature_command_topic', + 'temp_stat_tpl': 'temperature_state_template', + 'temp_stat_t': 'temperature_state_topic', + 'tilt_clsd_val': 'tilt_closed_value', + 'tilt_cmd_t': 'tilt_command_topic', + 'tilt_inv_stat': 'tilt_invert_state', + 'tilt_max': 'tilt_max', + 'tilt_min': 'tilt_min', + 'tilt_opnd_val': 'tilt_opened_value', + 'tilt_status_opt': 'tilt_status_optimistic', + 'tilt_status_t': 'tilt_status_topic', + 't': 'topic', + 'uniq_id': 'unique_id', + 'unit_of_meas': 'unit_of_measurement', + 'val_tpl': 'value_template', + 'whit_val_cmd_t': 'white_value_command_topic', + 'whit_val_stat_t': 'white_value_state_topic', + 'whit_val_tpl': 'white_value_template', + 'xy_cmd_t': 'xy_command_topic', + 'xy_stat_t': 'xy_state_topic', + 'xy_val_tpl': 'xy_value_template', +``` + ### {% linkable_title Support by third-party tools %} The following firmware for ESP8266, ESP32 and Sonoff unit has built-in support for MQTT discovery: @@ -113,4 +225,9 @@ Setting up a sensor with multiple measurement values requires multiple consecuti - Configuration payload no2: `{"device_class": "sensor", "name": "Humidity", "state_topic": "homeassistant/sensor/sensorBedroom/state", "unit_of_measurement": "%", "value_template": "{% raw %}{{ value_json.humidity}}{% endraw %}" }` - Common state payload: `{ "temperature": 23.20, "humidity": 43.70 }` +Setting up a switch using topic prefix and abbreviated configuration variable names to reduce payload length. +- Configuration topic: `homeassistant/switch/irrigation/config` +- Command topic: `homeassistant/switch/irrigation/set` +- State topic: `homeassistant/switch/irrigation/state` +- Payload: `{"~": "homeassistant/switch/irrigation", "name": "garden", "cmd_t": "~/set", , "stat_t": "~/state"}`