Bridge4KT, an app to extend the functionality of Z-Way, one of the smartest controllers for Z-Wave devices, allows to bridge Z-Wave devices into any Apple HomeKit environment.
Did you know that there's a full blown HomeKit server operating silently within Z-Way? There was already an attempt to unleash it's capabilities - yet got stuck in an early stage. Others tried to bridge this gap with additional tools external to Z-Way - requiring people to maintain and align two or more software packages.
This app is my attempt to not only map Z-Wave devices, yet to integrate them as good as possible into the HomeKit world - to provide the user experience we're accustomed to operating our Apple device of choice.
Honestly it was the ultimate driver to create Bridge4KT (and the fact that gave this app it's name) to provide the user experience KT is expecting when she's operating our z-waved Home.
- Disclaimers
- Capabilities
- Installation
- Device Detection Process
- Tag Based Manipulation Language
- Additional Information
- RapydScript
This app was inspired and is conceptually based on the work of Andreas Freud and his Apple HomeKit Bridge for Z-Way. It yet is a completely independent product.
This app is produced independently from Apple® or the Apple Home app and carries no guarantee from Apple about quality, suitability or anything else.
The Apple HomeKit world knows a limited number of standard use cases that are supported in the Home apps on the various Apple operating systems. Bridge4KT supports a subset of these use cases yet is prepared to extend it's capabilities if there's additional user demand.
This latest version is able to bridge to the following accessories:
- Door
- Fan
- Garage
- Lightbulb
- Outlet
- Programmable Switch
- Sensor
- Switch
- Thermostat
- Window
- Window Covering
Thus, if you've installed a Z-Wave device for one of these use cases, you should be able to bridge it's functionality into the Apple HomeKit world and operate it accordingly with your Apple device.
There are yet a number of capabilities being present with a Z-Wave device that are not supported (so far) by the Apple HomeKit protocol. As an example, this is valid for the capability to measure the power consumption of a device in operation. As there's no equivalent in the HomeKit world, this capability is not bridged.
Bridge4KT is distributed via the Z-Way app store, in the category Ext. UIs. After installation, you'll find it in the apps directory of your Z-Way application.
If you're interested in experiencing the latest development version of Bridge4KT - which might be in a pre-release status - you should add the token B4KT to your list of Z-Way app store tokens.
Alteratively you could download this repository and drop it's contents under z-way-server/automation/userModules in a directory named Bridge4KT.
Don't forget to restart your server afterwards:
sudo service z-way-server restart
Each time you close the app pushing the Save button, the device detection process will be initiated.
This will as well create each time a new HomeKit Configuration Code. You have to re-open the app to get this latest valid code necessary to integrate the bridged devices into your Home configuration. Whereas this procedure is quite annoying, it's necessary just once - to be re-done only after relevant changes to your Z-Wave network.
To avoid blindfolded guessing of capabilities - usually leading to an unpleasant user experience - Bridge4KT uses a staggered approach for positive device detection.
First stage is based on the vendor information coming with every device. If the device is positively identified, it's capabilities are read from a database and applied accordingly.
Second stage is based on the Z-Wave type definition, as well provided by each device as part of it's pre-setting. If the type definition is recognized in the respective database, the predefined capabilities are as well applied.
As final stage there's a fingerprint of the device created based on it's supported Z-Wave command classes. Again, this fingerprint is compared against a small database, to identify it's capabilities.
The app ships with those databases, yet they will be updated as well from this GitHub repository if your controller has internet access. This allows easy integration of additional device definitions and smooth rollout of the respective capabilities without the demand to re-install (or update) the whole app. That said: If you like to add a device into this databases (especially the first one) which is currently missing, raise an issue - and it will be integrated (as long as it's properties are supported by the existing app).
Whereas it is quite easy to distinguish a sensor from a roller shutter, it is yet impossible to sense if this roller shutter is operating a window covering, a door or a garage (door). You may therefore manually alter the detection process and even overwrite the database provided capability information by means of a Tag Based Manipulation Language.
The result of the detection process will be displayed within the app in the section Detected Configuration:
For each device installed you'll get the following information:
Given Name: Vendor Data / Z-Way Type Definition / Fingerprint / Tag Language >> Result of the detection process: Applied Capabilities
If the result shown does not fit your expectation, you may define the appropriate tags to manipulate the detection process.
Bridge4KT understands a number of modifiers provided as a tag of a virtual device to alter the capability detection process. Some of those are generic, some dedicated to a very special use case.
Each modification tag has to be prepended by B4KT: to indicate that this is something dedicated to Bridge4KT:
The following tags may be applied to any virtual device belonging to the physical device who's capability detection process shall be modified:
| Tag Definition | Example | Use Case |
|---|---|---|
| B4KT:Capability | B4KT:TemperatureSensor |
To add the capability TemperaturSensor to a device. |
| B4KT:Capability:Primary | B4KT:TemperatureSensor:Primary |
To add the capability TemperaturSensor as the primary capability of a device. |
| B4KT:Capability:Skip | B4KT:TemperatureSensor:Skip |
To remove the capability TemperaturSensor (most probably pre-defined via the device database) from the list of capabilities of a device. |
B4KT:Lightbulb:White |
To operate a lightbulb as white color only device. |
Please be advised, that you have to apply both an add tag definition and a remove tag definition to switch the capability of a device.
An example: To operate a device, detected by default as Smoke Sensor, as Temperature Sensor only, you have to define
B4KT:TemperatureSensorB4KT:SmokeSensor:SkipThe sequence of definition is of no relevance for the resulting operation - yet if impose a capability that the device is not capable to handle, it will not be bridged at all.
The following tags have to be applied to the virtual device that shall be used for the dedicated capability.
| Tag Definition | Use Case |
|---|---|
B4KT:Name |
To define that the label of this virtual device shall be used as HomeKit identifier. |
B4KT:Slat:Horizontal |
To define that this virtual device is used to operate a horizontal slat. |
B4KT:Slat:Vertical |
To define that this virtual device is used to operate a vertical slat. |
B4KT:Slat:Minus90 |
To define that the slat operated by this virtual device has a tilt angle of 0° to -90°. |
B4KT:Slat:Plus90 |
To define that the slat operated by this virtual device has a tilt angle of 0° to +90°. |
B4KT:Slat:Swing |
To define that the slat operated by this vertical device is a swinging slat. |
B4KT:Switch:1 |
To define that this virtual device should be considered as the first of several switches of this multi switch. |
B4KT:Switch:n |
To define that this virtual device should be considered as the n-th of several switches of this multi switch. |
This section tries to provide some additional information that might be suitable to support you in your endeavours to setup Bridge4KT accordingly. If you're missing any detail or if you have further questions, please raise an issue for clarification.
To forward the battery status of battery driven devices, you may add BatteryService as additional capability tag to your devices definition: B4KT:BatteryService
Refer to Lightbulb.
Refer to Motor Control Device.
Refer to Motor Control Device.
Refer to Device Detection Process.
Lightbulbs are - per default - operated via their color related properties, e.g. their RGB values. If you intend to operate it as a "white color only" device, define the tag B4KT:Lightbulb:White.
Lightbulbs support the HomeBridge identification protocol applied during the device inclusion process. Pressing the button "Identify Device" (Gerät identifizieren) will flash the bulb.
Z-Way Motor Control Devices (MCDs) can be bridged to a number of different capabilities. The Apple HomeKit protocol differentiates between Door, Garage, Window and WindowCovering.
Bridge4KT defaults to WindowCovering. You may apply an appropriate tag definition to change this e.g. for Door: B4KT:Door:Primary, B4KT:WindowCovering:Skip
Over the last years the capabilities provided by MCDs continously grew and improved. Thus there're different types of MCDs on the market, each one with a modified set of functionality. Bridge4KT provides dedicated implementations to adequately support each of the different types of MCDs.
MCD(C) devices are - out of the box - aware of their current position and report endpoints. You may get even better position reporting after calibration of the device.
If you operate a venetian blind by an appropriate MCD(C), you may as well get support to control the slat position by application of the necessary tag definition.
MCD(B) devices are - out of the box - only aware of the endpoints. They demand calibration to support position reporting - and prior to accept target-position-in-between commands. Thus, if your MCD(B) behaves a little bit strage, it could help to perform a calibration run.
MCD(A) devices are - out of the box - neither aware of the endpoints nor position. Nevertheless there's code implemented to provide adequate user experience even for those devices.
Devices advertising the type Simple Window Covering are as well supported by Bridge4KT.
By default, Bridge4KT takes the name given to the physical device in Z-Wave.me as HomeKit identifier.
If you define the tag B4KT:Name for any virtual device (associated with this pysical device), Bridge4KT is using the label of this virtual device as HomeKit indentifier.
In case you're operating a physical device combining several operational units (e.g. a double switch or a multi sensor), you may define B4KT:Name in combination with an index to reference the name to be given to the first (B4KT:Name:1) or n-th (B4KT:Name:n) device.
If this is a composed identifier, beginning with a term that equals the name of the room this device is associated to in HomeKit, then HomeKit will strip this portion of the identifier to create a nice label.
Be advised, that HomeKit considers the name a device is propagating as a datum that shall never change. The user may give the device a different name - yet the device itself shall never touch it once published. Thus, when you decide to alter (via definition in Z-Wave.me) the name of a device already bridged into HomeKit, those changes will not be reflected in the Home app. In such a case, you may either accept this - or you need to toggle the inclusion of the bridge (delete the bridge, then add it again!) to reset HomeKit's memory setup.
Refer to Switch.
Refer to Lightbulb.
Most devices suitable to operate a motor are advertised and sold as Roller Shutter as this is one of the most obvious use cases. In the end, they are capable to support a number of different activities, like opening / closing a garage or a motorized door.
Refer to Motor Control Device.
The following sensor types are supported:
- CarbonDioxideSensor
- CarbonMonoxideSensor
- ContactSensor
- LeakSensor
- MotionSensor
- SmokeSensor
- TemperatureSensor
If you operate a sensor supporting multiple types, you may add those as a capability by adding a dedicated tag, e.g. B4KT:TemperaturSensor.
Bridge4KT supports Single Switches as well as Double Switches (and even devices with more than two switching units - if they'd exist).
To alter the sequence of the switching units of a dedicated device (in HomeKit), you may define a numbering tag, e.g. B4KT:Switch:1 for the device to be considered as number 1 of its siblings.
Refer to Motor Control Device.
Refer to Motor Control Device.
Bridge4KT is written using RapydScript NG , a "transpiler for a Python like language to JavaScript".
I'd like to express a sincere "Great Job!" to @kovidgoyal for his efforts to maintain this excellent piece of software. It took away much of what I consider as ugliness when working with JavaScript - and allowed me to create a nicely structured easily extendable application.
To compile the sources into the JavaScript code demanded by Z-Way, there's a small Python script provided.