From 8ebbbea70100a47065e9530414ca3c18d8e42c83 Mon Sep 17 00:00:00 2001 From: Raman Gupta <7243222+raman325@users.noreply.github.com> Date: Tue, 30 Mar 2021 09:46:09 -0400 Subject: [PATCH] Add documentation for zwave_js.bulk_set_partial_config_parameters service (#17127) Co-authored-by: Franck Nijhof --- source/_integrations/zwave_js.markdown | 65 +++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/source/_integrations/zwave_js.markdown b/source/_integrations/zwave_js.markdown index abe5f86a0cd..b68ec215ca6 100644 --- a/source/_integrations/zwave_js.markdown +++ b/source/_integrations/zwave_js.markdown @@ -57,7 +57,7 @@ Advanced users: Make sure that the server started successfully by inspecting the ### Service `zwave_js.set_config_parameter` -This service will update a configuration parameter. At this time, it is not possible to update multiple partial parameters in a single call, but we hope to add support for that in the future. +This service will update a configuration parameter. To update multiple partial parameters in a single call, use the `zwave_js.bulk_set_partial_config_parameters` service. | Service Data Attribute | Required | Description | |------------------------ |----------- |------------------------------------------------------------------------------------------------------------------------------------------- | @@ -72,6 +72,7 @@ This service will update a configuration parameter. At this time, it is not poss Let's use parameter 31 for [this device](https://devices.zwave-js.io/?jumpTo=0x000c:0x0203:0x0001:0.0) as an example to show examples of different ways that the `LED 1 Blink Status (bottom)` partial parameter can be set. Note that in places where we are using different values for the same key, the different values are interchangeable across the examples. We can, for instance, use `1` or `Blink` interchangeably for the `value` in all of the examples. Example 1: + ```yaml service: zwave_js.set_config_parameter target: @@ -83,6 +84,7 @@ data: ``` Example 2: + ```yaml service: zwave_js.set_config_parameter target: @@ -94,6 +96,7 @@ data: ``` Example 3: + ```yaml service: zwave_js.set_config_parameter target: @@ -104,6 +107,66 @@ data: value: "Blink" ``` +### Service `zwave_js.bulk_set_partial_config_parameters` + +This service will bulk set multiple partial configuration parameters. Be warned that correctly using this service requires advanced knowledge of Z-Wave to use correctly. + +| Service Data Attribute | Required | Description | +|------------------------ |----------- |------------------------------------------------------------------------------------------------------------------------------------------- | +| `entity_id` | no | Entity (or list of entities) to set the configuration parameter on. At least one `entity_id` or `device_id` must be provided. | +| `device_id` | no | ID of device to set the configuration parameter on. At least one `entity_id` or `device_id` must be provided. | +| `parameter` | yes | The parameter number or the name of the property. The name of the property is case sensitive. | +| `value` | yes | Either the raw integer value that you want to set for the entire parameter, or a dictionary where the keys are the bitmasks (in integer or hex form) and the values are the value you want to set on each partial. Note that when using a dictionary, and bitmasks that are not provided will be set to their currently cached values. | + +#### Examples of bulk setting partial parameter values + +Let's use parameter 21 for [this device](https://devices.zwave-js.io/?jumpTo=0x031e:0x000a:0x0001:0.0) as an example to show how partial parameters can be bulk set. In this case, we want to set `0xff` to `127`, `0x7f00` to `10`, and `0x8000` to `1` (or the raw value of `4735`). + +
+ +When using the dictionary format to map the partial parameter to values, the cached values for the missing partial parameters will be used. So in examples 2 and 3, the service would use the cached value for partial parameters `0xff0000`, `0x3f000000`, and `0x40000000` because new values haven't been specified. If you send the raw integer value, it is assumed that you have calculated the full value, so in example 1, partial parameters `0xff0000`, `0x3f000000`, and `0x40000000` would all be set to `0`. + +
+ +Example 1: + +```yaml +service: zwave_js.bulk_set_partial_config_parameters +target: + entity_id: switch.fan +data: + parameter: 21 + value: 4735 +``` + +Example 2: + +```yaml +service: zwave_js.bulk_set_partial_config_parameters +target: + entity_id: switch.fan +data: + parameter: 21 + value: + 0xff: 127 + 0x7f00: 10 + 0x8000: 1 +``` + +Example 3: + +```yaml +service: zwave_js.bulk_set_partial_config_parameters +target: + entity_id: switch.fan +data: + parameter: 21 + value: + 255: 127 + 32512: 10 + 32768: 1 +``` + ### Service `zwave_js.refresh_value` This service will refresh the value(s) for an entity. This service will generate extra traffic on your Z-Wave network and should be used sparingly. Updates from devices on battery may take some time to be received.