[Feature Request] Custom node labels (Name/Location/Notes)

[codersaur]

Version

matter-server/0.5.4 (matter.js/0.17.0-alpha.0-20260308-2d3759f3b)

Node.js Version

n/a

Operating System

Docker

Issue Description

It would be really useful if users could input text labels associated with each node (e.g. Name, Location, or General Notes). These could then be displayed in the Nodes list and network visualisations to make device identification easier. At present we just see Node ID, Manufacturer and Model name, which isn't that helpful when trying to track down one of a dozen "GRILLPLATS plug" for example. This would align with similar functionality in Zigbee2MQTT and ZWave JS UI, which allow Name and Location labels.

The labels do not need to sync with Home Assistant, though Zigbee2MQTT give you the option to sync names to HA so it may be worth looking at something similar.

Steps to Reproduce

N/A

Server Logs

N/A

Device Information

No response

Additional Context

No response

Pre-submission Checklist

• I am running an Alpha/Beta version of the Matter.js server
• I have included the complete server logs (not truncated)
• I have checked existing issues to avoid duplicates

[schildbach]

Fwiw, this would somewhat duplicate what you can do in Home Assistant. There you can assign custom names for devices, and entities, and even set up "proxy entities" (templates) just for setting a descriptive name.

[codersaur]

Fwiw, this would somewhat duplicate what you can do in Home Assistant. There you can assign custom names for devices, and entities, and even set up "proxy entities" (templates) just for setting a descriptive name.

It's useful to have in the MatterJS-Server Web UI as well, for the same reasons.

In fact, MatterJS-Server does already seem to support a basic NodeLabel, but it isn't very accessible and not shown anywhere useful.

[markvp]

Proposal: Dashboard-side Home Assistant Name Sync

I'd like to propose an approach for pulling device names from Home Assistant into the matterjs-server dashboard. Posting here for community/maintainer feedback before implementation, per the contributing guidelines.

Problem

When you have multiple identical devices (e.g. a dozen "GRILLPLATS plug"), the current display of NodeLabel || productName (serialNumber) isn't enough to tell them apart. HA users already assign friendly names via the HA device registry — we should be able to reuse those.

Proposed Approach: Browser-side Integration

The feature would be implemented entirely in the dashboard (browser-side), with zero changes to the server WS protocol — preserving full Python Matter Server API compatibility.

How it works:

1. User configures their HA URL + long-lived access token in a new dashboard settings dialog (stored in localStorage, like matterURL)
2. On dashboard load, the browser connects directly to HA's WebSocket API (/api/websocket), authenticates, and fetches the device registry via config/device_registry/list
3. Matches HA devices to matterjs nodes using the Matter device identifier format: ["matter", "deviceid_<compressed_fabric_id>-<node_id>-<endpoint>"]
4. Displays name_by_user (HA user-assigned name) where available, falling back to nodeLabel → productName as today
5. Names are cached in localStorage so the dashboard works even when HA is unreachable

Key design decisions:

• Dashboard-only — no server-side changes, no new WS commands, no protocol compatibility concerns
• Fully optional — feature is dormant unless user configures HA connection
• Graceful degradation — cached names used offline, falls back to existing behavior when unconfigured
• One-shot sync — connects, fetches, disconnects. No persistent connection to HA. Manual "Sync Now" button for refresh.

New dashboard files:

• ha-websocket.ts — minimal HA WS client (connect, auth, query, disconnect)
• ha-device-matcher.ts — matches HA devices to matterjs nodes via identifier parsing
• ha-name-store.ts — manages config, caching, and name resolution
• ha-integration-dialog.ts — settings dialog (HA URL, token, test connection, sync)

Modified dashboard files:

• header.ts — new menu item for HA integration settings
• matter-dashboard-app.ts — initialize store on startup
• network-utils.ts getDeviceName() — check HA names first in the name resolution chain
• matter-server-view.ts, node-details.ts — display HA names

Questions for Maintainers

