changelog Z-Wave engine 2.0 -3.0 Migration. Changes in API.

[K.Drozynski 131]

API Migration: Z-Wave 2 -> Z-Wave 3 

Planned release window:

• beta: 5.202
• GA: 5.210

The Z-Wave 2 -> Z-Wave 3 migration is available in the system. This document is intended primarily for integrators and explains how the API changes and how to safely update integrations.

1. What changes the most

• This document focuses on API differences that matter for external integrations (partner systems, middleware, custom applications).
• Most device actions retain backward compatibility — the majority of actions previously available through /api/devices/{deviceID}/action/{actionName} remain fully functional in ZW3. Integrations that rely on device actions for switching, dimming, thermostat control, color control, door locks, etc. will continue to work without changes. See 

  Please login or register to see this link.

   for the full list of supported actions.
• In ZW3, Z-Wave infrastructure and management operations are exposed as dedicated REST resources under /api/zwave/.... This includes: configuration parameters, associations, wake-up settings, user codes, firmware update, network management (inclusion/exclusion), and node diagnostics.   - The full OpenAPI specification for the new REST API is available via the built-in Swagger UI at /swagger/ — select the "ZwaveEngine Api" section, or navigate directly to /swagger/?urls.primaryName=ZwaveEngine+Api.   - New integrations should use the /api/zwave/... REST API wherever possible, as it provides richer functionality, structured responses, and better async operation support.
• In ZW3, asynchronous operations are explicit: process endpoints (/api/zwave/nm/..., /api/zwave/fw_update_processes/...) and mailbox endpoints (/api/zwave/mailbox/...).
• Device firmware update is available via two mechanisms in ZW3:   - /api/update-service/... — monitors the Fibaro/Nice update server for available official firmware updates.   - /api/zwave/fw_update/... — new in ZW3, allows uploading a firmware file directly to a device (CC Firmware Update Meta Data).

Important: After migrating from ZW2 to ZW3, all existing integrations should be reviewed for compatibility with the new API and re-tested. Refer to the comprehensive Swagger documentation (/swagger/) for the authoritative reference of all available endpoints, request/response schemas, and error codes.

2. How to detect the active engine

Use the endpoint:

GET /api/service/getZwaveEngine

Example response:

Please login or register to see this code.

Recommendation:

• if the engine is ZW2 -> use legacy paths,
• if the engine is ZW3 -> use /api/zwave/....

3. Key functional differences

3.1 Network management (adding/removing devices)

ZW2

• Most commonly handled through device actions, for example: startAddingDevices, stopAddingDevices, startRemovingDevices, stopRemovingDevices.

ZW3

• Inclusion:   - POST /api/zwave/nm/inclusions   - GET /api/zwave/nm/inclusions/{id}   - POST /api/zwave/nm/inclusions/{id}/cancel   - POST /api/zwave/nm/inclusions/{id}/grant_keys   - POST /api/zwave/nm/inclusions/{id}/accept_dsk
• Exclusion:   - POST /api/zwave/nm/exclusions   - GET /api/zwave/nm/exclusions/{id}   - POST /api/zwave/nm/exclusions/{id}/cancel

Important:

• in ZW3 this is a process model (start -> poll status -> completion).

3.2 Node operations (diagnostics, topology, interview)

ZW2

• Commonly action-based, for example: requestNodeNeighborUpdate, sendNodeInfo, wakeUpDeadDevice.

ZW3

• Nodes and details:   - GET /api/zwave/nodes   - GET /api/zwave/nodes/{node_id}
• Interview:   - GET /api/zwave/nodes/{node_id}/interview   - POST /api/zwave/nodes/{node_id}/interview   - POST /api/zwave/nodes/{node_id}/interview/cancellation
• Topology and connectivity:   - POST /api/zwave/nodes/{node_id}/ping   - GET /api/zwave/nodes/{node_id}/neighbors   - POST /api/zwave/nodes/{node_id}/neighbors/update   - GET /api/zwave/nodes/{node_id}/last_working_route   - POST /api/zwave/nodes/{node_id}/reachability
• Diagnostics:   - GET /api/zwave/nodes/diagnostics/transmissions   - DELETE /api/zwave/nodes/diagnostics   - DELETE /api/zwave/nodes/diagnostics/{node_id}

3.3 Configuration parameters

ZW2

