mqtt-discovery-types/src/LightDiscovery.d.ts

Typescript Types For HomeAssistant MQTT Discovery

import type { CommandComponentDiscovery } from "./BaseEntityDiscovery.ts";
import type { MakeEntity } from "./utils.ts";

export type LightDiscovery = DefaultLightDiscovery | JSONLightDiscovery;
export type DefaultLightDiscovery = MakeEntity<DefaultLightComponentDiscovery>;
export type JSONLightDiscovery = MakeEntity<JSONLightComponentDiscovery>;
export type LightComponentDiscovery = DefaultLightComponentDiscovery | JSONLightComponentDiscovery;

/**
 * https://www.home-assistant.io/integrations/light.mqtt/#configuration-variables
 */
export interface DefaultLightComponentDiscovery extends CommandComponentDiscovery {
    platform: 'light';

    /**
     * Must be 'default' or 'omitted' to use the default schema.
     * Other options are `json` and `template`.
     */
    schema?: 'default'

    /**
     * The MQTT topic to publish commands to change the light’s brightness.
     */
    brightness_command_topic?: string;

    /**
     * Defines a template to generate the payload to send to `brightness_command_topic`.
     * Available variables: `value`.
     */
    brightness_command_template?: string;

    /**
     * Defines the maximum brightness value (i.e. 100%) of the MQTT device.
     */
    brightness_scale?: number;

    /**
     * The MQTT topic subscribed to receive brightness state updates.
     */
    brightness_state_topic?: string;

    /**
     * Defines a template to extract the brightness value from the `brightness_state_topic` payload.
     */
    brightness_value_template?: string;

    /**
     * The MQTT topic subscribed to receive color mode state updates.
     */
    color_mode_state_topic?: string;

    /**
     * Defines a template to extract the color mode value from the `color_mode_state_topic` payload.
     */
    color_mode_value_template?: string;

    /**
     * Defines a template to generate the payload to send to `color_temp_command_topic`.
     */
    color_temp_command_template?: string;

    /**
     * The MQTT topic to publish commands to change the light’s color temperature.
     */
    color_temp_command_topic?: string;

    /**
     * The MQTT topic subscribed to receive color temperature state updates.
     */
    color_temp_state_topic?: string;

    /**
     * Defines a template to extract the color temperature value from the `color_temp_state_topic` payload.
     */
    color_temp_value_template?: string;

    /**
     * When set to true, color_temp_command_topic will publish color mode updates in Kelvin and process color_temp_state_topic will process state updates in Kelvin. When not set the color_temp values are converted to mireds.
     */
    color_temp_kelvin?: boolean;

    /**
     * The maximum kelvin value supported by the light.
     */
    max_kelvin?: number;

    /**
     * The minimum kelvin value supported by the light.
     */
    min_kelvin?: number;

    /**
     * The MQTT topic to publish commands to change the light’s effect.
     */
    effect_command_topic?: string;

    /**
     * Defines a template to generate the payload to send to `effect_command_topic`.
     */
    effect_command_template?: string;

    /**
     * The list of effects the light supports.
     */
    effect_list?: string[];

    /**
     * The MQTT topic subscribed to receive effect state updates.
     */
    effect_state_topic?: string;

    /**
     * Defines a template to extract the effect value from the `effect_state_topic` payload.
     */
    effect_value_template?: string;

    /**
     * The MQTT topic to publish commands to change the light's color state in HS format.
     * Range for hue is 0-360° and for saturation 0-100%.
     * Note: brightness is sent separately via the brightness_command_topic.
     */
    hs_command_topic?: string;

    /**
     * Defines a template to generate the payload to send to `hs_command_topic`.
     * Available variables: `hue`, `sat`.
     */
    hs_command_template?: string;

    /**
     * The MQTT topic subscribed to receive HS state updates.
     */
    hs_state_topic?: string;

    /**
     * Defines a template to extract the HS value from the `hs_state_topic` payload.
     */
    hs_value_template?: string;

    /**
     * The maximum mireds value supported by the light.
     */
    max_mireds?: number;

    /**
     * The minimum mireds value supported by the light.
     */
    min_mireds?: number;

    /**
     * Defines when on the payload_on is sent. Using last (the default) will send any style (brightness, color, etc) topics first and then a payload_on to the command_topic. Using first will send the payload_on and then any style topics. Using brightness will only send brightness commands instead of the payload_on to turn the light on.
     */
    on_command_type?: 'first' | 'last' | 'brightness';

    /**
     * Flag that defines if the light works in optimistic mode.
     * @defaultValue false if `state_topic` defined, true otherwise
     */
    optimistic?: boolean;

    /**
     * The payload that represents the disabled state.
     */
    payload_off?: string;

    /**
     * The payload that represents the enabled state.
     */
    payload_on?: string;

    /**
     * The MQTT topic to publish commands to change the light’s RGB state.
     */
    rgb_command_topic?: string;

