Is there any guidance on the preferred way to model a multi-speed fan

[lsiepel]

          @openhab/core-maintainers: is there any guidance on the preferred way to model a multi-speed fan (with discrete speeds between 0 and some number less than 100 - usually, between 2 and 10)? I see four options:

• As a Dimmer. This has the advantage of being able to accept ON/OFF commands, with ON restoring to the previous speed. A state description could theoretically provide a step value to make any sliders behave better (though I seem to recall that at least one of the UIs don't handle a step value on a slider very well). This is how my ZWave fan controllers present themselves, but I think that's just how ZWave handles it (multi-level switch control command class), and less a conscious decision on the part of the openHAB ZWave binding, or zwave-js. It's also how HomeKit handles Fan accessories (you can set min/max on it to limit to discrete speeds, but it gets weird in the UI sometimes, and Siri's spoken interpretation pretty much assumes percentages). There can also be weirdness with a Dimmer - my ZWave fan controllers are 4 speed, but because ZWave presents it as 0-99 (and 100 is return-to-previous-value), speed 1 is 24.24%, speed 2 is 49.49%, speed 3 is 74.75%, and speed 4 is 100%. This PR essentially implements this option. For myself, I like the discrete numbers, and have rules to maintain number items calculated from the dimmer items, and use the number item for my UIs.
• As a Number. 0 is off, and speeds map directly - 1, 2, 3 etc. This could be harder to expose to some UIs, especially HomeKit. You also have no way to send a command turning it on returning to whatever speed it previously was.
• As a Number and a Switch. This duplicates things slightly, but gives you an ON command. This is how #17681 that I'm working on currently models it for WiZ devices (as it's a direct mapping from the underlying API). This also matches most closely with how Home Assistant's discovery information for MQTT models it. Though I get the impression Home Assistant itself maps it to something more closely resembling a Dimmer. It is a little unclear if the Number should go to 0 when the fan is off, or if it can be used to always show the what the speed would return to when it gets turned back on.
• As a Number and a Dimmer. This would give the most flexibility, but with the most duplication of information. Use the Dimmer when you need something that deals better with percentages. Use the Number when you want something that better deals with discrete speeds.

The latter two have a little bit of precedent when dealing with a light bulb that supports dimming (or color) and color temperature. My experience with those things is it can be very inconsistent if the color temperature channel goes to NULL or UNDEF when the light is OFF, or if it stays at its previous value (and what it would return to if it turns back on). It's also inconsistent if sending a command to the color temperature channel will turn the bulb on if it's currently off.

In a slightly different way, there is precedent with color temperature to model as a Dimmer and a Number.

So... thoughts?

All of these questions could probably use some explanation and reasoning in the FAQ at https://www.openhab.org/docs/developer/addons/faq.html#modelling-channels.

Originally posted by @ccutrer in https://github.com/openhab/openhab-addons/issues/17813#issuecomment-2505109193

[andrewfg]

TLDR think of DynamicStateDescriptionProvider providing state options for the channels.

Long version: Have a look at the tado binding which I think does this quite well. Its speciality is that the tado a/c thermostats can talk to a/c units from a huge range of manufacturers. And as you know different a/c manufactures do multi speed fans in multiple different ways .. ranging from the "classic" LOW/MEDIUM/HIGH to more "exotic" ones with (e.g. ECO, SILENT, BOOST, TURBO etc.).

On start up, the tado binding asks the thermostat for its range of state options (SILENT/LOW/MEDIUM/HIGH/TURBO or whatever) and it creates a DynamicStateDescriptionProvider component that provides those particular state options for the respective fan speed channel.

[ccutrer]

If I'm reading you right, the more exotic ones are an argument for Number (or even String, in the case of Tado) channels, with descriptions for each option. I don't think a DynamicStateDescriptionProvider really factors in to this - some bindings may be dynamic, while some bindings are static and can just put the information in the thing type XML.

But you bring up something I don't normally think of - when I say "fan" I'm referring more to "ceiling fan" or "exhaust fan", and less "blower in an air circulation system, connected to a thermostat". I think the latter is more likely to have the exotic modes, though the Wiz binding is definitely for ceiling fans, and has a "Breeze" mode (separate from numeric speed control).

I think my preference would be:

• If it's a fan of any types that supports discrete unnamed or generic speeds (off/low/medium/high, 0-6, etc.) that have a clear progression, model it as a Number (possibly with a state description giving the speeds names) and a Dimmer. One of the two should probably be marked as advanced - I don't have a preference for which. 0 should always be "off", even if the device itself controls power separately.
• If it's a fan that is simply 0-100%, clearly it's just a Dimmer. This would include devices like Zwave ceiling fan controllers that don't communicate what discrete speeds are actually available.
• If it's a fan that is simply on/off, clearly it's just a Switch (though could possibly be a degenerate case of the following category, so a String or a Number is also acceptable)
• If it's a fan that supports "exotic" modes such as Auto, Breeze, Eco, etc. that are not a clear progression, model it as a Number or a String, with a state description giving the enumeration of allowed options. A separate Switch channel that controls power (setting to ON will restore the previous state) is allowable if the device supports it (some devices may not support returning to the previous state, and others may not support directly turning the fan off - many thermostats it's either "On (continuously)" or "Auto - when the heating or cooling system is running"). If "off" makes sense at all, it should be one of the options on the enum channel, and not only accessible from a Switch channel.

[andrewfg]

I would model a multi speed fan as a string with multiple state options (which can as you say be modelled either statically in the state options xml, or dynamically via a state description provider.