• Parameter read/write is usually handled through device actions and device properties.

ZW3

• GET /api/zwave/configuration_parameters/{addr}
• GET /api/zwave/configuration_parameters/{addr}/{number}
• POST /api/zwave/configuration_parameters/{addr}/{number}/value
• POST /api/zwave/configuration_parameters/{addr}/{number}/default
• POST /api/zwave/configuration_parameters/{addr}/default
• POST /api/zwave/polling/configuration_parameters/{addr}/{number}

3.4 Associations

ZW2

• Associations are managed through legacy plugin endpoints under /api/apps/com.fibaro.zwave/..., for example:   - GET /api/apps/com.fibaro.zwave/nodes/{nodeId}/associationGroupInfo   - GET /api/apps/com.fibaro.zwave/nodes/{nodeId}/endpoints/{endpointId}/associationGroupInfo   - GET /api/apps/com.fibaro.zwave/nodes/{nodeId}/associations   - GET /api/apps/com.fibaro.zwave/nodes/{nodeId}/endpoints/{endpointId}/associations   - POST /api/apps/com.fibaro.zwave/nodes/{nodeId}/actions (set/add/remove/clear association operations)   - GET /api/apps/com.fibaro.zwave/nodes/{nodeId}/actions   - GET /api/apps/com.fibaro.zwave/nodes/{nodeId}/actions/{actionId}   - DELETE /api/apps/com.fibaro.zwave/nodes/{nodeId}/actions/{actionId}

ZW3

• GET /api/zwave/associations
• DELETE /api/zwave/associations/{id}
• GET /api/zwave/association_groups/{node_id}
• GET /api/zwave/association_groups/{addr}
• GET /api/zwave/association_groups/{addr}/{group_id}
• POST /api/zwave/association_groups/{addr}/{group_id}/associations

3.5 Wake-up (battery devices)

ZW2

• Most commonly handled through device actions.

ZW3

• GET /api/zwave/wake_ups/{node_id}
• PUT /api/zwave/wake_ups/{node_id}/configuration
• POST /api/zwave/polling/wake_ups/{node_id}
• mailbox:   - GET /api/zwave/mailbox/{node_id}/wake_ups   - POST /api/zwave/mailbox/{node_id}/wake_ups/clear

3.6 User codes (door locks)

ZW2

• Handled through actions such as setUserCode, setUserName, synchronizeUserCodes.

ZW3

• POST /api/zwave/user_codes/{addr}/synchronize
• GET /api/zwave/user_codes/{addr}
• GET /api/zwave/user_codes/{addr}/codes
• GET /api/zwave/user_codes/{addr}/codes/{user_identifier}
• PUT /api/zwave/user_codes/{addr}/codes/{user_identifier}
• POST /api/zwave/user_codes/{addr}/codes/{user_identifier}/clear
• POST /api/zwave/user_codes/{addr}/clear_all_codes
• PUT /api/zwave/user_codes/{addr}/master_code
• POST /api/zwave/user_codes/{addr}/keypad_mode

3.7 Device firmware update

In ZW3 there are two independent mechanisms for updating device firmware:

3.7.1 Update Service (/api/update-service/...)

The Update Service is a background process that monitors the Fibaro/Nice update server for available firmware updates for supported devices.

How it works:

1. The service periodically checks for available firmware — or on demand via POST /api/update-service/updates.
2. Devices with available updates are listed via GET /api/update-service/devices/.
3. To start an update, create a process via POST /api/update-service/processes (with {"deviceId": ...}).
4. Poll the process status via GET /api/update-service/processes/{deviceId} — statuses include Downloading, Queued, WaitingForWakeUp, InProgress (with progress stages), Completed, Failed, Stopped.
5. To stop an update, call POST /api/update-service/processes/{deviceId}/stop.

Endpoints:

• GET /api/update-service/devices/ — list devices with available firmware updates
• GET /api/update-service/devices/{deviceId} — get update info for a specific device
• GET /api/update-service/devices_count — number of devices ready to update
• POST /api/update-service/updates — force check for available updates from server
• GET /api/update-service/processes — list all update processes
• POST /api/update-service/processes — start new update process
• GET /api/update-service/processes/{deviceId} — get update process status
• POST /api/update-service/processes/{deviceId}/stop — stop update process

The full specification is available via built-in Swagger UI at /swagger/ — select the "UpdateService Api" section.

