Custom capabilities
To understand the concept of ESPhome custom capabilities, you need to understand a few things, and constraints!
Picture taken from Homey Apps SDK
Athom BV (distributor of Homey) can sometimes be annoying to be honest ... They made the possibility to have several times "most" of the capabilities, but they "forgot" to allow filtering on them.
As a result, I implemented "context aware" cards (see below)!
When a capability is used several times, to distinguish each of them, Homey use an "index" => unique capability identifier
Let's say the capability "measure_temperature" is used twice in the same device. By default, they will be indexed as follow:
- measure_temperature
- measure_temperature.2
Note the ".2" suffix, it's important!
Actuallly, in Homey, the index can be a "name" instead of a number!
In ESPhome for Homey Wizard, you can set an index for all the capabilities, even if you use it only once. As such, the capability could be:
- measure_temperature.indoor
- measure_temperature.outdoor
It can be very practical from programming point of view. But from "user" point of view, it's still meaningless ...
In Homey, the name of the capability will be based on the capability "type" (ie. measure_capability). You will end up with a lot "Temperature" capabilities, which is disturbing!
And that's where "title" come to help In ESPhome for Homey application, you can also specify a title for each capabilities!
It will make it easier to distinguish the capabilities from each others from a "user" point of view.
Seriously Baldhor, why you annoy us with such concept!? Trust me, if I could avoid it, I would ...
Homey only handle "device" level cards (trigger, condition and action), the "capability" level need to be handled at execution time. At least that's true for "custom" cards, Homey itself is cheating for their own cards!
The end result is that all the custom cards will ask you to select the concerned capability:
This selection will ask you to select a capability by "title", so you should always set one in the Wizard
Maybe I should make it mandatory ...
Let's say you have a device which can be set to have a min temperature, a max temperature, and report a current temperature! You would expect to have all three inside the same UI component?
In Homey, the thermostat ui component is limited to a current temperature and a target temperature!
So in practice, to solve your need, you probably would do something like this:
- Make the native capability "current temperature" match with "measure_temperature"
- Make the native capability "current temperature" match with "measure_temperature" => Yes a second "measure_temperature"!
Let's talk about how Index will be important just after
- Make the native capability "min temperature" match with "target_temperature"
- Make the native capability "max temperature" match with "target_temperature" => Yes a second "target_temperature"
I think you got the point, to make "one" measure_temperature and "one" target_temperature appear on the same thermostat UI component, they must have the same "index". So actually, what you want is:
- measure_temperature.min
- target_temperature.min
- measure_temperature.max
- tartget_temperature.max
And you will obtain, 2 nice thermostat in your device, one for min, and one for max.
both will indicate the current temperature!
You still need to set some title to make it nice :)
But the key point in this use case was to use index to match measure_temperature and target_temperature together!
This capability can be used if the native capability is of type text and cannot be modified (read only).
You can use it if the native capability can be modified, but you want to make it forbidden.
It will appear like this on your device:
This capability can be used if the native capability is of type text and has a list of authorized values.
It will appear like this on your device:
This capability will be proposed only if I defined a capbaility with exactly the same values as the native capability!
In Homey, the values of an enum capability cannot be dynamic, it has to be implemented for each case (one by one ...)
It will appear like this on your device:
If you need a custom enum for your specific use case, you can open a Custom Enum Request
It will cost you a beer!
No idea why, but Homey doesn't propose those capabilities as a standard, so I added them ...
Those cards are compatible with ALL the capabilities (standard or custom)!
Those cards allows to:
- Select one of the device capability
- Select a value compatible with the selected capability
The values proposed will adapt to the context, and it works for all type of capabilities
It considers min, max, precision and step when they are configured!
- esphome_text_changed: new value is available as a token
- esphome_text_changed_to: trigger only if new value is (or isn't) the one expected
- esphome_text_condition: check if the current value match (or doesn't match) the condition
- esphome_text_setvalue: modify the current value
This one is only for test purpose
supported values: "one", "two", "three"
supported values: "1", "2", "3", "4", "5", "Automatic"
supported values: "Normal", "Powerful", "Quiet"
supported values: "auto", "low", "medium", "high", "quiet"
supported values: "auto", "left", "left_center", "center", "right_center", "right"
supported values: "Left", "Left/Center", "Center", "Center/Right", "Right", "Wide", "Spot", "Swing"
supported values: "off", "heat_cool", "cool", "heat", "fan_only", "dry"
supported values: "off", "both", "vertical", "horizontal"
supported values: "swing", "auto", "up", "up_center", "center", "down_center", "down"
supported values: "swing", "auto", "up", "up_center", "center", "down_center", "down"
supported values: "Up", "Up/Center", "Center/Down", "Down", "Swing"