Add proper support for Battery CC "battery low" notification

[AlCalzone]

Related to: home-assistant/core#150898

zwave-js/zwave-js#7984 added a new "battery low" notification to fix an issue where Z-Wave JS incorrectly interpreted the corresponding command from a device. This notification used to overwrite the battery level with 0, even if the battery still had some power left.

Instead of a stateful "isLow" value, Z-Wave JS now exposes an event, similar to Notification CC and some other CCs. This event includes information whether the battery needs replacement soon or now: https://zwave-js.github.io/zwave-js/#/api/node?id=battery-cc

According to the Z-Wave specs,

Controllers SHOULD inform the user that the battery needs replacement each time the low-battery warning (0xFF) is received.

Not sure how other integrations handle this, but I think a dismissable repair issue could be a good way to handle this.

[marcelveldt]

@TheJulianJES assigned this one to you as its an ideal small one to dip your toes into the zwave integration

[TheJulianJES]

Not sure how other integrations handle this, but I think a dismissable repair issue could be a good way to handle this.

This is possible, but I wanna check how (many) other integrations open repairs for devices like this. I think they're more intended for general HA related issues. We may also wanna check with the HA team if "battery low" repairs are allowed, assuming no other integrations already do this.

Since you can't attach repairs to device entries, I'm pretty sure we'll also need to handle cleanup of the repairs ourselves when the device is removed, for example.
There's also no HA way of disabling certain repairs entirely, except to ignore them after they showed up. This could get spammy if there are a lot of Z-Wave devices with low battery, potentially even hiding other crucial repairs.

An alternative approach might be to use event entities. They would be created for all devices that previously provided the (removed) low_battery_level entity. We could call them something like "Low battery reported" or just "Low battery" (with a battery icon). The entity state would be the last date and time a "battery low" notification was emitted.
IMO, this is better than using repairs.

In ZHA, we emit some "notifications" via a zha_event in HA for things that most users don't need to act on, but still can via an automation listening to those events, similar to zwave_js_notifications. I don't think that's "enough" for this though.

[MartinHjelmare]

An event entity sounds good.

[MartinHjelmare]

Here's the current log message with the event details:

2026-01-09 13:20:18.329 INFO (MainThread) [zwave_js_server.model.node] Unhandled notification command class: BATTERY
2026-01-09 13:20:18.329 INFO (MainThread) [homeassistant.components.zwave_js] Unknown notification: {'source': 'node', 'event': 'notification', 'nodeId': 121, 'endpointIndex': 0, 'ccId': 128, 'args': {'eventType': 'battery low', 'urgency': 1}, 'node': Node(node_id=121)}

It can be useful for tests.

[AlCalzone]

The urgency will be one of these two values:

export enum BatteryReplacementStatus {
	Soon = 0x01,
	Now = 0x02,
}

[raman325]

is this in getAllNotifications? That's what we use to generate the notification constants, if this notification is missing from there then that explains why it's missing from the lib

[AlCalzone]

getAllNotifications is just for Notification CC, not notifications generated by other CCs.

[MartinHjelmare]

I think we only need to update the library and core. The event is sent as expected from the server what I can tell.