3.7.2 Firmware Update from file (/api/zwave/fw_update/...) — new in ZW3

ZW3 introduces the ability to upload a firmware file directly and apply it to a device. This is an implementation of the Z-Wave CC Firmware Update Meta Data command class.

How it works:

1. Query supported firmware targets via GET /api/zwave/fw_update/{addr} — returns the list of updatable firmware targets and their IDs.
2. Upload a firmware file via POST /api/zwave/fw_update/{addr}/{target}/request (multipart/form-data with manufacturerId, firmwareId, and the firmware binary).
3. Monitor the process via GET /api/zwave/fw_update_processes or GET /api/zwave/fw_update_processes/{id}.
4. If activation is required, trigger it via POST /api/zwave/fw_update_processes/{id}/activate.

Endpoints:

• GET /api/zwave/fw_update/{addr} — get firmware update info (targets, hardware version, activation support)
• POST /api/zwave/fw_update/{addr}/{target}/request — upload firmware file and start update
• GET /api/zwave/fw_update_processes — list all firmware update processes
• GET /api/zwave/fw_update_processes/{id} — get process status
• POST /api/zwave/fw_update_processes/{id}/cancel — cancel firmware update
• POST /api/zwave/fw_update_processes/{id}/activate — activate new firmware
• GET /api/zwave/fw_update_processes/{id}/activate — get activation status

3.8 Mailbox (pending actions for battery devices)

Battery-powered Z-Wave devices spend most of their time asleep and cannot receive commands. When a command is sent to a sleeping device, ZW3 stores it in a mailbox — a queue of pending actions that will be executed automatically when the device next wakes up.

How it works:

1. Send a command to a sleeping device (e.g. POST /api/zwave/configuration_parameters/7.0/2/value).
2. Instead of the usual 200 OK, the API responds with 202 Accepted and a JSON body containing the actionId:    json    {"actionId": 1}    
3. The pending action is now queued. You can inspect it via the mailbox endpoints.
4. When the device wakes up, all queued actions are executed automatically.
5. After execution, the actions are removed from the mailbox.

Mailbox endpoints per resource type:

• GET /api/zwave/mailbox/{node_id}/configuration_parameters — pending configuration changes
• POST /api/zwave/mailbox/{node_id}/configuration_parameters/clear — clear pending configuration changes
• GET /api/zwave/mailbox/{node_id}/associations — pending association changes
• POST /api/zwave/mailbox/{node_id}/associations/clear — clear pending association changes
• GET /api/zwave/mailbox/{node_id}/wake_ups — pending wake-up configuration changes
• POST /api/zwave/mailbox/{node_id}/wake_ups/clear — clear pending wake-up changes
• GET /api/zwave/mailbox/{node_id}/user_codes — pending user code changes
• POST /api/zwave/mailbox/{node_id}/user_codes/clear — clear pending user code changes
• DELETE /api/zwave/pending_actions/{action_id} — remove a specific pending action by ID

The mailbox has a configurable capacity. If the mailbox is full, the API returns an error.

Key integration point: Any endpoint that modifies device state may return 202 with an actionId for sleeping devices. Integrations should handle both 200 (executed immediately) and 202 (queued for wake-up) responses.

3.9 Polling (on-demand device state refresh)

Polling endpoints allow forcing an immediate state refresh from a device. This is useful when you need to ensure the locally cached state is up-to-date with the physical device.

All polling endpoints follow the pattern POST /api/zwave/polling/{resource_type}/{addr}/... and return:

• 200 OK (empty body) for mains-powered devices — the device was polled immediately.
• 202 Accepted with {"actionId": ...} for sleeping devices — poll request added to the mailbox.

Available polling endpoints (selected):

