Adding Abus Z-Wave Devices to Domoticz

Posted

Stock photo of a heating radiator, from https://www.pexels.com/photo/unrecognizable-handyman-with-ruler-near-heating-system-at-home-5691536/

If you’re using Domoticz with OpenZWave (rather than the MQTT-based Zwave-JS-UI), it’s comparably easy to add support for new Z-Wave devices. All Z-Wave device configurations are located in the Config/ subdirectory. A mapping between manufacturer IDs, device IDs, and device types of Z-Wave devices and the corresponding configuration files is stored in Config/manufacturer_specific.xml. Configuration files themselves are structured by manufacturer and stored in subdirectories such as Config/abus/, using one XML file per device.

Adding new devices is as simple as creating its XML configuration file, placing it in the correct directory, and adding an entry in the mapping file. These steps are shown below for two Abus Z-Wave devices (the SHHA10000 wireless socket and the SHLM10010 LED bulb) as well as the DONEXON Pro thermostat.

Important: Domoticz updates will overwrite any manual changes made to the OpenZWave configuration files. In order to retain your changes, either apply them manually after each update. Alternatively, set your configuration files to read-only mode so they cannot be overwritten.

Also, keep in mind to restart Domoticz after making changes to the configuration files, as they will only be updated during startup.

Abus Z-Wave Wireless Socket

Change into the Config/abus/ subdirectory of your Domoticz installation. There, create a file called SHHA10000.xml with the following contents that I have compiled from the documentation of the smart plug:

<!--
ABUS Z-Wave Wireless Socket SHHA10000
-->
<Product Revision="1" xmlns="https://github.com/OpenZWave/open-zwave">
  <MetaData>
    <MetaDataItem name="Name">ABUS Z-Wave Wireless Socket</MetaDataItem>
    <MetaDataItem name="Description">ABUS SHHA10000 Z-Wave Wireless Socket</MetaDataItem>
    <MetaDataItem name="OzwInfoPage">http://www.openzwave.com/device-database/0403:0003:0003</MetaDataItem>
    <MetaDataItem id="0003" type="0003" name="Identifier">ZC10-18116297</MetaDataItem>
    <MetaDataItem id="0003" type="0003" name="FrequencyName">CEPT (Europe)</MetaDataItem>
    <MetaDataItem id="0003" type="0003" name="ZWProductPage">https://products.z-wavealliance.org/products/3144/</MetaDataItem>
    <MetaDataItem name="ProductPic">images/abus/SHHA10000.jpg</MetaDataItem>
    <MetaDataItem name="ProductManual">
      https://products.z-wavealliance.org/ProductManual/File?folder=&filename=MarketCertificationFiles/3089/Anleitung%20SHRM10000%20EN.pdf
    </MetaDataItem>
    <MetaDataItem name="InclusionDescription">
      A.) Plug the Wireless-Socket into an outlet. The Status-LED is flashing.
      B.) Click the + (Add) button in your Z-Wave App and follow the further instructions
      C.) Press the Network-Button on the Socket once. The App will show if the Add device process was successful. The Status LED does not flash anymore but indicates if device is switched on or off. Repeat the inclusion process from step B if it was not successful.
    </MetaDataItem>
    <MetaDataItem name="ExclusionDescription">
      A.) Click the - (Remove) button in your Z-Wave App and follow the further instructions.
      B.) Press the Button on the socket 3 times. The App will show if the Remove Device process was successful. The Status-LED will now flash continuously. Repeat the exclusion process from step A if it was not successful.
    </MetaDataItem>
    <MetaDataItem name="ResetDescription">
      1. Keep pressing the Button on the socket for more than 5 seconds (the flash interval of the Status LED is now accelerated)
      2. The wireless socket is now restored to factory settings
    </MetaDataItem>
    <ChangeLog>
      <Entry author="toeeks.eu" date="13 February 2023" revision="1">
        Initial Metadata Import from Z-Wave Alliance Database - https://products.z-wavealliance.org/products/3144/xml
      </Entry>
    </ChangeLog>
  </MetaData>
  
  <!-- Configuration parameters -->
  <CommandClass id="112">
    <Value genre="config" index="1" label="Over current protection" max="1" min="0" size="1" type="list" value="1">
      <Help>Over current protection</Help>
      <Item label="function is disabled" value="0"/>
      <Item label="function is enabled (default)" value="1"/>
    </Value>
    <Value genre="config" index="2" label="Setting device status after power failure" max="2" min="0" size="1" type="list" value="0">
      <Help>Setting device status after power failure</Help>
      <Item label="Smart Plug memorizes its state after a power failure. (default)" value="0"/>
      <Item label="Connected device will be on after the power supply is reconnected." value="1"/>
      <Item label="Connected device will be off after the power supply is reconnected." value="2"/>
    </Value>
    <Value genre="config" index="3" label="Notification when Load status changes" max="2" min="0" size="1" type="list" value="1">
      <Help>Notification when Load status changes</Help>
      <Item label="function is disabled" value="0"/>
      <Item label="send basic report (default)" value="1"/>
      <Item label="Send Basic report only when Load status is not changed by Z-Wave command" value="2"/>
    </Value>
    <Value genre="config" index="4" label="LED Load indicator mode selection" max="1" min="0" size="1" type="list" value="0">
      <Help>LED Load indicator mode selection</Help>
      <Item label="The LED status follows the load change (default)" value="0"/>
      <Item label="when operating the load, the LED lights for 5 seconds and then turns off." value="1"/>
    </Value>
    <Value genre="config" index="16" label="Minimal Watt change to report" size="2" min="0" max="65535" type="int" units="watt" value="0">
      <Help>The value represents min. change in wattage (in terms of wattage) for a meter report to be sent (0=disabled)</Help>
    </Value>
    <Value genre="config" index="17" label="Minimal perent change to report" size="2" min="-128" max="127" type="int" units="percent" value="0">
      <Help>The value here represents minimum change in wattage percent (in terms of percentage) for a meter report (watt) to be sent (0=disabled)</Help>
    </Value>
    <Value genre="config" index="100" label="Reset reporting parameters" max="85" min="0" size="1" type="list" value="0">
      <Help>Setting the parameters 101-104 to the default value.</Help>
      <Item label="function is disabled" value="0"/>
      <Item label="Setting the parameters 101~104 to the default value." value="85"/>
    </Value>
    <Value genre="config" index="101" label="Watt report interval" max="2678400" min="0" type="int" size="4" units="seconds" value="0">
      <Help>setting time for sending meter report (watt) (0=disabled)</Help>
    </Value>
    <Value genre="config" index="102" label="kWh report interval" max="2678400" min="0" type="int" size="4" units="seconds" value="0">
      <Help>setting time for sending meter report (kWh) (0=disabled)</Help>
    </Value>
    <Value genre="config" index="103" label="Voltage report interval" max="2678400" min="0" type="int" size="4" units="seconds" value="0">
      <Help>setting time for sending meter report (voltage) (0=disabled)</Help>
    </Value>
    <Value genre="config" index="104" label="Current report interval" max="2678400" min="0" type="int" size="4" units="seconds" value="0">
      <Help>setting time for sending meter report (current) (0=disabled)</Help>
    </Value>
    <Value genre="config" index="254" label="Enable/disable the configuration command" max="1" min="0" size="1" type="list" value="0">
      <Help>Enable/disable the configuration command</Help>
      <Item label="unlock (default)" value="0"/>
      <Item label="lock" value="1"/>
    </Value>
  </CommandClass>
  
  <!-- Association Groups -->
  <CommandClass id="133">
    <Associations num_groups="1">
      <Group index="1" label="LifeLine" max_associations="1"/>
    </Associations>
  </CommandClass>
