changelog Migracja silnika Z-Wave wersja 2.0 do 3.0. Zmiany w API

[K.Drozynski 131]

 

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

 

Planned release window:

- beta: `5.203`

- 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 [Appendix A](#appendix-a-supported-legacy-device-actions) 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:

 

```json

{

  "version": "3.0",

  "status": "set"

}

```

 

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:

```http

POST /api/devices/{deviceID}/action/startAddingDevices

```

 

ZW3:

```http

POST /api/zwave/nm/inclusions

Content-Type: application/json

 

{"networkWide": true, "allowS0": false, "allowS2": true}

```

 

### B) Set user code

 

ZW2:

```http

POST /api/devices/{deviceID}/action/setUserCode

Content-Type: application/json

 

{"args": [1, "1234"]}

```

 

ZW3:

```http

PUT /api/zwave/user_codes/15.0/codes/1

Content-Type: application/json

 

{"userCode": "1234", "userIdStatus": "AVAILABLE"}

```

 

### C) Set configuration parameter

 

ZW2:

```http

POST /api/devices/{deviceID}/action/setConfiguration

Content-Type: application/json

 

{"args": [2, 1, 0]}

```

 

ZW3:

```http

POST /api/zwave/configuration_parameters/15.0/2/value

Content-Type: application/json

 

{"value": 0}

```

 

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:

```http

POST /api/devices/{deviceID}/action/associationSet

Content-Type: application/json

 

{"args": [{"groupingId": 2, "singleChannel": [1]}]}

```

 

ZW3:

```http

POST /api/zwave/association_groups/15.0/2/associations

Content-Type: application/json

 

{"destinationNode": 1, "destinationEndpoint": 0}

```

 

## 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`