    /**
     * Defines a template to generate the payload to send to `rgb_command_topic`.
     * Available variables: `red`, `green`, `blue`.
     */
    rgb_command_template?: string;

    /**
     * The MQTT topic subscribed to receive RGB state updates.
     * Expected payload is RGB values separated by commas.
     */
    rgb_state_topic?: string;

    /**
     * Defines a template to extract the RGB value from the `rgb_state_topic` payload.
     */
    rgb_value_template?: string;

    /**
     * The MQTT topic to publish commands to change the light’s RGBW state.
     */
    rgbw_command_topic?: string;

    /**
     * Defines a template to generate the payload to send to `rgbw_command_topic`.
     * Available variables: `red`, `green`, `blue`, `white`.
     */
    rgbw_command_template?: string;

    /**
     * The MQTT topic subscribed to receive RGBW state updates.
     * Expected payload is RGBW values separated by commas.
     */
    rgbw_state_topic?: string;

    /**
     * Defines a template to extract the RGBW value from the `rgbw_state_topic` payload.
     */
    rgbw_value_template?: string;

    /**
     * The MQTT topic to publish commands to change the light’s RGBWW state.
     */
    rgbww_command_topic?: string;

    /**
     * Defines a template to generate the payload to send to `rgbww_command_topic`.
     * Available variables: `red`, `green`, `blue`, `cold_white`, `warm_white`.
     */
    rgbww_command_template?: string;

    /**
     * The MQTT topic subscribed to receive RGBWW state updates.
     * Expected payload is RGBWW values separated by commas.
     */
    rgbww_state_topic?: string;

    /**
     * Defines a template to extract the RGBWW value from the `rgbww_state_topic` payload.
     */
    rgbww_value_template?: string;

    /**
     * The MQTT topic to publish commands to change the light to white mode with a given brightness.
     */
    white_command_topic?: string;

    /**
     * Defines a template to generate the payload to send to `white_command_topic`.
     */
    white_command_template?: string;

    /**
     * Defines the maximum white value (i.e. 100%) of the MQTT device.
     */
    white_scale?: number;

    /**
     * The MQTT topic to push commands to change the light’s XY state.
     */
    xy_command_topic?: string;

    /**
     * Defines a template to generate the payload to send to `xy_command_topic`.
     * Available variables: `x`, `y`.
     */
    xy_command_template?: string;

    /**
     * The MQTT topic subscribed to receive XY state updates.
     */
    xy_state_topic?: string;

    /**
     * Defines a template to extract the XY value from the `xy_state_topic` payload.
     */
    xy_value_template?: string;
}

export type ColorModes = 'onoff' | 'brightness' | 'color_temp' | 'hs' | 'rgb' | 'rgbw' | 'rgbww' | 'white' | 'xy';

/**
 * https://www.home-assistant.io/integrations/light.mqtt/#json-schema---configuration
 */
export interface JSONLightComponentDiscovery extends CommandComponentDiscovery {
    platform: 'light';

    /**
     * Must be 'json' to use the JSON schema.
     */
    schema: 'json';

    /**
     * Flag that defines if the light supports brightness control.
     */
    brightness?: boolean;

    /**
     * Defines the maximum brightness value (i.e. 100%) of the MQTT device.
     */
    brightness_scale?: number;

    /**
     * Flag that defines if the light supports color modes.
     */
    color_mode?: boolean;

    /**
     * Flag that defines if the light supports effects.
     */
    effect?: boolean;

    /**
     * The list of effects the light supports.
     */
    effect_list?: string[];

    /**
     * The duration in seconds of a "long" flash.
     */
    flash_time_long?: number;

    /**
     * The duration in seconds of a "short" flash.
     */
    flash_time_short?: number;

    /**
     * The maximum mireds value supported by the light.
     */
    max_mireds?: number;

    /**
     * The minimum mireds value supported by the light.
     */
    min_mireds?: number;

    /**
     * When set to true, color_temp_command_topic will publish color mode updates in Kelvin and process color_temp_state_topic will process state updates in Kelvin. When not set the color_temp values are converted to mireds.
     */
    color_temp_kelvin?: boolean;

    /**
     * The maximum kelvin value supported by the light.
     */
    max_kelvin?: number;

    /**
     * The minimum kelvin value supported by the light.
     */
    min_kelvin?: number;


    /**
     * Flag that defines if the light works in optimistic mode.
     * @defaultValue false if `state_topic` defined, true otherwise
     */
    optimistic?: boolean;

    /**
     * The MQTT topic subscribed to receive state updates.
     */
    state_topic?: string;

    /**
     * A list of color modes the light supports.
     * This is required if `color_mode` is true.
     */
    supported_color_modes?: ColorModes[];

    /**
     * Defines the maximum white value (i.e. 100%) of the MQTT device.
     */
    white_scale?: number;
}