feat: support embedding Z-Wave JS UI in other software by AlCalzone · Pull Request #4520 · zwave-js/zwave-js-ui

AlCalzone · 2026-01-16T12:01:28Z

This PR adds support for embedding Z-Wave JS UI in other software, e.g. a Home Assistant addon.

In this mode, several settings are managed externally and will be unavailable in Z-Wave JS UI.

Controller port

Set using the env variable ZWAVE_PORT:

Security keys, RF and log configuration

Set using the env variable ZWAVE_EXTERNAL_SETTINGS

coveralls · 2026-01-16T12:07:26Z

Pull Request Test Coverage Report for Build 21627130537

Details

0 of 275 (0.0%) changed or added relevant lines in 4 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-0.2%) to 19.288%

Changes Missing Coverage	Changed/Added Lines	%
src/stores/base.js	7	0.0%
api/lib/ZwaveClient.ts	11	0.0%
api/app.ts	25	0.0%
api/lib/externalSettings.ts	232	0.0%

Totals
Change from base Build 21469973205:	-0.2%
Covered Lines:	4052
Relevant Lines:	22295

💛 - Coveralls

AlCalzone · 2026-01-16T12:43:01Z

Before merging, we need to delete the tarball again. I had to upload it for testing.

robertsLando

Apart from tarball the code changes look good to me 👍🏼

AlCalzone · 2026-01-30T13:59:51Z

Did a few more changes. Once we're ready to merge and release, I'll delete the tarballs again.

robertsLando

Changes look good. I'm wondering if in UI it makes sense to make inputs disabled instead of hiding them. WDYT?

robertsLando

would also be nice to mention this on docs somewhere

Copilot

Pull request overview

This PR adds support for embedding Z-Wave JS UI in other software (e.g., Home Assistant addon) by allowing external management of certain settings through environment variables and a JSON configuration file.

Changes:

Adds new externalSettings.ts module to load and merge external Z-Wave settings from a JSON file specified via ZWAVE_EXTERNAL_SETTINGS environment variable
Implements ZWAVE_PORT environment variable to force-enable Z-Wave and override the configured port, disabling serial port enumeration
Updates Settings UI to conditionally hide fields for externally managed settings using isSettingManagedExternally checks
Adds managedExternally array to frontend store to track which settings are managed externally

Reviewed changes

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

Show a summary per file

File	Description
api/lib/externalSettings.ts	New module providing functions to load external settings from JSON file, merge them into Z-Wave config, apply driver-only settings, and generate list of externally managed setting paths
api/lib/ZwaveClient.ts	Adds ZWAVE_PORT environment variable handling to force-enable and override port, and applies external driver settings after security key parsing
api/app.ts	Integrates external settings by merging them before ZwaveClient initialization, constructs managedExternally array for API responses, and skips serial port enumeration when ZWAVE_PORT is set
src/stores/base.js	Adds managedExternally state array and isSettingManagedExternally getter function to check if a setting path is externally managed
src/views/Settings.vue	Adds conditional rendering (v-if directives) to hide UI controls for externally managed settings across Z-Wave, security keys, RF configuration, logging, and Home Assistant sections; adds computed properties to check when all settings in a group are externally managed
.env.app.example	Documents new ZWAVE_PORT and ZWAVE_EXTERNAL_SETTINGS environment variables
api/lib/utils.ts	Removes outdated TODO comment about using ??= operator
package.json	Bumps version to 11.10.2-alpha.6

.env.app.example

api/lib/externalSettings.ts

src/views/Settings.vue

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

AlCalzone · 2026-02-03T10:25:23Z

@copilot add documentation for the new features in this PR to the end of the usage/setup section in the docs

Copilot · 2026-02-03T10:25:32Z

@AlCalzone I've opened a new pull request, #4533, to work on those changes. Once the pull request is ready, I'll request review from you.

Adds documentation for embedding Z-Wave JS UI in other software (e.g., Home Assistant add-ons) where settings are managed externally via environment variables. ### Documentation Added - **Controller Port Override** (`ZWAVE_PORT`): Force-enable Z-Wave and override configured port, disables serial port enumeration in UI - **External Settings Management** (`ZWAVE_EXTERNAL_SETTINGS`): Path to JSON file with externally managed driver/server settings, hides corresponding UI controls - **Supported External Settings**: Complete reference for all configurable settings: - Logging (UI + driver-only options) - RF configuration (region, auto power levels) - Storage settings (cache dir, throttle mode) - Security keys (S0, S2, Long Range) - Z-Wave JS Server configuration - Driver presets - **Example Configuration**: Real-world Home Assistant add-on setup with JSON structure ### External Settings File Example ```json { "logEnabled": true, "logLevel": "info", "rf": { "region": 0, "autoPowerlevels": true }, "securityKeys": { "S0_Legacy": "0102030405060708090A0B0C0D0E0F10", "S2_Authenticated": "2122232425262728292A2B2C2D2E2F30" }, "serverEnabled": true, "serverPort": 3000 } ``` Documentation placed at end of `docs/usage/setup.md` as requested.  --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey). --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: AlCalzone <17641229+AlCalzone@users.noreply.github.com>