1. Does a dashboard-only approach align with the project's direction? The alternative would be server-side integration (new WS commands, HA config in ConfigStorage), but that breaks Python Matter Server API compatibility.
2. Is the HA device identifier format deviceid_<fabric>-<node>-<endpoint> stable? This is what I've found in HA core — would appreciate confirmation from anyone running both.
3. Any concerns about storing the HA token in localStorage? This is a local-network tool, but happy to discuss alternatives (e.g. session-only storage).

Happy to submit a PR once there's alignment on the approach.

[markvp]

Update: How Other Systems Handle This

After researching how Zigbee2MQTT, ZWave JS UI, and HA add-ons handle device naming, the picture is quite different from what I initially proposed.

Zigbee2MQTT / ZWave JS UI: Push TO HA, not pull FROM HA

These tools do not pull names from HA. They work the opposite way:

1. Z2M has its own naming system — "friendly names" stored in Z2M's own config (configuration.yaml)
2. Users rename devices in Z2M's UI — the Z2M dashboard has rename functionality built-in
3. Optionally sync TO HA — when renaming with homeassistant_rename: true, Z2M publishes updated MQTT discovery messages that HA picks up and uses to update its device/entity registry

So the direction is always tool → HA, not HA → tool. The "source of truth" for names lives in the tool itself, and HA is a downstream consumer.

HA Add-on Model: Automatic Auth (Server-Side Only)

When matterjs-server runs as an HA add-on, the server process automatically gets a SUPERVISOR_TOKEN environment variable — no user configuration needed. The server could use this to query HA's API. However:

• This only works in the add-on scenario, not standalone Docker/native installs
• The dashboard frontend JS does NOT get automatic API access — ingress only provides user identity headers (X-Remote-User-ID, etc.), not auth tokens
• A server-side endpoint would be needed to proxy the HA API call to the dashboard

Revised Thinking

Given how the ecosystem actually works, there are two directions to consider:

Option A: Add custom naming to matterjs-server itself (like Z2M)

• Add a set_node_name / set_node_label WS command to store custom names server-side
• Dashboard gets rename UI (inline edit on node list, or in node details)
• Names stored in server-side config (alongside fabric label, etc.)
• Optionally write the name to the Matter NodeLabel attribute (0/40/5) on the device itself
• Future: optionally push names to HA (like Z2M's homeassistant_rename)

Option B: Pull names from HA (original proposal)

• Dashboard connects to HA WebSocket API to fetch device registry names
• Requires user to configure HA URL + long-lived access token manually
• OR: server-side proxy using SUPERVISOR_TOKEN when running as add-on (no config needed)

Option C: Both — custom naming in the dashboard (Option A) with optional HA sync in either direction as a future enhancement

Option A seems most aligned with how the ecosystem works, and addresses the core issue (#409) without requiring HA at all. Thoughts?

Sources:

• Zigbee2MQTT HA Integration
• HA Supervisor Authentication & Security
• HA Supervisor Proxy & Ingress

[codersaur]

Option A: Add custom naming to matterjs-server itself (like Z2M)

Option B: Pull names from HA (original proposal)

Option C: Both — custom naming in the dashboard (Option A) with optional HA sync in either direction as a future enhancement

Option A seems most aligned with how the ecosystem works, and addresses the core issue (#409) without requiring HA at all. Thoughts?

Option A is the only logical option in my view. Especially given Open Home Foundation Matter Server serves as the foundation to provide Matter support to Home Assistant but its universal approach makes it suitable to be used in other projects too. Matter Server should be the upstream "source of truth" and remain agnostic to any downstream consumers.

[markvp]

It's an interesting one. When you commission a device, you commission it in HA though. Most people would name it there during commissioning... so it would be intuitive if that name was also then synced to or available in Matter Server.

[codersaur]

When you commission a device, you commission it in HA though

...unless you commission a device directly in Matter Server... or in some other platform that is consuming the Matter Server API...

but yeah, I see your point. Option C may be the best compromise.