Tool: Automatically Rename Z-Wave JS Devices in Domoticz

[Ragdag]

After moving to Z-Wave JS UI as the Z-Wave backend for Domoticz, I quickly noticed that Domoticz ends up with a lot of devices with very inconsistent names.
Manually renaming them all was way too much work, and worse:

• I ended up with devices having the same name, which completely broke my dzVents scripts (ask me how I know ).
• Device naming was chaos, making it harder to keep an overview.
• Smoke detectors didn't have a Reset button, motion sensors had wrong icons, etc.

So I created a PowerShell script to bring order to the chaos and harmonize all device names automatically.
GitHub: Rename-Domoticz-From-ZwaveJSON

What does it do?

• Reads your Z-Wave JS JSON export.
• Creates a consistent name for each Domoticz device:

  Code: Select all

  [Room Name] - [Device Name] - [Property Label]

• Applies renaming rules for common cases (Current Value, Watt/kWh, Temp, Lux, Motion, etc.).
• Fixes device types: Smoke detectors get a Reset button, motion sensors show the right icon, alert sensors can't be accidentally toggled.
• Preserves $ prefixes if you use those in Domoticz.
• Ensures no duplicate names, which is a lifesaver for dzVents scripting.
• Runs everything in a single transaction and makes a backup of your DB first.
• Generates an interactive HTML report with search/filter to review all changes.

screenshot.png (91.18 KiB) Viewed 2832 times

Examples
After running the script, devices look like this:

Code: Select all

Kitchen - Dining Table Light
Kitchen - Dining Table Light [kWh]
Kitchen - Dining Table Light [W]
Porch - Sensor - LED: Blink on Motion
Shed - Ventilation Hood - Heat Alarm
Driveway - Sensor - Lux
Driveway - Sensor - Temp

How to use
1. Stop Domoticz so there is no lock on the database.
2. Copy your domoticz.db to a safe working location where you will run the script.
3. Export your full Z-Wave JSON in Z-Wave JS UI:
General Actions → Dump → EXPORT
4. First do a dry run to preview changes:

Code: Select all

powershell
.\Rename-Domoticz-From-ZwaveJSON.ps1 -JsonFile "nodes_dump.json" -DbPath "domoticz.db" -DryRun

5. Check the generated HTML report to see what will be renamed.
6. If everything looks good, run without -DryRun to apply changes:

Code: Select all

powershell
.\Rename-Domoticz-From-ZwaveJSON.ps1 -JsonFile "nodes_dump.json" -DbPath "domoticz.db"

7. Copy the modified DB back to your Domoticz folder and restart Domoticz.

Note: This modifies your Domoticz database directly.
The script will create a timestamped backup automatically and generates an undo SQL script if you need to revert, but I still recommend making your own backup before use.

Hope this helps some of you who, like me, got lost in the sea of Z-Wave device names!

[Ragdag]

Update: quite a lot has changed since I posted this.

The script is now at v2.13.1 and there is proper documentation for it: Domoticz Device Renamer for Z-Wave JS. Short version of what is new:

No more manual JSON export
You can point the script straight at your running Z-Wave JS UI instance and it reads the node data live over its API. The General Actions → Dump → EXPORT step is optional now, and the data is always current:

Code: Select all

.\Rename-Domoticz-From-ZwaveJSON.ps1 -ZwaveJsUrl "http://zwave-host:8091" -DbPath "domoticz.db" -DryRun

Exporting a nodes_dump.json and using -JsonFile still works exactly as before, for when the instance is not reachable from where you run the script.

It runs on the Raspberry Pi now
The old PSSQLite dependency was x64-only. It has been replaced with Microsoft.Data.Sqlite, and a one-time setup script fetches the right native SQLite for your platform (ARM64, ARM, x64, Windows, macOS). So on the Pi itself:

Code: Select all

pwsh ./setup.ps1

That is a new required first step compared to the instructions in my original post. PowerShell 7.0+ is still the only other requirement.

If you have Central Scene remotes, please read this bit
This is the important one, and the reason to update if you ran an older version.

Domoticz stores a scene controller as one DeviceID with several Unit rows, one per key state. The script used to read one row but write with WHERE DeviceID = ..., which hit all of them. If you had named those units individually, a rename silently collapsed them all to the same name, reported "Collisions: 0", and the undo script had the same flaw so running it made things worse rather than better. That is fixed: every write and every undo statement is now scoped to a single row.

Since then the script also names each Unit row individually, reading the key states from Z-Wave and labelling them Short / Released / Held. That is a real improvement, but it means the script now renames devices you were already using, where before it left them alone. So: run with -DryRun first, read the report, and keep the undo script from the run. And if you have dzVents scripts looking devices up by name (the thing that bit me in the first place ), point them at the device idx instead, which never changes when the script renames something. More detail here: Multi-unit devices.

If the script cannot work out with certainty which Unit is which key state, it refuses to touch the device and reports it as Ambiguous rather than guessing.

Authentication is no longer a chore
If your Z-Wave JS UI requires a login, you no longer fetch a JWT by hand and paste it somewhere until it expires. Give it your username and it prompts for the password, then logs in itself and uses a fresh token for that run:

Code: Select all

pwsh ./Rename-Domoticz-From-ZwaveJSON.ps1 -ZwaveJsUrl "http://localhost:8091" -DbPath "domoticz.db" -ZwaveJsUser admin -DryRun

The password never reaches your shell history, the process list, the log or the HTML report.

The report explains itself

• Both old and new names are shown in full instead of just the last fragment.
• New Names Disambiguated section: when two devices want the same name, it now tells you which device is holding the one you wanted, whether Z-Wave JS still reports it, and when it was last updated. Usually the culprit is a stale Domoticz device left behind after a Z-Wave value moved endpoint, and deleting it and re-running is all it takes. Before, you just got a mysterious " - EP2" suffix with no explanation.
• Collision detection now checks a proposed name against the full end state, including devices that keep their name, so it can no longer create a duplicate.

Other bits

• It also renames the node-level device Domoticz builds for a node, like the combined Temp+Humidity device from a multisensor, which was never matched before.
• The bundled rule set is up to 41 rules, and rules can be scoped to specific hardware with nodeMatch (matching product label, description or manufacturer), so for example the Fibaro RGBW colour channel rules do not touch your ordinary dimmers.
• Database-in-use detection works on Linux and macOS now, not just Windows, and it names the process holding the file.

Updated how to use
The copy-the-database-out-and-back dance from my original post is no longer needed, and you do not have to stop Domoticz to preview:

1. Run pwsh ./setup.ps1 once on the machine you will run this from.
2. Dry run, with Domoticz still running. A dry run writes nothing at all, so you can point it straight at your live database:

   Code: Select all

   .\Rename-Domoticz-From-ZwaveJSON.ps1 -ZwaveJsUrl "http://zwave-host:8091" -DbPath "domoticz.db" -DryRun

   It will warn you that the database is open by Domoticz. For a preview that is expected and harmless, and it will not stop or prompt you.
3. Read the HTML report: check the rename list, and the Names Disambiguated section if there is one.
4. Now stop Domoticz, before applying anything. It caches device rows in memory and will happily write the old names back over your renames, and the new names do not show up in the UI until it restarts anyway.
5. Run the same command without -DryRun. It makes its own timestamped backup before touching anything.
6. Start Domoticz again.

The automatic backup and the undo SQL script are generated on every real run, and I would still take your own backup as well.

Full release notes for each version are on the releases page, and the code is where it always was: Rename-Domoticz-From-ZwaveJSON. Issues and suggestions welcome.