Z-Wave
Driver: zwave
The Z-Wave page is the health dashboard for the mesh and the place you commission it: it shows whether the controller and every node are alive and communicating, audits every zone for a configuration that cannot work, and is where you pair (include) and remove (exclude) devices, turn nodes into GEM zones, and wire each zone's buttons and feedback to specific Z-Wave values.
Open Z-Wave
The page lives under Integrations > Z-Wave. It talks to a USB Z-Wave stick plugged into the GEM server — Aeotec Z-Stick, Zooz ZST10, Nortek/GoControl HUSBZB-1 and similar. One stick is one controller device in GEM; everything on this page acts on the controller in the strip at the top. A site with one stick lands on it directly; with more than one, a picker in the strip chooses.
Including a node does not create a zone, and creating a zone does not make it controllable. A Z-Wave zone works only after you have (1) created it with a node:endpoint address, (2) mapped each button to a Z-Wave value in Command Mappings, and (3) mapped each piece of feedback in Response Mappings. All three steps are on this page, and the sections below follow that order.
Before you start — the controller device
Add the stick as a device
Go to Devices and click Add (when no controller exists yet, the Z-Wave page's empty state offers an Add a controller link that opens the same device editor in a modal and selects the new controller once saved).
| Field | What to enter |
|---|---|
| Name | Lowercase name, e.g. zwave_controller. |
| Driver | zwave. |
| Type | Controller or hub. |
| Address | The serial path of the stick — /dev/ttyUSB0, /dev/ttyACM0, or a /dev/serial/by-id/... path. |
| Command Set | Required. Picking the driver auto-selects (and creates, on first use) a command set named zwave. |
| Status | On. |
| Elevated | Turn on only if everything on this stick is sensitive. Most sites leave it off here and set Elevated on the individual lock or gate zone instead, so lighting on the same stick stays available to ordinary roles. |
Address is the field the driver reads. The Device Attributes section also offers Serial Port (alt) (port), which is copied into Address when the controller connects — useful if a site already stores the path there. The Serial Path attribute in the same list is not used; leave it empty and put the path in Address.
On connect, the driver promotes a /dev/tty* address to its stable /dev/serial/by-id/... symlink so the controller survives replug and reboot reordering, and saves the new path back onto the device. If the configured path no longer exists (the dongle moved to a different USB port), it scans the by-id entries for a known Z-Wave descriptor — Silicon Labs HubZ -if00, Aeotec Z-Stick, generic Z-Stick, UZB, Zooz, Nortek, Sigma Designs — and points itself at the match. On a HubZ combo stick the -if00 interface is the Z-Wave radio and -if01 is Zigbee, which is why the match includes the suffix.
To switch this off, add a device attribute usb_auto_discover set to false. Worth doing only on a host with two identical Z-Wave sticks, where the wrong one could be picked up.
Security keys are minted for you
The first time the controller connects, GEM generates the four Z-Wave network keys (S0 Legacy, S2 Unauthenticated, S2 Authenticated, S2 Access Control) as random 32-character hex strings and stores them together in one encrypted, read-only device attribute named security_keys. You never type them in — the individual key fields listed under Device Attributes are not what the driver reads.
If that attribute is deleted or replaced, every already-included secure device (locks especially) has to be excluded and re-included. Node pairings live with the stick and its own cache on the GEM server, not in GEM's database — replacing or re-flashing the stick means re-including every node.
Zone verbs — what makes a button work
A Z-Wave zone's buttons reach the stick through the zone's command mappings. These verbs dispatch through the zone whenever the command names a zone on this controller — no command-set setup is needed:
| Verb | Typical use |
|---|---|
on, off | Switches, dimmers, outlets, fans |
level | Dimmer and shade position (also what the Light Dimmer slider sends) |
high, medium, low | Three-speed fans |
raise, lower | Ramping controls |
lock, unlock | Door locks |
open, close, pulse | Garage doors, gates, relay-driven loads |
To route any other verb through a zone's command map, set its row's Template to zone in the controller's command set. Rows already templated zone keep working exactly as before.
get_state and get_level read, they don't write: each reads the zone's Response Mapping for state / level live from the node (through its value map) and answers the value, or answers the zone's last known value when there is no response mapping for it. Leave them out of the command map.
Page layout
Three bands, top to bottom:
- Controller strip — the controller's name (click it to open the device record in a modal), a Connected/Disconnected badge that follows the driver's
connectedattribute live, the home ID, RF region, SDK version and node count, then the Enrollment, Removal, Refresh, Reload and Settings buttons. It stays above every tab so the state of the stick is never a click away. - Stat tiles — Controller, Nodes, Alive, Asleep, Dead, Interviewing, Zones and Zone Issues. Every tile is a shortcut: the node tiles open the Nodes tab filtered to that state, the zone tiles open the Zones tab.
- Tabs — Overview, Nodes, Zones, Diagnostics and Configure. The first four are the dashboard; Configure is the node → zone → mappings workflow described further down.
The dashboard is one round trip to the stick (get_network_health) plus the controller's zone rows. It refreshes itself every 30 seconds while the page is open, on every controller event, and on demand with Refresh in the strip. Nothing on the server depends on that timer — the driver's own node-status events and alarms run whether or not the page is open.
How GEM knows a node is alive
There is no connection to a Z-Wave node to be "up" or "down" — liveness is inferred from traffic, and the page shows the four signals zwave-js keeps:
| Signal | What it means |
|---|---|
| Status | Alive — the last frame exchanged with the node succeeded. Dead — a transmission got no acknowledgement; the stick marks the node dead and flips it back to alive on the next successful frame. Asleep / Awake — battery devices between and during their wake-ups; asleep is normal. Unknown — nothing exchanged since the driver started. |
| Last seen | The last time a command was received from or successfully sent to the node. A mains node quiet for a day, or a battery node quiet for a week, is the practical staleness test. |
| Statistics | Commands sent, received, dropped and timed out since the driver started, the average round trip, the average RSSI of frames from the node, and the last working route with its repeaters. Rising timeouts with a flat receive count means the node is reachable but marginal. |
| Ping | Sends a NOP and waits for the acknowledgement — proof for a mains-powered node. On a sleeping node the ping queues until the node next wakes, so it only answers when the device does. |
The response-map poll (see Feedback in below) reads values from the zwave-js value cache, not from the device. A dead node's zone attributes therefore freeze at their last values with no error. That is why the driver mirrors each node's status onto its zones as a node_status attribute, raises the standard zone_offline alarm on every zone of a node that goes dead, and clears it when the node answers again — see Alarms.
Controller strip
Enrollment, removal, reset
| Group | Button | What it does |
|---|---|---|
| Enrollment | Start | Puts the controller into inclusion mode after a confirmation prompt. Disabled while the controller is disconnected or already including or excluding. |
| Enrollment | Stop | Ends inclusion mode. Enabled only while inclusion is running. |
| Removal | Start | Puts the controller into exclusion mode after a confirmation prompt. |
| Removal | Stop | Ends exclusion mode. Enabled only while exclusion is running. |
| Refresh | Re-reads the health picture from the stick. | |
| Reload | Restarts the controller driver — GEM reconnects to the stick, pairings are kept. The same as reloading the device on the Devices page. | |
| Settings | Opens the controller device editor in a modal. |
The Reset Controller button (soft reset: disconnect, wait two seconds, reconnect — pairings kept) and Rebuild Routes live on the Overview tab. Toasts report each state change as it happens, and an inclusion or exclusion mode left running is flagged on the Diagnostics tab.
Enrolling a new device
- Click Start under Enrollment and confirm.
- Put the physical device into pairing mode (usually a triple-tap on the paddle or a small button — check the manufacturer's instructions).
- Wait for the pairing to complete. A toast names the node when it is added, and the dashboard refreshes on its own. A new node shows as Interviewing until the stick has finished asking it what it can do; battery devices only finish while awake.
- Click Stop when you are done adding devices.
The Start button runs the controller's default inclusion strategy. When a device asks GEM to grant security classes or to validate a DSK and enter the 5-digit PIN printed on the device, GEM records the request and carries on — it does not prompt you, so an S2 pairing that requires that confirmation will not finish. Devices that pair unauthenticated (most switches, dimmers, sensors) include normally.
If you need a specific strategy, run the start_inclusion command from the controller's Commands tab with a strategy argument of default, smart_start, insecure, security_s0 or security_s2 — see Maintenance commands below.
Removing a device
- Click Start under Removal and confirm.
- Trigger the exclusion sequence on the physical device.
- A toast names the node when it is removed and the dashboard refreshes.
- Click Stop to leave removal mode.
Exclusion works on devices that were paired to a different controller, so it doubles as a factory reset before re-enrolling gear pulled from another system. A node that is physically gone and cannot be excluded is removed with Remove on its row in the Nodes tab, which works only once the stick has marked it failed.
Overview tab
Four cards:
- Controller — serial path, home ID and the stick's own node ID, chip, SDK and firmware versions, RF region and Long Range capability, its role (primary, SUC, SIS), the zwave-js controller status (
ready,unresponsive,jammed) beside the inclusion state, and when the picture was last refreshed. - Serial Link — messages sent and received over the USB link, dropped messages, ACK/response/callback timeouts, NAK and CAN counts and the failure rate, all since the driver last started. Anything above a few percent points at the USB cable, hub or port rather than the mesh. When the stick reports it, the background RSSI per channel follows: the noise floor the stick hears with nobody transmitting. Below -90 dBm is quiet; above -75 weak nodes start to fail.
- Mesh — node counts by state and the average round trip, with Rebuild Routes (start/stop, with per-node progress while it runs) and Reset Controller.
- Health Summary — the counts of errors, warnings and information from the Diagnostics tab and the first five findings.
Nodes tab
One row per node on the mesh, the stick itself included and marked. Filter chips narrow the list to Alive, Asleep, Dead, Unknown, Interviewing (interview not yet complete) or No zone; the search box matches id, model, name, location and the labels of zones on the node.
| Column | What it shows |
|---|---|
| ID | The node id — the first half of every zone address on it. |
| Device | Manufacturer and model from the device configuration the stick matched, with the node's own name and location when set. |
| Status | Alive / Awake / Asleep / Dead / Unknown, and the interview stage underneath while it is incomplete. |
| Power | Mains, Battery or FLiRS (wakes on a beam), and whether the node routes for others. |
| Security | The highest security class granted at inclusion — S2 Access, S2 Auth, S2 Unauth, S0 or None. |
| FW | Firmware version. |
| Last seen | How long since the last frame; hover for the exact time. |
| RTT / RSSI | Average round trip and average signal strength of frames from the node. |
| TX / RX / T/O | Commands sent, received and timed out since the driver started. |
| Zones | The GEM zones addressed to the node — click one to open it in a modal. |
Ping and Configure sit on every row; Remove appears on a dead node. Click a row to expand it: identity details (manufacturer and product ids, protocol and Z-Wave Plus versions, endpoint count, capabilities), the communication counters, the last working route — direct, or the repeaters the frame hopped through, with the data rate and the ACK signal strength, and a note when a hop recently failed — plus Load neighbors (which nodes this one can hear; an empty list is a routing hole), the zones on the node with their mapped verbs and reported attributes, and Refresh Info (re-interview), Rebuild Routes (this node only) and Device Config (the configuration file the stick matched).
Zones tab
Every zone addressed to the controller, disabled ones included, with the node behind it and what has been mapped. The Health column is the audit; With issues filters to zones that cannot work as configured.
| Finding | Severity | Why it matters |
|---|---|---|
| address must be node:endpoint | error | The driver splits the address on the colon; without one the zone is never controllable. |
| same address as zone N | error | Two zones on one node:endpoint — the second silently shadows the first. |
| node N is not on the mesh | error | The address names a node the stick does not have. Excluded, failed-and-removed, or a typo. |
| node N is dead | error | Buttons fail and feedback is frozen. The node's own finding carries the actions. |
| node exposes endpoints 0–N | warning | The endpoint in the address is one the node does not have. |
| no command mappings | warning | Every button answers missing command map. |
| lock or security zone on a node paired with S0 / without security | warning | A lock, gate or garage zone whose node was included without S2 Authenticated or S2 Access Control. Re-include it with S2. |
| no response mappings | info | The zone reports no feedback. |
| zone is disabled | info | Skipped by the driver; its mappings are not audited. |
Configure on a row opens the Configure tab with the node and zone selected; Ping checks the node behind it.
Diagnostics tab
Every check the page runs, listed by severity with the action that fixes it where one exists. The checks re-run on each refresh and on every live node event.
Controller — disconnected; health query failing; zwave-js status unresponsive (offers Reset) or jammed; inclusion or exclusion mode left running (offers Stop); a route rebuild in progress; nodes still interviewing; the serial link failing more than 5% of messages; background RSSI above -75 dBm on any channel.
Nodes — dead (offers Ping, Rebuild Routes, Remove Failed); a mains node with unknown status (Ping); an incomplete interview (Refresh Info); not seen for over a day (mains) or a week (battery); more than a fifth of commands timing out (Rebuild Routes); average RSSI below -85 dBm; a recently failed hop on the last working route; an interviewed node with no zone (Configure).
Zones — every row of the audit table above, with Configure or Open.
Configure tab
Nodes panel
The left panel lists every node the controller knows about, as [node id] manufacturer description (a dead node is marked). The reload icon in the panel header re-reads the mesh from the stick. Configure on a row of the Nodes or Zones tab lands here with the node — and the zone — already selected. Nodes the controller has not yet interviewed show as Unknown with no description — reload after a minute, or run refresh_node_info for that node.
Click a single node to load it. The list allows multi-select, but only one node at a time can be configured; selecting more than one shows a warning and loads nothing.
Selecting a node reads its full value list from the stick, which is what fills the Endpoint and Command Class dropdowns, and lists the zones already created against that node.
Node Configuration panel
Zone Management
Existing Zones lists the zones already created on this controller whose address begins with the selected node id. Picking one loads its subsystem, endpoint and control type, locks those three fields, and reveals the Mappings tabs for that zone.
Open opens the selected zone's full editor — attributes, programming, history — in a modal, so the node selection and any mapping work in progress on this page survive the detour.
Delete removes the selected zone. It asks for confirmation first, then deletes the zone, every attribute on it (including its command and response maps) and every UI zone assignment pointing at it.
To create a new zone for the node:
| Field | What to enter |
|---|---|
| Subsystem | Required. The subsystem the zone belongs to — lights, shades, doors, climate, and so on. |
| Endpoint | Required. Pick from the endpoints this node actually exposes. Single-load devices have only 0; a two-relay module or a dual outlet exposes 1 and 2 as well. |
| Control Type | The zone control the UI should render — light_dimmer, light_switch, door_lock and so on. The list offers every control already in use on the site, and you can type a new one. |
Click Create Zone. GEM asks for the zone name, pre-filled from the node's manufacturer and model, and creates an enabled zone whose address is node:endpoint (for example 12:0) and whose device is this controller.
A Z-Wave zone address must be node:endpoint. An address without the colon is logged as invalid when the controller connects and the zone is never controllable. Zones created on this page always get it right; zones created by hand on the Zones page do not.
Command Class Configuration
This section is where you find the specific Z-Wave value behind a function, and test it before you map it.
Select the Endpoint first. The Command Class dropdown only lists values belonging to the endpoint chosen above it, so while Endpoint is empty the dropdown is empty too. Each entry reads [class number] Class Name property (endpoint n) — for example [38] Multilevel Switch currentValue (endpoint 0).
Choosing a value reads its metadata from the node, and the controls that appear depend on what came back:
Writable values get a Value box and a Test Set button. The box adapts to the value's type — a true/false dropdown for boolean, a list of named states for values with a state table (thermostat modes, lock modes), or a plain typed input for numbers and strings. Test Set writes the value to the node immediately.
Read-only values show Read-only value and a Test Get button, which reads the current value and prints it beside the label.
Test before you map. If Test Set does not move the load, the mapping will not either — that is a Z-Wave problem (wrong value, sleeping device, out of range), not a GEM one.
Mappings
The Command Mappings and Response Mappings tabs appear once a zone is selected under Zone Management. Between them they write the two things the driver needs to run the zone.
Command Mappings
A command mapping ties one GEM verb to one Z-Wave value plus the value to send.
- Select the Endpoint and then the Command Class value in the section above.
- If the value is writable, enter the Value to send for this verb —
99for a dimmer'son,0for itsoff, and leave it as-is forlevel, where the slider supplies the number. - Pick the Zone Command — the dropdown lists the zone verbs in this controller's command set, plus any other verb whose row carries the
zonetemplate. - Click Map Command.
Saved mappings appear under Mapped Commands as verb ← Class property value, each with two icons: the remote icon sends that verb to the zone as a live test, and the delete icon removes the mapping after a confirmation.
Numbers and true/false values typed into the Value box are converted to the type the node reported, so the map holds 99 rather than "99". Each saved entry also carries the value's metadata, which is what lets GEM clamp a slider: a level or setpoint argument above the value's own maximum is reduced to that maximum before it is sent. That is what keeps a UI slider sending 100 working against a Multilevel Switch, which tops out at 99 (255 on that class means "restore the last level", not "full").
Response Mappings
A response mapping ties one zone attribute to one Z-Wave value, so the zone reflects what the device reports.
- Select the Endpoint and Command Class value in the section above.
- Enter or pick the Attribute Name —
state,level,temperature,battery, and so on. The list offers every zone attribute name already in use; you can type a new one. - Turn Map Values on and use the Value Mapping editor to translate raw readings into the words the UI expects —
255→on,0→off,23→closed. - Click Map Response.
Saved mappings appear under Mapped Responses with their value translations underneath, each with a delete icon.
Map Response only completes while the Map Values switch is on — with the switch off the save does not go through and no toast appears. If a response mapping never shows up in the list, that is why. Leave the translation table empty if you don't need one; the switch itself is what matters.
How a mapped zone behaves
Commands out
Pressing a button on a UI, running a macro step or firing a trigger sends the verb to the zone. GEM looks the verb up in the zone's command map and writes the mapped value to the mapped Z-Wave value. It also records what it sent on the zone as an attribute named after the verb — a level command leaves a level attribute, an on command leaves an on attribute. Those are a record of the last command, not device feedback; feedback comes from response mappings.
Two error replies tell you exactly what is missing:
missing command map— nothing has been mapped for this zone at all.command not mapped— the zone has a command map, but not for the verb you pressed.
The node comes from the zone, not from the payload. A zone command takes its node and endpoint from the zone's own node_id:endpoint address, so a node_id argument sent alongside is overwritten rather than honoured — a benign zone's command map can never be applied to a different node on the mesh. This holds for every caller, macros and triggers included: the command map being applied belongs to the zone, so aiming it at another node would write one zone's value mapping to different hardware. Ordinary traffic is unaffected: a zone command has no reason to carry a node id.
When a payload does name a different node, the override is logged as "zwave: ignoring caller node_id … is node …" with both node ids. Macro step and script payloads are stored as JSON, so that log line is the practical way to find a saved automation still aiming at the wrong node — search Logging for it after a zone is re-addressed.
Feedback in
Feedback is polled, not pushed. Reports the device sends on its own are logged but do not update the zone. Instead, once the controller connects, GEM walks each zone's response map in turn — one value per second — reads each value from the zwave-js value cache (the stick's copy of what the device last reported, not a fresh query to the device), applies the value translation, and writes the result onto the zone attribute when it changed. The pass then repeats after the controller device's status_interval attribute in milliseconds, defaulting to 3000 (3 seconds).
Two consequences worth planning around:
- Add
status_intervalon a large mesh. With one read per second per mapped value, a stick with many mapped zones spends real time on each pass. Raising the interval on the controller device spaces the passes out. - Polling starts only when the controller connects. New response mappings stay dark until the controller reconnects. Finish the whole batch of mappings, then reload the controller device once from the Devices page.
- A dead node's feedback freezes rather than errors. The cache keeps serving the last values. Watch the zone's
node_statusattribute (written by the driver on every alive / awake / asleep / dead transition) or the zone_offline alarm the driver raises for every zone on a dead node — both are visible on the Zones tab.
open, close and pulse
open and close do not write a value directly — they are built for garage doors and gates driven by a momentary contact:
- GEM reads the zone's
stateattribute first and acts only when it disagrees with the request, socloseon an already-closed door does nothing. Ifstateis unknown, GEM goes ahead anyway. Mapstatein Response Mappings if you want that check to work. - The pulse itself sends the mapped value, waits, and sends it again. The wait comes from the verb's
delayargument in milliseconds; anything under 2000 is raised to 2000 to give an opener time to settle, and leaving it empty gives no wait at all — always supply a delay. - The zone attribute
normally_closedreverses the order of the two writes.
A shade motor is positioned, not pulsed. Map level for shades, and if the UI needs open/close buttons, set the zone's open_action and close_action attributes to re-dispatch level at 99 and 0. The AI assistant's shade profile below does exactly that.
Bulk node mapping with the AI Assistant
The Mappings tabs above save one entry per round trip — pick a node, refresh its value IDs, pick one, read its metadata, pick the verb, type the value, save; then do the response side. That is the right tool for one odd node. A single dimmer is five of those loops, a multisensor is more, and a typo in a value ID surfaces only as command not mapped when the button is pressed.
For a batch, the AI Assistant has a map_zwave_zones skill — the Z-Wave sibling of map_bacnet_points, map_modbus_points, map_mqtt_topics, map_knx_group_addresses and map_opc_ua_points. Include the nodes first (enrollment above), then describe them:
Map node 12 as the kitchen island dimmer, node 8 as the front door lock, and nodes 14 and 15 as the bedroom multisensors.
It creates (or updates) one zone per node on the controller, builds the node:endpoint address the driver requires (an address without the colon is never controllable), and writes both mapping attributes from a device-class profile:
| Profile | Command class | Commands | Reports |
|---|---|---|---|
switch | Binary Switch (37) | on / off | state |
dimmer | Multilevel Switch (38) | on / off / level | level, state |
fan | Multilevel Switch (38) | on / off / low / medium / high / level | level, state |
shade | Multilevel Switch (38) | level, plus open_action / close_action overrides | level, state |
lock | Door Lock (98) | lock / unlock | state (full lock-mode map), battery |
sensor | — | none (read-only) | from sensors |
What it handles for you:
- Levels are clamped at 99. The Multilevel Switch class tops out at 99 — 255 means "restore last level", not a position — so a UI slider sending 100 still works.
- The shade trap. Native
open/closego through the momentary pulse described above, which would never position a shade motor. The shade profile leaves those verbs out of the command map and wires the zone'sopen_action/close_actionoverrides to re-dispatchlevelat 99 / 0 instead. - Metadata on every command entry. Generated entries always carry the value's metadata, exactly as entries saved from this page do — that is what the clamping relies on.
- Extra telemetry. Any profile can add
sensorsshorthands — battery, temperature, humidity, illuminance, ultraviolet, motion, contact, tamper, leak, smoke, co, and the legacy Binary Sensor forms. Meter (class 50) power/energy must be given explicitly, because its property key is a computed code that differs per device — read it off the node's value list in Command Class Configuration. Battery is included by default on the lock and sensor profiles. - Validation before any write. The device must be a Z-Wave controller, node IDs must be 1-232, and duplicate
node:endpointpairs are rejected in-batch and against existing zones on the controller (two zones on one address means the second silently shadows the first). A mid-batch failure deletes every zone it created and restores every attribute it touched. It also warns when a mapped verb has no row in the controller's command set, or is not one of the zone verbs and its row has nozonetemplate — only those route into the driver's zone dispatch.
Reloading is deliberately different from the other point-mapping skills. Mapped zones are always reloaded, which is all a command needs — buttons work immediately. The controller itself is not reloaded unless you ask (reload_device), because the response pollers only start when the driver connects, and reloading a Z-Wave controller restarts the serial driver and re-interviews the mesh. The consequence: attribute feedback stays dark until the controller reconnects. Map the whole batch, then reload the controller once.
Ask for a dry run first whenever the assistant inferred profiles from node names — it returns the resolved address, profile, verbs and reports per zone and writes nothing. The cap is 60 zones per call. Inclusion itself stays on this page — the assistant maps nodes that are already on the mesh, it does not pair them. Per-node raw command_map / response_map entries can be passed for anything a profile doesn't describe, and merge over the profile output.
Maintenance commands
The page exposes inclusion, exclusion and soft reset. Everything else the controller can do runs from the controller device's Commands tab: open Devices, click the remote icon on the controller row, pick the controller in Test Device, then click the remote icon on the command row. Commands that take arguments open a form first; replies and device chatter appear in the Device Console below the grid.
| Command | Arguments | What it does |
|---|---|---|
get_nodes | — | Full record for every node: id, name, location, manufacturer, model, ready flag, status (numeric and named), interview stage, whether it sleeps, listens, routes or is the controller, security class, endpoint count, protocol, SDK and firmware versions, last-seen time and communication statistics. |
get_network_health | — | What the dashboard loads: get_controller_info plus get_nodes in one reply. |
get_controller_info | — | Home id, own node id, chip, SDK, firmware and API versions, role, RF region, Long Range support, zwave-js status, inclusion state, whether a route rebuild is running, node count, and the serial-link statistics with background RSSI. |
get_node_statistics | node_id | Status, last-seen time and the communication counters for one node — sent, received, dropped, timeouts, round trip, RSSI, last and next-to-last working routes. |
get_defined_value_ids | node_id | Every value the node exposes — the same list the Command Class dropdown is built from. |
get_value / set_value | node_id, value_id, value | Read or write one value directly. Elevated sessions only — see the note below. |
get_value_metadata | node_id, value_id | Type, range, writability and state table for one value. |
get_endpoints | node_id | Endpoint list with the command classes each one supports. |
get_node_config | node_id | The device configuration file the controller matched to this node. |
refresh_node_info | node_id | Re-interviews the node. Use on a node stuck at Unknown. Elevated sessions only. |
ping_node | address | Round-trip check against a node. address is node:endpoint or a bare node id. |
refresh_values | node_id | Re-reads every value the node reports from the device. Elevated sessions only. |
poll_value | node_id, value_id | Asks the node for one value now, bypassing the cached value get_value returns. Elevated sessions only. |
get_node_neighbors | node_id | Which nodes this one can hear — the practical way to find a routing hole. |
heal_node | node_id | Rebuilds routes for one node (zwave-js calls this rebuild node routes; the GEM name is kept). Elevated sessions only. |
start_healing_network / stop_healing_network | — | Rebuilds routes mesh-wide (rebuild routes in zwave-js). Run it after adding or moving mains-powered nodes, and expect it to take a while on a large mesh. Progress shows on the Overview tab. Elevated sessions only. |
remove_failed_node | node_id | Drops a node the stick has marked failed. Refused for a node that still answers or is merely asleep. Zones addressed to it stay behind. Elevated sessions only. |
start_inclusion | strategy | Inclusion with an explicit strategy: default, smart_start, insecure, security_s0, security_s2. Elevated sessions only. |
soft_reset_controller | — | Same as the page's Reset button — reconnects to the stick, keeps pairings. Elevated sessions only. |
hard_reset_controller | — | Wipes the stick. Every node must be re-included afterwards. Elevated sessions only. |
value_id is the ValueID object get_defined_value_ids returns, e.g. {"commandClass":38,"endpoint":0,"property":"targetValue"} — typed into a command field it is parsed from that JSON. set_value converts its value to a number or boolean when the value's metadata names that type.
get_value / set_value / poll_value name a node and a raw value_id with no zone in between, so no command map confines what they reach — that is the Door Lock write in its most direct form.
Controller lifecycle is gated the same way: start_inclusion, stop_inclusion, start_exclusion, stop_exclusion, start_healing_network, stop_healing_network, heal_node, remove_failed_node, refresh_node_info, refresh_values, toggle_radio, soft_reset_controller and hard_reset_controller. These change the mesh itself rather than any one zone, and nothing else confines them — the address rule has no address to check when the payload names no node, and most sites leave Elevated off on the controller so ordinary lighting on the same stick stays usable (see the device table above). So the command list is the only thing standing between a guest tablet and a factory reset that unpairs every lock on the mesh.
All of them answer not authorized: this command requires an elevated session for a non-elevated caller (a guest tablet, kiosk or PIN wall panel). Reads — get_nodes, get_network_health, get_controller_info, get_node_statistics, get_endpoints, get_node_config, get_node_neighbors, ping_node, get_value_metadata, get_defined_value_ids — and every mapped zone command are unchanged, as are macros, triggers, schedules and drivers. See Roles → Elevated devices and macros.
node_id is also treated as a hardware address by the central address confinement, so a non-elevated caller cannot aim a command at a node the account has no zone for.
Real-time updates
While the page is open it listens for controller events and reacts to them:
| Event | What you see |
|---|---|
| node_added / node_removed | Toast naming the node; the dashboard refreshes. |
| node_status | A node went alive, awake, asleep or dead. The row, the stat tiles and the zone audit update in place; a node going dead or coming back gets a toast. The driver also writes the zone attribute node_status and raises or clears the zone_offline alarm. |
| node_interview_completed / node_interview_failed | The dashboard refreshes, or an error toast names the node and the reason. |
| all_nodes_ready | Every node has finished its startup interview; the dashboard refreshes. |
| inclusion_started / inclusion_stopped | Toast; the enrollment buttons swap enabled state. |
| exclusion_started / exclusion_stopped | Toast; the removal buttons swap enabled state. |
| inclusion_failed / exclusion_failed | Error toast; the buttons reset so you can retry. |
| heal_network_progress / heal_network_done | Per-node progress on the Overview tab's Mesh card, then a toast when the rebuild finishes. |
| connected (device attribute) | The strip badge and the Controller tile flip; reconnecting refreshes the dashboard. |
These events are the same ones a macro or trigger can subscribe to on the controller device.
Troubleshooting
A node shows Dead
The stick sent it something and got no acknowledgement. In order:
- Ping it from the Nodes tab. A mains node that answers flips back to Alive on its own.
- Check power and range. A node that lost mains or moved out of reach looks exactly like this; Load neighbors on the row shows what it can hear.
- Rebuild Routes for the node once it is powered — its stored routes may run through a repeater that is gone.
- Only when the device is physically gone, Remove it. The stick refuses while the node still answers.
Every zone on a dead node shows the same finding on the Zones tab and carries an open zone_offline alarm until the node answers again.
Enrollment fails
- Confirm inclusion is actually running — Start was clicked and the toast appeared.
- Confirm the device is in pairing mode (manufacturer instructions).
- Move the device within about 30 feet of the controller for the initial pairing; you can relocate it afterwards.
- Exclude the device first, then re-enroll — this clears a pairing to a previous controller.
- If the device demands DSK/PIN validation, it will not finish from this page. See the secure-inclusion warning above.
The node list is empty or a node shows as Unknown
- Confirm the controller device is enabled and connected — the address must point at a serial path that exists.
- Click Refresh in the strip, or the reload icon in the Configure tab's Z-Wave Nodes header.
- Expand the node on the Nodes tab and click Refresh Info. Battery devices must be awake for this to succeed; press the device's button first.
A button does nothing, or the reply is an error
| Reply | Fix |
|---|---|
unknown command | The verb is not a zone verb and its row has no zone template, or the command's address names no zone on this controller. See "Zone verbs" above. |
missing command map | The zone has no command mappings yet. |
command not mapped | The command map has no entry for that verb — map it in Command Mappings. |
unknown zone address | The zone's address is not a node:endpoint pair on this controller. |
| Nothing at all | Test the value directly with Test Set. If that does not move the load, the mapped value is wrong for the device. |
Values are not updating
- Confirm the attribute is mapped in Response Mappings — feedback only comes from polling those entries.
- Reload the controller device. Response mappings added since the controller last connected are not being polled yet.
- Battery devices only answer while awake, so their attributes update on their own reporting rhythm rather than on the poll cycle.
- Check the value translation under Map Values — a raw reading with no translation is written through as-is, so a UI expecting
on/offwill not light up for255/0. - Confirm the attribute type matches what the device reports.
The device responds slowly or intermittently
- Expand the node on the Nodes tab: a high timeout count, a low RSSI, or a last working route through several repeaters says the link is marginal. Load neighbors — a node with no mains-powered neighbour is a routing hole.
- Check the Serial Link card on the Overview tab. Dropped messages and timeouts there are the USB link, not the mesh; a high background RSSI is interference at the stick.
- Rebuild Routes (Overview tab) after adding or moving mains-powered devices.
- Raise
status_intervalon the controller if a large mesh is being polled continuously. - Reset Controller if communication remains unreliable; it keeps pairings.
Related Documentation
- Devices - Z-Wave controller device configuration
- Zones - Zone configuration
- Command Sets - Zone command definitions and the
zonetemplate for verbs beyond the built-in zone verbs - Attributes - Editing zone and device attributes by hand
- AI Assistant -
map_zwave_zonesbulk node mapping