feat: handle battery replacement notifications from Z-Wave devices

[Copilot]

Z-Wave JS 15.10.0+ emits battery replacement notifications with urgency levels (Soon | Now) based on device-specific discharge characteristics. Previously logged as unknown errors.

Changes

Backend (api/lib/ZwaveClient.ts)

• Added batteryReplacementStatus to ZUINode type
• Store notification urgency when Battery CC notification received
• Auto-clear status when battery level exceeds 90%
• Exposed dismissBatteryReplacementStatus(nodeId) API method

Frontend (src/components/nodes-table/)

• Display orange mdiBatteryAlert for "Soon", red mdiBatteryAlertVariantOutline for "Now"
• Prioritize replacement status over normal battery percentage display
• Click battery icon to dismiss notification
• Enhanced RichValue.vue with onClick handler support

Behavior

// Notification sets status on node
node.batteryReplacementStatus = 'Now'  // or 'Soon'

// Auto-clears when battery recharged
if (node.minBatteryLevel > 90) {
  node.batteryReplacementStatus = null
}

// Manual dismissal
await dismissBatteryReplacementStatus(nodeId)

UI

Battery icons now indicate replacement urgency with appropriate colors and tooltips prompting user action:

Per spec: "Controllers SHOULD inform the user that the battery needs replacement each time the low-battery warning is received." Device manufacturers determine warning thresholds based on battery chemistry.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 224.0.0.251
  • Triggering command: REDACTED, pid is -1 (packet block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Unknown notification received CC Battery</issue_title>
<issue_description>### Checklist

• I am not using Home Assistant. Or: a developer has told me to come here.
• I have checked the troubleshooting section and my problem is not described there.
• I have read the changelog and my problem is not mentioned there.

Deploy method

Docker

Z-Wave JS UI version

11.3.1.3c9348d

ZwaveJS version

15.14.0

Describe the bug

Oct 03 09:27:40 zui[2693152]: 09:27:40.590 SERIAL « 0x012100a8000001000d139f03e900ad8c59c3f17b55b0d1c0f37ef006e600c6007 (35 bytes)
Oct 03 09:27:40 zui[2693152]:                       f7f82
Oct 03 09:27:40 zui[2693152]: 09:27:40.595 SERIAL » [ACK]                                                                   (0x06)
Oct 03 09:27:40 zui[2693152]: 09:27:40.597 DRIVER « [Node 013] [REQ] [BridgeApplicationCommand]
Oct 03 09:27:40 zui[2693152]:                       │ RSSI: -58 dBm
Oct 03 09:27:40 zui[2693152]:                       └─[Security2CCMessageEncapsulation]
Oct 03 09:27:40 zui[2693152]:                         │ sequence number: 233
Oct 03 09:27:40 zui[2693152]:                         │ security class:  S2_Authenticated
Oct 03 09:27:40 zui[2693152]:                         └─[SupervisionCCGet]
Oct 03 09:27:40 zui[2693152]:                           │ session id:      45
Oct 03 09:27:40 zui[2693152]:                           │ request updates: false
Oct 03 09:27:40 zui[2693152]:                           └─[BatteryCCReport]
Oct 03 09:27:40 zui[2693152]:                               is low: true
Oct 03 09:27:40 zui[2693152]: 2025-10-03 09:27:40.600 ERROR Z-WAVE: [Node 013] Unknown notification received CC Battery: { eventType: 'battery low', urgency: 1 }

To Reproduce

Have a device send a low battery notification.

Expected behavior

Event is handled.

Additional context

Notification added to driver in 15.10.0.</issue_description>

<agent_instructions>When a battery notification is received set a flag on node and show this on UI to warn user that the battery should be replaced. The user can dismiss this notification and the notification should be dismissed automatically when/if the battery level returns above 90%</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@robertsLando @AlCalzone Should I handle this notification or not? What kind of "valueId" should I create then? What are the possible values of args.urgency?

zwave-js-ui/api/lib/ZwaveClient.ts

Lines 5817 to 5847 in 7b0285f

	if (ccId === CommandClasses.Notification) {
	valueId.property = args.label
	valueId.propertyKey = args.eventLabel
	data = this._parseNotification(args.parameters)
	} else if (ccId === CommandClasses['Entry Control']) {
	valueId.property = args.eventType.toString()
	valueId.propertyKey = args.dataType
	data = isUint8Array(args.eventData)
	? utils.buffer2hex(args.eventData)
	: args.eventData
	} else if (ccId === CommandClasses['Multilevel Switch']) {
	valueId.property = getEnumMemberName(
	MultilevelSwitchCommand,
	args.eventType as number,
	)
	data = args.direction
	} else if (ccId === CommandClasses.Powerlevel) {
	// ignore, this should be handled in zwave-js
	return
	} else {
	this.logNode(
	zwaveNode,
	'error',
	'Unknown notification received CC %s: %o',
	valueId.commandClassName,
	args,
	)
	return
	}

</comment_new>
<comment_new>@AlCalzone
For reference, here's the explanation why it was done:
zwave-js/zwave-js#7984

The urgency is one of BatteryReplacementStatus.Soon | BatteryReplacementStatus.Now

I would actually not create a value ID for it. The whole point of this change was that it is meant to be a notification and not stateful.

Maybe we can show a badge on the battery level, yellow warning symbol for "soon", red alert symbol for "now"?
On click we could show a dialog explaining that the battery needs to be replaced soon/now, with a button to dismiss the warning state?</comment_new>
<comment_new>@robertsLando
What I do with notifications is to create a valueId object to be emitted with the event in both socket and MQTT, I don't create a real valueId. </comment_new>
<comment_new>@robertsLando
BTW I already show battery levels on UI, I don't know if this Is really necessary (I mean to handle it on UI side as well)</comment_new>
<comment_new>@robertsLando
@kpine This should be handled in latest release</comment_new>
<comment_new>@AlCalzone

BTW I already show battery levels on UI, I don't know if this Is really necessary

The point of these notifications is that each battery type is different. 20% might be fine for one kind of battery, but another one might drop off very steeply:

The device manufacturer knows the chemistry and
discharge characteristics of the battery but the controller does not. Thus the device chooses when the
user should be informed of the low battery condition. The device manufacturer may choose a battery
level of 20% for the low-battery warning point for a lithium battery which has a steep discharge curve
at end-of-life or 5% for alkaline cells which has a more linear discharge curve. The point where the
low-battery warning is sent is at the discretion of the device manufacturer. Controllers SHOULD
inform the user that the battery needs replacement each time the low-battery warning (0xFF) is
received.

Showing hints on the UI can help with this.</bo...

• Fixes Unknown notification received CC Battery #4396

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[coveralls]

Pull Request Test Coverage Report for Build 21359151708

Details

• 0 of 222 (0.0%) changed or added relevant lines in 3 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.2%) to 19.344%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
api/lib/ZwaveClient.ts	0	46	0.0%
src/components/nodes-table/nodes-table.js	0	55	0.0%
mock-server-configs/battery_simulation.cjs	0	121	0.0%

Totals
Change from base Build 21356024977:	-0.2%
Covered Lines:	4052
Relevant Lines:	22230

---

💛 - Coveralls

[robertsLando]

@AlCalzone thoughts on this?

[github-actions]

This pull-request is stale because it has been open 90 days with no activity. Remove the stale label or comment or this will be closed in 5 days. To ignore this pull-request entirely you can add the no-stale label