robertsLando · 2026-02-03T10:46:40Z

@AlCalzone Lookd good to me, did you checked also #4520 (review) ?

AlCalzone · 2026-02-03T10:48:03Z

I had them disabled at first, but eventually decided to hide them completely. The settings felt unnecessarily noisy with all those disabled fields the user couldn't use at all.

feat: support setting controller port through env variable ZWAVE_PORT

563f681

AlCalzone requested a review from robertsLando January 16, 2026 12:01

fix lint

ca27955

AlCalzone force-pushed the external-port-setting branch 3 times, most recently from 4bc6ebd to 2b226db Compare January 16, 2026 12:38

AlCalzone added 2 commits January 16, 2026 13:44

fix: env variable name

f2cf243

test: check in tarball for installation tests

ec54863

AlCalzone force-pushed the external-port-setting branch from 2b226db to ec54863 Compare January 16, 2026 12:44

AlCalzone marked this pull request as draft January 16, 2026 19:33

AlCalzone changed the title ~~feat: support setting controller port through env variable ZWAVE_PORT~~ feat: support embedding Z-Wave JS UI in other software Jan 16, 2026

AlCalzone removed the request for review from robertsLando January 16, 2026 19:34

AlCalzone added 2 commits January 16, 2026 21:17

do not allow disabling Z-Wave controller if port is managed externally

33713af

fix formatting

660b647

robertsLando reviewed Jan 19, 2026

View reviewed changes

AlCalzone added 5 commits January 30, 2026 11:58

Support managing logging, RF settings and keys externally

28aa5a0

hide all externally managed settings

bf090b3

Optimize layout when setting are hidden

4b26925

externally manage Z-Wave JS Server settings

80ab783

fix: some settings weren't handled correctly

90e19f7

AlCalzone requested a review from robertsLando January 30, 2026 13:59

AlCalzone mentioned this pull request Jan 30, 2026

Include Z-Wave JS UI in the Z-Wave JS addon home-assistant/addons#4360

Draft

2 tasks

robertsLando approved these changes Feb 2, 2026

View reviewed changes

robertsLando requested a review from Copilot February 2, 2026 10:33

Copilot started reviewing on behalf of robertsLando February 2, 2026 10:33 View session

robertsLando requested changes Feb 2, 2026

View reviewed changes

Copilot AI reviewed Feb 2, 2026

View reviewed changes

.env.app.example Outdated Show resolved Hide resolved

api/lib/externalSettings.ts Show resolved Hide resolved

src/views/Settings.vue Show resolved Hide resolved

Update .env.app.example

061eb5f

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI mentioned this pull request Feb 3, 2026

docs: add embedding documentation to usage/setup section #4533

Merged

AlCalzone and others added 2 commits February 3, 2026 11:26

delete tarball

96966b6

robertsLando marked this pull request as ready for review February 3, 2026 10:45

Merge branch 'master' into external-port-setting

c6e951a

robertsLando merged commit 9b081cc into master Feb 3, 2026
12 checks passed

robertsLando deleted the external-port-setting branch February 3, 2026 10:53

Uh oh!

Conversation

AlCalzone commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Controller port

Security keys, RF and log configuration

Uh oh!

coveralls commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 21627130537

Details

💛 - Coveralls

Uh oh!

AlCalzone commented Jan 16, 2026

Uh oh!

robertsLando left a comment

Choose a reason for hiding this comment

Uh oh!

AlCalzone commented Jan 30, 2026

Uh oh!

robertsLando left a comment

Choose a reason for hiding this comment

Uh oh!

robertsLando left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlCalzone commented Feb 3, 2026

Uh oh!

Copilot AI commented Feb 3, 2026

Uh oh!

robertsLando commented Feb 3, 2026

Uh oh!

AlCalzone commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AlCalzone commented Jan 16, 2026 •

edited

Loading

coveralls commented Jan 16, 2026 •

edited

Loading