[hue] Apply status description if battery is low

[andrewfg]

This PR adds a Thing status description text when the thing has a low battery.

The consequence of a Thing status description text is as follows:

1. The status description text is displayed on the WebUI Thing detail page
2. A 'blue dot' decorator is added to the Thing status badge on the WebUI Things overview list (new WebUI feature).

It follows the analogy of #20498 where a Thing status description text is added to indicate availability of a software update.

Signed-off-by: Andrew Fiddian-Green software@whitebear.ch

[Copilot]

Pull request overview

This PR enhances the Hue binding to surface a low-battery indication via the Thing status description (which triggers the "blue dot" badge in MainUI), analogous to the software-update status feature added in #20498. When a battery-powered Hue device reports low battery, the Thing's ONLINE status description is set to a translatable "Battery level is low." text; it is cleared again once the battery recovers, but only if no other description (e.g., firmware update) is already in place.

Changes:

• Add new i18n key online.battery-low and constant TEXT_ONLINE_BATTERY_LOW.
• Call a new updateOnlineStatusDescription() from Clip2ThingHandler.updateChannels() whenever a DEVICE_POWER resource update arrives.
• Apply/clear the low-battery description only when the Thing is ONLINE, has the battery-low channel, and currently has no other description set.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
bundles/org.openhab.binding.hue/src/main/resources/OH-INF/i18n/hue.properties	Adds new online.battery-low translatable text.
bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/HueBindingConstants.java	Adds TEXT_ONLINE_BATTERY_LOW constant referencing the new i18n key.
bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/handler/Clip2ThingHandler.java	Adds updateOnlineStatusDescription() and invokes it from the DEVICE_POWER channel update branch.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[andrewfg]

@jlaur / @lsiepel I wonder if you can kindly comment on this enhancement? If this gets implemented then I would apply the same enhancement to other bindings with battery powered things e.g. homekit, zwave, zigbee, matter, hdpowerview, tado, neohub .. to name a but a few..

[lsiepel]

To be honest, I’m not very keen on the overall blue dot feature.

I wasn’t aware of the discussion before it was merged, but I would have shared my perspective if I had been. The meaning of the blue dot now feels ambiguous. For some entities, it means “has changed and can be saved”, like a configuration. For status-related things, it can mean firmware is available, and now also that the battery is empty. What comes next?

How do we handle concurrent states, for example when both firmware is available and the battery is low?

The openHAB domain models already allow alarm channels and/or trigger channels to signal these kinds of details. To me, that is sufficient. It allows users to subscribe to the events they are interested in by linking an item or rule to the channel.

Not saying we have to revert, but we need to have clear definitions and be sure this is the best implementation to support the use case. If the meaning and purpose the blue dot is to get the user's attention, like "something needs your attention" i would have suggested more something like a light yellow/orange dot with an exclamation mark.

[andrewfg]

The meaning of the blue dot now feels ambiguous

I think you are massively over thinking this. The blue dot is shown in the WebUI Things list overview. It is simply a marker that means "thing has (new) information". It simply invites one to click the Thing to see its Thing detail page where the respective information can be read.

/TLDR it is just a UI information..

PS note that you are talking about two / three different issues. The one is about whether to apply a thing status description text when there is new information. The second is whether to display a blue dot in the WebUI Thing list if such a text exists. And the third is what colour should the dot be .. I would have no problem to change it to (say) amber..

---

PS for the avoidance of doubt here is a table of the WebUI Things list..

Condition	Badge Color	Decoration
No handler, No bridge	Gray	-
Offline, Gone	Red	-
Interim states	Amber	-
Online	Green	-
Online plus Status Description	Green	Blue (but could be amber) dot

[andrewfg]

@lsiepel I changed the title and description of this PR to reflect what the PR is actually doing -- namely adding a Thing status description text when the battery is low.

To be clear this PR here is simply about adding a Thing status description text. This is an extra text that is displayed on the 3rd line of the Thing detail page in WebUI (see screenshot below). In other words, this PR is actually NOT directly related to applying a blue dot decorator to the Thing status badge in the WebUI Things overview list page (PR) so if you have objections to that function, or want to change its colour, you can of course open a separate issue in WebUI.