• POST /api/zwave/polling/configuration_parameters/{addr}/{number} — poll a configuration parameter
• POST /api/zwave/polling/binary_switches/{addr} — poll binary switch state
• POST /api/zwave/polling/multilevel_sensors/{addr}/{sensor_type} — poll sensor reading
• POST /api/zwave/polling/door_locks/{addr} — poll door lock state
• POST /api/zwave/polling/alarm_sensors/{addr}/{sensor_type} — poll alarm sensor
• POST /api/zwave/polling/binary_sensors/{addr}/{sensor_type} — poll binary sensor
• POST /api/zwave/polling/color_switches/{addr}/{component_id} — poll color component
• POST /api/zwave/polling/user_codes/{addr}/codes/{user_identifier} — poll user code
• POST /api/zwave/polling/wake_ups/{node_id} — poll wake-up configuration
• POST /api/zwave/polling/association_groups/{addr}/{group_id} — poll association group
• POST /api/zwave/polling/protection/{addr} — poll protection state
• POST /api/zwave/polling/sound_switches/{addr} — poll sound switch state
• POST /api/zwave/polling/window_covering/{addr}/parameters/{parameter_id} — poll window covering
• POST /api/zwave/polling/central_scenes/{addr} — poll central scene configuration
• POST /api/zwave/polling/schedule/{addr}/{block_id}/{schedule_id} — poll schedule entry
• POST /api/zwave/polling/basic/{addr} — poll basic value
• POST /api/zwave/polling/failed_nodes — poll failed nodes list

Refer to Swagger UI for the complete list of polling endpoints and their parameters.

4. ZW3 asynchronous model (what this means for integrations)

In ZW3, some operations do not return final state immediately. Integrations should:

• store the process identifier,
• poll the status endpoint,
• handle mailbox queue responses (especially for battery-powered devices),
• treat the operation as complete only after final status is returned.

5. Before/after examples

A) Start inclusion

ZW2:

Please login or register to see this code.

ZW3:

Please login or register to see this code.

B) Set user code

ZW2:

Please login or register to see this code.

ZW3:

Please login or register to see this code.

C) Set configuration parameter

ZW2:

Please login or register to see this code.

ZW3:

Please login or register to see this code.

For a sleeping (battery) device the response is 202 Accepted with {"actionId": 1} — the action is queued in the mailbox and will be applied on the next wake-up.

D) Add association

ZW2:

Please login or register to see this code.

ZW3:

Please login or register to see this code.

Appendix A: Supported legacy device actions

The following 101 device actions remain available in ZW3 via /api/devices/{deviceID}/action/{actionName} for backward compatibility.

Switching & level control

turnOn, turnOff, open, close, startLevelIncrease, startLevelDecrease, stopLevelChange, stop, step, pause

Brightness & values

setValue, setValue2, setBrightness, setVolume, poll

Color control

setColor, setColorComponents, setR, setG, setB, setW, startColorEnhancement, startColorFade, stopColorChange

Thermostat

setThermostatMode, setThermostatFanMode, setHeatingThermostatSetpoint, setCoolingThermostatSetpoint, setFurnaceThermostatSetpoint, setDryAirThermostatSetpoint, setMoistAirThermostatSetpoint, setAutoChangeoverThermostatSetpoint, setEnergySaveHeatingThermostatSetpoint, setEnergySaveCoolingThermostatSetpoint, setAwayHeatingThermostatSetpoint, setAwayCoolingThermostatSetpoint, setFullPowerThermostatSetpoint

Door lock

secure, unsecure, unsecureWithTimeout, unsecureInside, unsecureInsideWithTimeout, unsecureOutside, unsecureOutsideWithTimeout, setDoorLockMode

User codes

setUserCode, setUserCodeDec, setUserName, deleteUserCode, getUserCode, getMaxUsers, synchronizeUserCodes

Scheduling

setSchedule, setAllSchedules, removeSchedule, setOverrideSchedule, removeOverrideSchedule, setScheduleState

Node management

removeFailedNode, requestNodeNeighborUpdate, getNeighborList, getLastWorkingRoute, markDead, wakeUpDeadDevice

Protection

setProtection, setExclusiveControl, setTimeout

All Switch mode

switchAllOn, switchAllOff, switchAllGet, switchAllSetMode

Indicator

identify, indicatorGet, setIndicatorValue

Metering

reset, resetMeter, clearEnergyData

Configuration

setConfiguration, readWholeConfiguration

AV control

getSupportedCommands, sendAVControl

Window covering

setSlatsAngle, setFavoritePosition, configureFavoritePositions, startCalibration

Barrier operator

setAllSubsystems

Black box

getRecords, removeRecords

Sound switch

setTone, setDefaultTone, setArmed, setSequence, removeSequence

Device-specific

setDefaultPartyTime, startProgram, setRingsLightMode, setTamperMode, setAutoFanMode, setUnlockSequence, setLockKey, setIdleTimeout, configure