Complications

Complications

Complications are HomeKit integration items that are more than a simple one-to-one mapping (although that is part of the complications system too but aren't referred to as complications).

One-To-One Complication

Take, for instance, a light switch. This is a simple one-to-one mapping between Indigo's onState of a device to the On characteristic of HomeKit, both are boolean and it's the absolute simplest device mapping possible.

One-To-Many Complications

Consider an Indigo sprinkler system. Indigo's single device defines the core system plus up to sixteen zones. In HomeKit an irrigation controller is one device and then each zone is a valve on that controller, meaning up to seventeen devices need to be created in HomeKit to have the same capabilities as an Indigo sprinkler. This is a one-to-many relationship and it's complicated and, thus, a complication.

Now add to this complication the fact that Indigo doesn't report how much time is remaining on a zone or the entire schedule, so all of that then also must be specially calculated in the plugin and you can appreciate how something as simple as a sprinkler controller is one of the more complex devices to deal with.

Many-To-One Complications

A Fibaro FGMS motion sensor. In Indigo when you add this it adds four devices linked together: a motion sensor, temperature sensor, light sensor and tilt/tamper sensor. Only the motion sensor will report the battery state. In HomeKit each of those sensors not only detect the primary "thing", such as light level or motion or temperature, but also report if the battery is low and if the sensor has been tampered with. A complication is needed to say that your temperature sensor gets it's temperature from itself, the low battery indication from the motion sensor and the tamper status from the tamper sensor. This is a many-to-one relationship and is complicated.

Many-To-Many Complications

Using the same example as in the Many-To-One, the Fibraro FGMS motion sensor can also create multiple devices in HomeKit, one for each sensor and each sensor is using information from each of the other sensors to complete the HomeKit characteristics for a device. This is many-to-many.

Simple "Complications"

Complications can also be somewhat simple and be used to incorporate a plugin device that wouldn't otherwise be supported. If a plugin device is "custom" and therefore doesn't have an onState or sensorValue or any number of other "standard" Indigo properties then there is no way for the plugin to know how this custom device reports one thing or the other, it's an orphan.

With a simple complication we are just telling the plugin to map certain properties from Indigo to certain characteristics in HomeKit, thus now being able to support this custom device just as we do any other.

A good example of this is the Nest thermostat. While it appears to be a thermostat in Indigo it actually is quite different because the standard ways that an Indigo thermostat works are not supported by the plugin, so a simple complication has to be built to, for instance, get the running state of the fan from the states rather than the Indigo standard fanIsOn attribute.

Implementation

Complications are implemented in HomeKit Bridge via JSON construction files. Basically it's a file that is in JSON format that the plugin reads to get everything it needs to know about reporting a device to HomeKit and then what to do when HomeKit requests an action be taken.

In the current generation of the product these files are part of the plugin, but eventually you will be able to have your own local copies that you can create to make your own complications (or share with others).