</Product>

At last, edit Config/manufacturer_specific.xml and insert a new line at the end of the Manufacturer tag for Abus (ID 0403). It is important that the manufacturer id as well as both the product id and the type fields match the ones of your Z-Wave device.

 <Manufacturer id="0403" name="ABUS Security-Center GmbH Co. KG">
    ...
    <Product config="abus/SHHA10000.xml" id="0003" name="Wireless Socket SHHA10000" type="0003"/>
 </Manufacturer>

After restarting Domoticz, the changes should become effective, and all supported configuration options be available on the Domoticz web interface. Once entering the device setup via Setup > Hardware, click the Setup button next to the entry of your Z-Wave stick, and select the corresponding devices in the list of nodes. Below the list of nodes, you will now see all available configuration options as well as a button to apply these changes to the devices.

Abus Z-Wave LED bulb

I have also extracted a configuration file for the LED bulb from its documentation. Save the following XML content as Config/abus/SHLM10010.xml.

<!--
ABUS Z-Wave LED Bulb SHLM10010
-->
<Product Revision="1" xmlns="https://github.com/OpenZWave/open-zwave">
  <MetaData>
    <MetaDataItem name="Name">SHLM10010 ABUS Z-Wave LED Bulb</MetaDataItem>
    <MetaDataItem name="Description">
      The ABUS Z-Wave LED Light Bulb is dimmable and provides warm white LED light (2700 K). The Bulb fits into any E27 socket and includes a repeater function for extending the range of the Z-Wave radio signal.
    </MetaDataItem>
    <MetaDataItem name="OzwInfoPage">http://www.openzwave.com/device-database/0403:0003:0002</MetaDataItem>
    <MetaDataItem id="0002" type="0003" name="Identifier">SHLM10010</MetaDataItem>
    <MetaDataItem id="0002" type="0003" name="FrequencyName">CEPT (Europe)</MetaDataItem>
    <MetaDataItem id="0002" type="0003" name="ZWProductPage">https://products.z-wavealliance.org/products/3136/</MetaDataItem>
    <MetaDataItem name="ProductPic">images/abus/shlm10010.png</MetaDataItem>
    <MetaDataItem name="ProductManual">
      https://products.z-wavealliance.org/ProductManual/File?folder=&filename=MarketCertificationFiles/3136/Anleitung%20SHLM100x0%20EN.pdf
    </MetaDataItem>
    <MetaDataItem name="InclusionDescription">
      A.) Screw the LED bulb into a standard E27 socket
      B.) Click the + (Add) button in your Z-Wave App and follow the further instructions
      c.) Turn the light-switch on. The App will show if the Add device process was successful and the LED-bulb will flash once. Repeat the inclusion process from step B if it was not successful.
    </MetaDataItem>
    <MetaDataItem name="ExclusionDescription">
      A.) Click the - (Remove) button in your Z-Wave App and follow the further instructions.
      B.) Switch the LED bulb on. The App will show if the Remove device process was successful. The LED bulb will flash once and then dim to 5%. Repeat the exclusion process from step A if it was not successful.
    </MetaDataItem>
    <MetaDataItem name="ResetDescription">Reset the device :
      a) Please use this procedure only when the network primary controller is missing or otherwise inoperable.
      b) Led bulb re-power 6 times (between 0.5-2 seconds each time); If the 6th power on, the led bulb flashes twice, which means that the resetting is successful.
    </MetaDataItem>
    <ChangeLog>
      <Entry author="toeeks.eu" date="13 November 2023" revision="1">
        Initial Metadata Import from Z-Wave Alliance Database - https://products.z-wavealliance.org/products/3136/xml
      </Entry>
    </ChangeLog>
  </MetaData>
  
  <!-- Configuration Parameters -->
  <CommandClass id="112">
    <Value genre="config" index="1" label="Temperature of NTC" max="255" min="0" size="1" type="byte" units="degrees" read_only="true" value="0">
      <Help>This parameter can only be read and not set.</Help>
    </Value>
    <Value genre="config" index="255" label="Reset" max="2290649224" min="0" size="4" type="int" units="" value="0">
      <Help>
        This parameter cannot been read, but only set.
        2290649224 = Reset to factory configuration and removed the Z-Wave network.
        2281701376 = Reset Configuration parameter to default value.
      </Help>
    </Value>
  </CommandClass>
  
  <!-- Association Groups -->
  <CommandClass id="133">
    <Associations num_groups="1">
      <Group index="1" label="Lifeline" max_associations="1"/>
    </Associations>
  </CommandClass>
