mirror of
https://github.com/adrianjagielak/home-assistant-futurehome.git
synced 2025-12-20 03:33:56 +00:00
Create MQTT components interfaces and documentation
This commit is contained in:
Adrian Jagielak
276
futurehome/src/ha/mqtt_components/binary_sensor.ts
Normal file
276
futurehome/src/ha/mqtt_components/binary_sensor.ts
Normal file
@@ -0,0 +1,276 @@
|
||||
/**
|
||||
* Represents a MQTT Binary Sensor component for Home Assistant MQTT Discovery.
|
||||
*
|
||||
* The `mqtt` binary sensor platform uses an MQTT message received to set the binary sensor's state to `on`, `off` or `unknown`.
|
||||
*
|
||||
* For detailed documentation see:
|
||||
* https://www.home-assistant.io/integrations/binary_sensor.mqtt/
|
||||
*/
|
||||
export interface BinarySensorComponent {
|
||||
/**
|
||||
* Must be `binary_sensor`.
|
||||
* Only allowed and required in [MQTT auto discovery device messages](https://www.home-assistant.io/integrations/mqtt/#device-discovery-payload).
|
||||
*/
|
||||
platform: 'binary_sensor';
|
||||
|
||||
/**
|
||||
* An ID that uniquely identifies this sensor.
|
||||
* If two sensors have the same unique ID, Home Assistant will raise an exception.
|
||||
* Required when used with device-based discovery.
|
||||
*/
|
||||
unique_id: string;
|
||||
|
||||
/**
|
||||
* The MQTT topic subscribed to receive sensor's state.
|
||||
* Valid states are `OFF` and `ON`.
|
||||
* Custom `OFF` and `ON` values can be set with the `payload_off` and `payload_on` config options.
|
||||
*/
|
||||
state_topic?: string;
|
||||
|
||||
/**
|
||||
* Sets the [class of the device](https://www.home-assistant.io/integrations/binary_sensor/#device-class),
|
||||
* changing the device state and icon that is displayed on the frontend.
|
||||
* The `device_class` can be `null`.
|
||||
*/
|
||||
device_class?: string | null;
|
||||
|
||||
/**
|
||||
* The string that represents the `on` state.
|
||||
* It will be compared to the message in the `state_topic` (see `value_template` for details).
|
||||
* Default: "ON"
|
||||
*/
|
||||
payload_on?: string;
|
||||
|
||||
/**
|
||||
* The string that represents the `off` state.
|
||||
* It will be compared to the message in the `state_topic` (see `value_template` for details).
|
||||
* Default: "OFF"
|
||||
*/
|
||||
payload_off?: string;
|
||||
|
||||
/**
|
||||
* Defines a [template](https://www.home-assistant.io/docs/configuration/templating/#using-value-templates-with-mqtt)
|
||||
* that returns a string to be compared to `payload_on`/`payload_off` or an empty string,
|
||||
* in which case the MQTT message will be removed.
|
||||
* Remove this option when `payload_on` and `payload_off` are sufficient to match your payloads
|
||||
* (i.e no preprocessing of original message is required).
|
||||
*/
|
||||
value_template?: string;
|
||||
|
||||
/**
|
||||
* Sends update events (which results in update of [state object](https://www.home-assistant.io/docs/configuration/state_object/)'s `last_changed`)
|
||||
* even if the sensor's state hasn't changed. Useful if you want to have meaningful value graphs in history
|
||||
* or want to create an automation that triggers on *every* incoming state message (not only when the sensor's new state is different to the current one).
|
||||
* Default: false
|
||||
*/
|
||||
force_update?: boolean;
|
||||
|
||||
/**
|
||||
* If set, it defines the number of seconds after the sensor's state expires,
|
||||
* if it's not updated. After expiry, the sensor's state becomes `unavailable`.
|
||||
* Default the sensor's state never expires.
|
||||
*/
|
||||
expire_after?: number;
|
||||
|
||||
/**
|
||||
* The encoding of the payloads received.
|
||||
* Set to `""` to disable decoding of incoming payload.
|
||||
* Default: "utf-8"
|
||||
*/
|
||||
encoding?: string;
|
||||
|
||||
/**
|
||||
* Flag which defines if the entity should be enabled when first added.
|
||||
* Default: true
|
||||
*/
|
||||
enabled_by_default?: boolean;
|
||||
|
||||
/**
|
||||
* The name of the binary sensor.
|
||||
* Can be set to `null` if only the device name is relevant.
|
||||
* Default: "MQTT binary sensor"
|
||||
*/
|
||||
name?: string | null;
|
||||
|
||||
/**
|
||||
* Used instead of `name` for automatic generation of `entity_id`.
|
||||
*/
|
||||
object_id?: string;
|
||||
|
||||
/**
|
||||
* The maximum QoS level to be used when receiving and publishing messages.
|
||||
* Default: 0
|
||||
*/
|
||||
qos?: number;
|
||||
|
||||
/**
|
||||
* The [category](https://developers.home-assistant.io/docs/core/entity/#generic-properties) of the entity.
|
||||
* When set, the entity category must be `diagnostic` for sensors.
|
||||
*/
|
||||
entity_category?: string;
|
||||
|
||||
/**
|
||||
* Picture URL for the entity.
|
||||
*/
|
||||
entity_picture?: string;
|
||||
|
||||
/**
|
||||
* [Icon](https://www.home-assistant.io/docs/configuration/customizing-devices/#icon) for the entity.
|
||||
*/
|
||||
icon?: string;
|
||||
|
||||
/**
|
||||
* Defines a [template](https://www.home-assistant.io/docs/configuration/templating/#using-value-templates-with-mqtt)
|
||||
* to extract the JSON dictionary from messages received on the `json_attributes_topic`.
|
||||
* Usage example can be found in [MQTT sensor](https://www.home-assistant.io/integrations/sensor.mqtt/#json-attributes-template-configuration) documentation.
|
||||
*/
|
||||
json_attributes_template?: 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](https://www.home-assistant.io/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
|
||||
*/
|
||||
json_attributes_topic?: string;
|
||||
|
||||
/**
|
||||
* If set, the sensor will send `off` state after this amount of seconds when the sensor only sends `on` state updates.
|
||||
*/
|
||||
off_delay?: number;
|
||||
|
||||
/**
|
||||
* A list of MQTT topics subscribed to receive availability (online/offline) updates.
|
||||
* Must not be used together with `availability_topic`.
|
||||
*/
|
||||
availability?: Array<{
|
||||
/**
|
||||
* An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
*/
|
||||
topic: string;
|
||||
|
||||
/**
|
||||
* The payload that represents the available state.
|
||||
* Default: "online"
|
||||
*/
|
||||
payload_available?: string;
|
||||
|
||||
/**
|
||||
* The payload that represents the unavailable state.
|
||||
* Default: "offline"
|
||||
*/
|
||||
payload_not_available?: string;
|
||||
|
||||
/**
|
||||
* Defines a [template](https://www.home-assistant.io/docs/configuration/templating/#using-value-templates-with-mqtt)
|
||||
* to extract device's availability from the `topic`.
|
||||
* To determine the device's availability, result of this template will be compared to `payload_available` and `payload_not_available`.
|
||||
*/
|
||||
value_template?: string;
|
||||
}>;
|
||||
|
||||
/**
|
||||
* When `availability` is configured, this controls the conditions needed to set the entity to `available`.
|
||||
* Valid values: "all", "any", "latest"
|
||||
* Default: "latest"
|
||||
*/
|
||||
availability_mode?: 'all' | 'any' | 'latest';
|
||||
|
||||
/**
|
||||
* Defines a [template](https://www.home-assistant.io/docs/configuration/templating/#using-value-templates-with-mqtt)
|
||||
* to extract device's availability from the `availability_topic`.
|
||||
* To determine the device's availability, result of this template will be compared to `payload_available` and `payload_not_available`.
|
||||
*/
|
||||
availability_template?: string;
|
||||
|
||||
/**
|
||||
* The MQTT topic subscribed to receive birth and LWT messages from the MQTT device.
|
||||
* If `availability` is not defined, the binary sensor will always be considered `available` and its state will be `on`, `off` or `unknown`.
|
||||
* If `availability` is defined, the binary sensor will be considered as `unavailable` by default and the sensor's initial state will be `unavailable`.
|
||||
* Must not be used together with `availability`.
|
||||
*/
|
||||
availability_topic?: string;
|
||||
|
||||
/**
|
||||
* The string that represents the `online` state.
|
||||
* Default: "online"
|
||||
*/
|
||||
payload_available?: string;
|
||||
|
||||
/**
|
||||
* The string that represents the `offline` state.
|
||||
* Default: "offline"
|
||||
*/
|
||||
payload_not_available?: string;
|
||||
|
||||
/**
|
||||
* Information about the device this binary sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/device_registry_index/).
|
||||
* Only works when [`unique_id`](#unique_id) is set.
|
||||
* At least one of identifiers or connections must be present to identify the device.
|
||||
*/
|
||||
device?: {
|
||||
/**
|
||||
* A link to the webpage that can manage the configuration of this device.
|
||||
* Can be either an `http://`, `https://` or an internal `homeassistant://` URL.
|
||||
*/
|
||||
configuration_url?: string;
|
||||
|
||||
/**
|
||||
* A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`.
|
||||
* For example the MAC address of a network interface:
|
||||
* `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.
|
||||
*/
|
||||
connections?: Array<[string, string]>;
|
||||
|
||||
/**
|
||||
* The hardware version of the device.
|
||||
*/
|
||||
hw_version?: string;
|
||||
|
||||
/**
|
||||
* A list of IDs that uniquely identify the device.
|
||||
* For example a serial number.
|
||||
*/
|
||||
identifiers?: string[];
|
||||
|
||||
/**
|
||||
* The manufacturer of the device.
|
||||
*/
|
||||
manufacturer?: string;
|
||||
|
||||
/**
|
||||
* The model of the device.
|
||||
*/
|
||||
model?: string;
|
||||
|
||||
/**
|
||||
* The model identifier of the device.
|
||||
*/
|
||||
model_id?: string;
|
||||
|
||||
/**
|
||||
* The name of the device.
|
||||
*/
|
||||
name?: string;
|
||||
|
||||
/**
|
||||
* The serial number of the device.
|
||||
*/
|
||||
serial_number?: string;
|
||||
|
||||
/**
|
||||
* Suggest an area if the device isn’t in one yet.
|
||||
*/
|
||||
suggested_area?: string;
|
||||
|
||||
/**
|
||||
* The firmware version of the device.
|
||||
*/
|
||||
sw_version?: string;
|
||||
|
||||
/**
|
||||
* Identifier of a device that routes messages between this device and Home Assistant.
|
||||
* Examples of such devices are hubs, or parent devices of a sub-device.
|
||||
* This is used to show device topology in Home Assistant.
|
||||
*/
|
||||
via_device?: string;
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user