Integration with Z-Wave devices

Owned by Robin Rainton
Last updated: 12.02 2020Version comment
8 min read

Loxone do not supply a Z-Wave extension but sometimes it may be desirable to integrate with such devices.

This How-To describes the simple case of using Z-Wave wireless window/door sensors with Loxone, but the principles will be similar for other sensors or actuators.

Why?

The author's requirements were to add wireless window/door sensors in their installation in the most unobtrusive and cost effective way possible. Loxone do supply wireless window/door sensors but as an cost comparison for an example 10 sensor installation:

  1. Loxone Air Extension + 10 x Loxone Door & Window Contact Air costs around 800€

  2. Raspberry Pi kit (inc. case, SD card, PSU) + Z-wave.Me UZB + 10 x Coolcam Neo DS01Z window sensors costs around 230€

For the record, the Coolcam Neo DS01Z have similar specifications to the Loxone Door & Window Contact Air, and some may say the Coolcam product is more aesthetically pleasing. There are, or course, many other Z-Wave options for those with different needs or tastes. And of course, a Raspberry Pi in your installation can do much more than just act as a bridge for this one purpose. In fact, the author was already using one so in this instance it's 'cost' was 'free'.

Materials

You will need:

  1. At least one Z-Wave sensor or actuator (example uses Coolcam Neo DS01Z window sensors).

  2. A Z-Wave USB stick (the author chose a z-wave.me UZB).

  3. PC or SBC (eg. Raspberry Pi) to act as a Z-Wave Bridge.

Step by Step Instructions using ioBroker

ioBroker is now the author's preferred choice of software for the Z-Wave bridge as it appears slightly easier to configure and as this has an object hierarchy that is similar to Loxone's periphery will likely be more familiar to Loxone users.

Moreover, ioBroker has a Loxone adapter so can communicate directly with your Loxone Miniserver to both read and write values immediately. Therefore, feedback from Z-Wave sensors using this method is not only instant (rather than polling a virtual input) but also requires easier configuration.

Setup in Loxone

In order to feed the state of external sensors into Loxone it is necessary to setup Virtual Inputs. The ioBroker Loxone adapter (see below) works by connecting to the Loxone web interface with a given username & password. It is recommended to create a separate user specifically for this interaction and make sure only the Virtual Inputs of interest are visible to this user.

In the case of this example using door sensors:

  1. Create a new user and user group (the name 'iobroker' is proposed).

  2. Create 1 or more Virtual Inputs for each Z-Wave door sensor. For such sensors a simple on/off switch type is useful.

  3. Be sure to configure the Loxone access controls for these sensors so that only the 'iobroker' user can see and modify them and that no other users can. Place them in an appropriate room & category and check the appropriate configuration option so these Virtual Input switches are visible in the Loxone user interface.

  4. Verify the above configuration is as required by logging into the Loxone web interface with the 'iobroker' user.

Setup the Z-Wave Bridge

