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

Typescript Types For HomeAssistant MQTT Discovery

import type { AvailabilityDiscovery } from "./AvailabilityDiscovery";
import type { DeviceOptions } from "./DeviceOptions";

export interface BaseComponentDiscovery extends AvailabilityDiscovery {

    /**
     * A base topic that all other topics will be relative to.
     */
    "~"?: string;

    /**
     * The name of the entity. Can be set to `null` if only the device name is relevant.
     */
    name?: string | null;

    /**
     * Used instead of `name` for automatic generation of `entity_id`.
     */
    object_id?: string;

    /**
     * An ID that uniquely identifies this entity. If two entities have the same unique ID, Home Assistant will raise an exception.
     */
    unique_id: string;

    /**
     * Information about the device this alarm panel is a part of to tie it into the device registry. 
     * Only works when `unique_id` is set. At least one of identifiers or connections must be present to identify the device.
     */
    device?: DeviceOptions;

    /**
     * Flag which defines if the entity should be enabled when first added to Home Assistant.
     */
    enabled_by_default?: boolean;

    /**
     * The encoding of the payloads received and published messages. 
     * Set to "" to disable decoding of incoming payload.
     */
    encoding?: 'utf-8' | 'utf-16' | 'utf-32';

    /**
     * The category of the entity.
     * 
     * @defaultValue sensor
     */
    entity_category?: "config" | "diagnostic";

    /**
     * Icon for the entity. From material design icons. Prefix with `'mdi:'`.
     */
    icon?: string;

    /**
     * The MQTT topic subscribed to receive a JSON dictionary payload and then set as sensor attributes. 
     * Usage example can be found in MQTT sensor documentation.
     */
    json_attributes_topic?: string;

    /**
     * Defines a template to extract the JSON dictionary from messages received on the `json_attributes_topic`.
     * Usage example can be found in MQTT sensor documentation.
     */
    json_attributes_template?: string;

    /**
     * The maximum QoS level to be used when receiving and publishing messages.
     * @defaultValue 0
     */
    qos?: 0 | 1 | 2;
}

export interface StatefulComponentDiscovery extends BaseComponentDiscovery {

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

    /**
     * Defines a template to extract a value from the payload.
     */
    value_template?: string;

    /** Defines a template to extract a value from the payload. */
    state_value_template?: string;
}

export interface OptionallyStatefulComponentDiscovery extends BaseComponentDiscovery {

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

    /**
     * Defines a template to extract a value from the payload.
     */
    value_template?: string;
}

export interface CommandComponentDiscovery extends BaseComponentDiscovery {
    /**
     * The MQTT topic to publish commands to the device.
     */
    command_topic: string;

    /**
     * The template used for the command payload. 
     */
    command_template?: string;

    /**
     * If the published message should have the retain flag on or not.
     * @defaultValue false
     */
    retain?: boolean;
}

export interface StatefulCommandComponentDiscovery extends StatefulComponentDiscovery, CommandComponentDiscovery { }

export interface OptionallyStatefulCommandComponentDiscovery extends OptionallyStatefulComponentDiscovery, CommandComponentDiscovery { }