</Product>

The line to add to Config/manufacturer_specific.xml in the Manufacturer section for Abus is:

 <Manufacturer id="0403" name="ABUS Security-Center GmbH Co. KG">
    ...
    <Product config="abus/SHLM10010.xml" id="0002" name="LED Bulb SHLM10010" type="0003"/>
 </Manufacturer>

DONEXON Pro thermostat

The DONEXON Pro thermostat shares its hardware platform with other Danfoss thermostats. As such, the existing configuration file Config/danfoss/z.xml can simply be reused. Thus, edit Config/manufacturer_specific.xml and insert a the following mapping in the Manufacturer section for Danfoss.

<Manufacturer id="0002" name="Danfoss">
  ...
  <Product config="danfoss/z.xml" id="a010" name="Donexon Radiator Thermostat" type="5fff"/>
</Manufacturer>

The timeout issue: If your thermostats are unresponsive and/or timeout errors appear in the Domoticz log, a further change to the Z-Wave USB stick configuration is needed. The minimum polling interval of DONEXON thermostats seems to be 60 seconds. However, unless the Z-Wave USB stick receives an acknowledgment of the setpoint change within 5 seconds (the default value), the setpoint change will time out and may not become effective.

The Z-Wave USB dongle configuration must hence be changed to use a timeout that is at least equal to the setting of the deployed thermostats. On the Domoticz web frontend, choose Setup > Hardware, click the Setup button next to the entry of your Z-Wave stick. In the list of nodes shown as a result, click the Controller (usually at ID 0x01) and adapt the RetryTimeout value to at least 60000 ms. Also, disabling the Assume Awake feature seemed to lead to fewer timeouts here. Of course, don’t forget to apply the configuration afterwards by clicking on the Apply configuration for this device button.