In this example we are going to use a Raspberry Pi as a Z-Wave bridge. In theory any PC or SBC that has a spare USB port, runs ioBroker and has LAN connectivity to your Loxone Miniserver will do.

  1. Gather your materials (hardware).

  2. Plug the Z-Wave USB key into the Raspberry Pi and after installing your distribution of choice, check it has correctly loaded the driver. Ie. check for presence of /dev/ttyACM0 or similar.

  3. Install the ioBroker package, Z-Wave adapter and Loxone adapter. It is beyond the scope of this How-To to discuss this, please follow the relevant installation instructions. Be sure to configure the Z-Wave adapter with the correct USB device (/dev/ttyACM0 or similar).

  4. The Z-Wave and Loxone adapters perform auto-discovery and should create objects for both the Z-Wave devices and the Loxone Virtual Inputs that were configured above. Using the 'Objects' list in the ioBroker admin interface verify this.

  5. If this is the first time pairing Z-Wave devices then use the Z-Wave adapter's settings screen to add (pair) your nodes. NB: If nodes are already paired then it may take some time for them to 'wake up' and become fully registered with the adapter (this is dependant on the wake-up time configured for each node). At this point it would also be useful to go through the Z-Wave objects and assign them useful names so they are easier to identify in the next steps.

  6. The final step is to connect the Z-Wave sensors so they update Loxone Virtual inputs. For this the ioBroker Javascript adapter is required. This may sound more daunting than it really is - this adapter allows scripts to be created using a drag-and-drop 'blocky' interface similar to the Loxone Config software, or, for more advanced users, code can be written in pure Javascript.

    1. Install the ioBroker Javascript adapter.

    2. Create a new ioBroker script then drag and drop the relevant blocks to have any change in specific Z-Wave objects reflected in the Loxone Virtual Input objects. It is assumed that those wanting to code directly in Javascript will know how to do this. For the the less technical, this connection is achieved using the 'bind' System block:

    3. In the example door sensor, 2 'bind' blocks are required for each one - one for the actual door state, and one to show the battery level in the Loxone interface. For each block, insert the Object ID of the Z-Wave input in the left hand box, and the Object ID of the Loxone Virtual Input to be updated in the right hand one. After creating such blocks for several door sensors, the script appears as below:

    4. Save the script and make sure the Javascript adapter is running, and this newly created script is running too (there should be a 'pause' symbol next to it's name in the list of scripts, indicating, if it can be paused, that it should be running).

And that is is. You should now have the status of Z-Wave sensors communicated to Loxone Virtual Inputs. It should be possible to view the objects changing in real time in both the ioBroker Objects list and Loxone web interface.

Alternate approach using Home Assistant

Note that the author originally completed this task using Home Assistant automation software. Although this worked (using the steps below) this was ultimately deprecated in favour of ioBroker method described above. However, the steps here are left for completeness as some may favour this approach.

Setup the Z-Wave Bridge

In this example we are going to use a Raspberry Pi as a Z-Wave bridge. In theory any PC or SBC that has a spare USB port, runs Home Assistant and has LAN connectivity to your Loxone Miniserver will do.

  1. Gather your materials (hardware).

  2. Plug the Z-Wave USB key into the Raspberry Pi and after installing your distribution of choice, check it has correctly loaded the driver. Ie. check for presence of /dev/ttyACM0 or similar.

  3. Install the Home Assistant Z-Wave software. It is beyond the scope of this How-To to discuss this, but note:

    1. Some might suggest that novice users will fair best if installing the Hass.io distribution.

    2. If using a Docker container note that there is (or at least was as of mid-May 2018) no latest tag for homeassistant/raspberrypi3-homeassistant and therefore one has to pull a specific version (the author used 0.69.0b3).

  4. Manually edit the Home Assistant configuration file to specify the device your Z-Wave USB key is on. Eg. add this:

    # Z-Wave
    zwave:
    usb_path: /dev/ttyACM0

  5. Restart Home Assistant and ensure Z-Wave management appears in the 'Configuration' menu:

  6. Proceed to add nodes to your Z-Wave network. In the case of the Coolcam Neo DS01Z window sensors this was as easy as hitting 'Add Node' in Home Assistant and triple tapping the button on the window sensor device. Note:

    1. In the case of the Coolcam Neo DS01Z window sensors this not only created the binary sensor (open/close) input we require but also some alarm and other entities that were superfluous to requirements. Each time these can be removed by selecting the entity and checking 'Exclude this entity from Home Assistant'. The author found this sometimes didn't take immediate effect or required a restart of Home Assistant. YMMV.

  7. Repeat the step above for each device required. Name each device as required.

  8. If everything goes as planned when returning to the Home Assistant overview you will see your Z-Wave device(s) listed with the correct status (note in this example the superfluous entities have already been removed). Go ahead and test the sensors by open/closing them, etc.

Eg:

Please ignore the 'Initializing' state of these devices in the example - the author had recently rebooted their Home Assistant instance and the Z-Wave devices had not yet 'woken up' since.

As you open/close doors (or move the magnet from sensor to test) in the example above the status should be instantly updated in the relevant entity atop this overview screen.

Setup in Loxone

To read the status of your Z-Wave sensors in Loxone it is necessary to use virtual inputs (HTTP or UDP). There are two mechanisms:

  1. Have Home Assistant transmit, and Loxone react to UDP packets. This method is untested but should work in theory. It has the advantage of instant updates in Loxone but also the disadvantage that UDP packets can (rarely) get 'lost' on any network. There is discussion on how to have Home Assistant transmit UDP packets here: Send UDP-packages with HA on rPi.

  2. Have Loxone regularly poll Home Assistant to read sensor states. This has the disadvantage that polling can only occur every 10s at the most frequent, but also the advantage that because reading is direct via HTTP there is no chance of data loss. The Home Assistant API returns a JSON response for either all sensor data, or a subset of data for a specific sensor so with this method there are further choices:

    1. Read all sensor states directly from Home Assistant (ie. with http://your.ha.instance:8123/api/states) and then parse out each sensor value.
      In Loxone speak this is to have one Virtual HTTP Input with multiple Virtual Input Commands nested within.

    2. Read individual sensor states from Home Assistant (ie. with http://your.ha.instance:8123/api/states/binary_sensor.sensor, http://your.ha.instance:8123/api/states/binary_sensor.sensorbinary_sensor.sensor_2, etc) and parse out the value more simply.
      In Loxone speak this is to have multiple Virtual HTTP Inputs, each with a single Virtual Input Command nested within.

    3. Write a small 'proxy' script to read and parse Home Assistant sensor data and return only a very small fragment re-formatted to better suit Loxone. Ie. Like 'a' above, but instead of JSON format return something like:

      Door 3.battery.100 Door 3.state.0 Door 2.battery.100 Door 2.state.0 Door 4.battery.100 Door 4.state.0

Parsing HTTP Virtual inputs or configuring UDP Virtual inputs is covered elsewhere so it is left to the reader to best determine which method best suits their needs.

For the record, the author chose method '2c' above, writing a Node.js proxy in a handful of lines of code and that runs in a separate Docker container on their Raspberry Pi.