---

Referring to this screen shot above, this Hue PR would cause the following

1. top line Thing status is ThingStatus.ONLINE so (as before) it displays "ONLINE" within a green coloured badge.
2. second line Thing status detail is ThingStatusDetail.NONE so (as before) it displays nothing.
3. third line Thing status description is set so (new) it displays "Battery is low." (in i18n local language).

[lsiepel]

Thanks for pointing out the implementation details, but I’m aware of how it works.

I think you are massively over thinking this.

note that you are talking about two / three different issues. The one is about whether to apply a thing status description text when there is new information. The second is whether to display a blue dot in the WebUI Thing list if such a text exists. And the third is what colour should the dot be .. I would have no problem to change it to (say) amber..

I agree up to some extent that these are three separate issues, but they are also connected as you described.

1. Adding status description text for an ONLINE device is useful in some specific cases, but it is not commonly used. I also doubt it should be used to signal low battery for multiple reasons:
   • What is the definition / rule of thumb? Why use it for low battery, but not for fire alerts, tamper alerts, thermostat fault codes, or a washing machine running out of soap?
   • Duplicating information should be avoided. This information is already available elsewhere and in a more useful and structured way through channels.
   • Once we start mixing operational state with device telemetry/alerts, the semantics of Thing status become unclear and inconsistent across bindings.
   • Different bindings and developers will make different decisions on what deserves a status description, leading to fragmented UX behaviour.
2. I’m not against showing an indicator. It can be helpful to draw attention, but that also depends on the decisions made in point 1.
   • An indicator is most useful when it communicates a clearly defined and consistent category of information.
   • If status descriptions are used inconsistently across bindings, the indicator becomes noisy and loses meaning over time.
3. There is more to it than just the color:
   • It should be distinctive (or match) indicators already used in MainUI. I remember the blue dot as indicating unsaved configuration changes, but there may be more indicators.
   • The indicator itself should reflect the situation based on the choices made in point 1.
   • For example, a generic warning/alert indicator could justify an amber icon with an exclamation mark, while a lightweight firmware update hint might only justify a subtle yellow dot. Not saying it needs to eb dynamic, but rather that it aligns with the choices made in point 1.
   • Accessibility and recognizability also matter, relying on color alone is usually not ideal.

[andrewfg]

Adding status description text for an ONLINE device is useful in some specific cases, but it is not commonly used.

Yeah. There are about 20 bindings that do it. They generally use the status description to describe some particular nature or qualification of the actual Thing being "not quite perfectly online" such as 'online but still waiting for data', or 'online but via cloud connection' or 'online status limited due to pending software update' or as I now propose 'online status at risk due to low battery' etc.

Honestly I don't understand why you want to enforce stricter regulation of the status description now. It has always been up to binding designers to design their bindings to either provide such qualifier information or not. (Indeed if you would forbid it now for software available or low battery, you would probably need to go back over other bindings and forbid it also for some other (in your eyes) mis-uses. .. But why? Are you seriously thinking of that?

Personally I think it is a useful mechanism for binding designers to provide online qualifier information. And I see no reason why it should not be more commonly used. It is a fully confirmed and accepted capability of existing OH core and UI code.

I’m not against showing an indicator.
There is more to it than just the color

Ok. The recent current approach was simply to display the decoration dot if there is a status description text, and not display it if there is none. Just a binary advice "more information is available". Yet if I understand you correctly you are suggesting that the style of the decorator dot should be settable at run time. For example by adding a 4th field to the ThingStatusInfo class e.g. status, status detail, status description, plus (new) status description decorator style .. or something like that? e.g. Decorator.NONE, Decorator.INFO, Decorator.CRITICAL etc. This is not impossible but it would require deeper changes in OH Core and OH WebUI. => WDYT?

[andrewfg]

@lsiepel moving the discussion from OH Addons to OH Core openhab/openhab-core#5587
and OH WebUI openhab/openhab-webui#4211