@uboness/homebridge-mqtt v0.0.9

Homebridge Mqtt Plugin

!! Experimental !!

• Core Ideas
  • Device Configuration
• Settings
  • Templates
• Converters Reference
• Characteristics Reference

• Services Reference

  • air-quality-sensor
  • battery
  • button
  • co2-sensor
  • contact-sensor
  • co-sensor
  • door
  • doorbell
  • fan
  • humidifier-dehumidifier
  • humidity-sensor
  • leak-sensor
  • lightbulb
  • light-sensor
  • lock
  • microphone
  • motion-sensor
  • occupancy-sensor
  • outlet
  • security-system
  • smoke-sensor
  • speaker
  • switch
  • temperature-sensor
  • thermostat
  • window
  • window-covering

This plugin enables the configuration of devices (HomeKit accessories) that are driven by MQTT topics.

Core Ideas

• Multiple brokers are supported
• Each broker defines:
  • a unique id
  • connection settings to a single MQTT broker
  • baseTopic a "prefix" topic that will be prepended to all topics configured by the devices & templates
  • device configurations - all driven by topics within the broker
  • device templates - reusable device configuration segments (helps keep configuration clean and simple)

Device Configuration

A device configuration is made out of:

• id - This identifies the device in homebridge, so it needs to be unique within the Homebridge instance.
• type - The primary service type
• name - Serves as both the primary service name and the HomeKit accessory name
• deviceName - If set, serves as the accessory name (used to separate the accessory and primary service names)
• topics - Defines the characteristics of the primary service and their associated (read/write) topics from/to which values will be read/written
• services - An array of additional (secondary) services that are part of the HomeKit accessory.

Here's an example of a simple lightbulb accessory that happens to have a built-in light sensor:

{
  "id": "my-ceiling-light",
  "type": "lightbulb",
  "name": "My Ceiling Lamp",
  "topics": {
    "on": {
      "get": "my-home/my-room/my-ceiling-light/on",
      "set": "my-home/my-room/my-ceiling-light/on/set",
      "converter": "boolean"
    },
    "brightness": {
      "get": "my-home/my-room/my-ceiling-light/brightness",
      "set": "my-home/my-room/my-ceiling-light/brightness/set"
    }
  },
  "services": [
    {
      "type": "light-sensor",
      "name": "Light Sensor",
      "topics": {
        "ambientLevel": {
          "get": "my-home/my-room/my-ceiling-light/lux",
          "set": "my-home/my-room/my-ceiling-light/lux/set"
        }
      }
    }
  ]
}

Each service type defines a set of required characteristics which must be configured within the topics configuration (e.g. A switch service must define the on characteristic).

There may also be optional characteristics that a service can support (e.g. all sensor services support the statusLowBattery characteristic, though it's optional).

The HomeKit Accessory Protocol (HAP) Specification define the services supported in homekit and their required/optional characteristics. This plugin roughly follows these specifications with a few exceptions here and there.

In the example above, the configured MQTT topics hold the values that will eventually be read/published by the relevant characteristics. MQTT values are strings and therefore we need a way to convert these values to the appropriate type that is expected by each characteristic. This is the role of the converter. Each characteristic support a set of converters that helps in converting different formats. For example, as in the above, by default, the on characteristic expects 1 (for "on") and 0 (for "off") values. But if the MQTT value holds true and false instead, the boolean converter will be able to handle it. What if the MQTT values is YES and NO? Well, there's a converter for that too - a more generic one: converter: { "on": "YES", "off": "NO" } - in this case, we indicate which MQTT values represent on and off.

Some systems (e.g. zigbee2mqtt) publish JSON values to their MQTT topic. To fetch a JSON value, you append the "path" to the value within the JSON to the topic itself, using the $ sign as a separator. For example, the following hum characteristic configuration reads/writes the hue values from/to JSON values in the MQTT topics:

{
  "hue": {
    "get": "zigbee2mqtt/Garage Led$color.hue",      // reads from
    "set": "zigbee2mqtt/Garage Led/set$color.hue"   // publishes to
  }
}

In the above, the topic is zigbee2mqtt/Garage Led holds a JSON object of the form:

{
  //...
  "color": {
    "hue": 212,
    "saturation": 10,
    "x": 0.3131,
    "y": 0.3232
  }
  //...
}

With the $ syntax, the plugin knows how to read it and extract the appropriate value.

Similarly, when publishing a value to the zigbee2mqtt/Garage Led/set topic, the plugin will create a JSON value of the following form:

{ "color": { "hue": 200 }}

At the moment, not all HAP services are supported by this plugins, but certainly a big chunk of the most common ones. More services/characteristics may be added in the future.

There are many service types to choose from and many characteristic types as well, all of which are

Settings

Here's an example of the plugin configuration:

{
    "name": "Mqtt",
    "platform": "Mqtt",
    "logger": {
      "trace": false // change to 'true' to output extensive logs (only works when HB runs in debug mode)
    },
    "servers": [
      {
        "id": "knx",
        "host": "mqtt.local",
        "port": 1883,
        "auth": { // optional, remove if your MQTT broker doesn't require authentication
          "username": "<username>",
          "password": "<password>"
        },
        "baseTopic": "knx",
        "templates": [
          // all the KNX device templates are configued here (see below)
        ],
        "devices": [
          // all the KNX devices are configured here
        ]
      },
      {
        "id": "zigbee2mqtt",
        "host": "mqtt.local",
        "port": 1883,
        "auth": { // optional, remove if your MQTT broker doesn't require authentication
          "username": "<username>",
          "password": "<password>"
        },
        "baseTopic": "z2m",
        "templates": [
          // all the z2m device templates are configued here (see below)
        ],
        "devices": [
          // all the z2m devices are configured here
        ]
      }
    ]
}

In the example above, the plugin is configured with 2 brokers - one that holds all KNX devices values and another that is the zigbee2mqtt broker.

If you look closely thought, they are actually pointing to the same server - they could point to different servers, but in this case it's the same server and the only thing that really differentiate them is the baseTopic - all KNX values are under the knx base topic while all the zigbee2mqtt topics are under the z2m base topic.

In this case, we could have also use a single MQTT connection by dropping the baseTopic setting and make sure that the devices use the full MQTT topic paths in their configurations. So there are a lot of possibilities to design this in a way to best fit your setup.

Templates

We've seen above an example of a device configuration. These configurations may vary from simple to complex, depending on the type of services (and the number of services) each device/accessory has. But event in its simplest form, like a simple switch device with a single primary switch service that only has one on characteristic, when you have many of such services defined, the configuration may look quite cumbersome. More over, it really depends on the setup you have at home, but it is often the case that the same physical device types are used across the house, for example:

• If you have KNX installed in the house, the setups for all your switches in the house is most likely similar and the only thing that changes between them is the KNX group addresses that are associated with them.

• If you have a Hue bridge at home, and you're using Hue motion sensor, it's very likely you have a bunch of those and zigbee2mqtt will expose their state in similar ways (just under a different base topic)

There can be many examples as the two above, but the point is, with the normal device configuration as we've seen, you'll find yourself copy-pasting configurations all over the place. This is where Templates enter the picture.

But first, lets say we have 2 Hue motion sensors in the house and we configure them without templates, here's how it might look like:

{
  //...
  "devices": [
    {
      "id": "garage-motion",
      "name": "Garage Motion",
      "type": "motion-sensor",
      "topics": {
        "motionDetected": {
          "get": "Garage Motion$occupancy",
          "converter": "boolean"
        }
      },
      "services": [
        {
          "name": "Battery Level",
          "type": "battery",
          "topics": {
            "batteryLevel": {
              "get": "Garage Motion$battery"
            }
          }
        },
        {
          "name": "Light Sensor",
          "type": "light-sensor",
          "topics": {
            "ambientLevel": {
              "get": "Garage Motion$illuminance_lux"
            }
          }
        },
        {
          "name": "Temperature Sensor",
          "type": "temperature-sensor",
          "topics": {
            "currentTemperature": {
              "get": "Garage Motion$temperature"
            }
          }
        }
      ]
    },
    {
      "id": "stairs-motion",
      "name": "Stairs Motion",
      "type": "motion-sensor",
      "topics": {
        "motionDetected": {
          "get": "Stairs Motion$occupancy",
          "converter": "boolean"
        }
      },
      "services": [
        {
          "name": "Battery Level",
          "type": "battery",
          "topics": {
            "batteryLevel": {
              "get": "Stairs Motion$battery"
            }
          }
        },
        {
          "name": "Light Sensor",
          "type": "light-sensor",
          "topics": {
            "ambientLevel": {
              "get": "Stairs Motion$illuminance_lux"
            }
          }
        },
        {
          "name": "Temperature Sensor",
          "type": "temperature-sensor",
          "topics": {
            "currentTemperature": {
              "get": "Stairs Motion$temperature"
            }
          }
        }
      ]
    }
  ]
}

Ouch... as you can see, just defining 2 motion sensors already looks quite cumbersome and complex. And even more annoying, the two configurations are almost identical - the only thing that differs them is the base topic of the device (which makes sense, because these are both Hue motion sensors, supporting the same characteristics and controlled by the same system (zigbee2mqtt)).

Surely we can do better - We can define a template for a hue motion sensor and have both devices point to it:

{
  "templates": [
    {
      "id": "hue-motion-sensor",
      "type": "motion-sensor",
      "topics": {
        "motionDetected": {
          "get": "{{baseTopic}}$occupancy",
          "converter": "boolean"
        }
      },
      "services": [
        {
          "name": "Battery Level",
          "type": "battery",
          "topics": {
            "batteryLevel": {
              "get": "{{baseTopic}}$battery"
            }
          }
        },
        {
          "name": "Light Sensor",
          "type": "light-sensor",
          "topics": {
            "ambientLevel": {
              "get": "Stairs {{baseTopic}}$illuminance_lux"
            }
          }
        },
        {
          "name": "Temperature Sensor",
          "type": "temperature-sensor",
          "topics": {
            "currentTemperature": {
              "get": "{{baseTopic}}$temperature"
            }
          }
        }
      ]
    }
  ],
  "devices": [
    {
      "id": "garage-motion",
      "name": "Garage Motion",
      "baseTopic": "Garage Motion",
      "template": "hue-motion-sensor"
    },
    {
      "id": "stairs-motion",
      "name": "Stairs Motion",
      "baseTopic": "Stairs Motion",
      "template": "hue-motion-sensor"
    }
  ]
}

The template above defines the typical structure of a Hue motion sensor device and it uses parameter placeholders to make it reusable. Then, when defining the devices, all that is required is to point to the template and provide a value to the template parameters (baseTopic in this case). Now imagine you have 10 such motion sensors in the house - this makes their configuration a breeze. More over, it's great for maintenance - if you need to change how you handle a motion sensor, you just need to change the template and all motion sensor devices will automatically be updated.

It's also possible to use parameter placeholder in normal device configuration. For example

{
  "devices": [
    {
      "id": "garage-motion",
      "name": "Garage Motion",
      "type": "motion-sensor",
      "topic": "Garage Motion",
      "topics": {
        "motionDetected": {
          "get": "{{topic}}$occupancy",
          "converter": "boolean"
        }
      },
      "services": [
        {
          "name": "Battery Level",
          "type": "battery",
          "topics": {
            "batteryLevel": {
              "get": "{{topic}}$battery"
            }
          }
        },
        {
          "name": "Light Sensor",
          "type": "light-sensor",
          "topics": {
            "ambientLevel": {
              "get": "{{topic}}$illuminance_lux"
            }
          }
        },
        {
          "name": "Temperature Sensor",
          "type": "temperature-sensor",
          "topics": {
            "currentTemperature": {
              "get": "{{topic}}$temperature"
            }
          }
        }
      ]
    }
  ]
}

In the above example, we only need to define the topic of the accessory once in a parameter and have all topics reference it. If the topic changes, we only need to change one place. Though again, the use of templates has the potential of a greater added value overall.

Converters Reference

Booleans

• boolean - Converts "true" and "false" string values or true and false JSON values.
• one-zero - Converts "1" and "0" to true and false (also 1 and 0 numeric JSON values)
• { "on": "<on_value>", "off": "<off_value>" } - Indicates the values that represent true (on) and false (off)

Percentages (%)

• homekit - Homekit expects numbers between 0 - 100.
• decimal - Converts numbers between 0 - 1 (0.34 indicates 34%)
• { "min": <number>, "max": <number> } - Translate any number between these bounds to a percentage value. Any number above the max will be converted to max and any number below the min will be converted to min.

Hue

• homekit - Homekit expects numbers representing arc degrees (0 - 360)
• percent-integer - Converts a percentage value between 0 - 100
• percent-decimal - Converts a percentage value between 0 - 1

Color Temperatures

• homekit - Homekit expects numbers in mirek units ($mirek = \frac{1,000,000}{Kelvin}$)
• mirek - same as homekit
• kelvin - Converts numbers in kelvin units

Illuminance

• homekit - Homekit expects numbers in lux units
• lux - same as homekit
• log-scale-lux - Expects number in log scale values as used by Hue ($lux =(\frac{logscale-1}{10000})^{10}$)

Temperatures

• homekit - Homekit expects temperature to be in Celsius
• celsius - same as homekit
• fahrenheit - Expects temperatures to be in Fahrenheit units

Characteristics Reference

• Common Characteristics
• Common Sensor Characteristics
• active
• airQuality
• ambientLightLevel
• batteryLevel
• brightness
• co2Detected
• co2Level
• co2PeakLevel
• coDetected
• coLevel
• coPeakLevel
• chargingState
• colorTemperature
• contactSensorState
• coolingThreshold
• currentFanState
• currentHeatingCoolingState
• currentHorizontalTiltAngle
• currentHumidifierDehumidifierState
• currentPosition
• currentRelativeHumidity
• currentTemperature
• currentVerticalTiltAngle
• faultMessage
• heatingThreshold
• holdPosition
• hue
• leakDetected
• lockCurrentState
• lockPhysicalControls
• lockTargetState
• motionDetected
• mute
• no2Density
• obstructionDetected
• occupancyDetected
• on
• outletInUse
• ozoneDensity
• pm10Density
• pm25Density
• positionState
• pressEvent
• dehumidifierThreshold
• humidifierThreshold
• rotationDirection
• rotationSpeed
• saturation
• alarmType
• securitySystemCurrentState
• securitySystemTargetState
• smokeDetected
• so2Density
• statusFault
• statusLowBattery
• statusTampered
• swingMode
• targetFanState
• targetHeatingCoolingState
• targetHorizontalTiltAngle
• targetHumidifierDehumidifierState
• targetPosition
• targetRelativeHumidity
• targetTemperature
• targetVerticalTiltAngle
• temperatureDisplayUnits
• vocDensity
• volume
• waterLevel

Common Characteristics

The following characteristic are optional and may be configured on any service type

• statusFault
• faultMessage

Common Sensor Characteristics

In addition to the above common characteristics, sensor devices may also support the following ones:

• statusLowBattery
• statusTampered

active

Indicates whether the service is currently active. By default, will look for values 0 or 1 where 1 indicates on/true and 0 indicates off/false. Values can be converted using the Booleans converter.

Services

• speaker
• humidifier-dehumidifier

Configuration

{
  "topics": {
    "active": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "boolean" | { "min": <number>, "max": <number> }
    }
  }
}

airQuality

Describes the subject assessment of air quality. By default, will look for the following values:

• 0 - indicates "unknown"
• 1 - indicates "excellent"
• 2 - indicates "good"
• 3 - indicates "fair"
• 4 - indicates "inferior"
• 5 - indicates "poor"

You can customize the read/published values using a value map converter (as shown below)

Services

• air-quality-sensor

Configuration

{
  "topics": {
    "airQuality": {
      "get": "<read_topic>",
      "converter"?: {
        "unknown"?:   "<value representing 'unknown'>",
        "excellent"?: "<value representing 'excellent'>",
        "good"?:      "<value representing 'good'>",
        "fair"?:      "<value representing 'fair'>",
        "inferior"?:  "<value representing 'inferior'>",
        "poor"?:      "<value representing 'poor'>"
      }
    }
  }
}

ambientLightLevel

Indicates the current light level in lux numeric units. Values can be converted using the Illuminance converter.

Services

• light-sensor

Configuration

{
  "topics": {
    "ambientLightLevel": {
      "get": "<read_topic>",
      "converter"?: log-scale-lux"
    }
  }
}

batteryLevel

Describes the current level of the battery in a numeric value representing a percentage. Values can be converted using the Percentages converter.

Services

• battery

Configuration

{
  "topics": {
    "batteryLevel": {
      "get": "<read_topic>",
      "converter"?: "decimal" | { "min": <number>, "max": <number> }
    }
  }
}

brightness

Describes a level of brightness in a numeric value representing a percentage. Values can be converted using the Percentages converter.

Services

• lightbulb
• doorbell

Configuration

{
  "topics": {
    "brightness": {
      "get": "<read_topic>",
      "get": "<write_topic>",
      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
    }
  }
}

co2Detected

Indicates if a sensor detects abnormal levels of Carbon Dioxide. By default, will look for 0 (indicating "not detected") or 1 (indicating "detected"). Values can be converted using the Booleans converter.

Services

• co2-sensor

Configuration

{
  "topics": {
    "co2Detected": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "'detected' value", "off": "'not-detected' value" }
    }
  }
}

co2Level

Indicates the detected level of Carbon Dioxide - a numeric value indicating parts per million (ppm).

Services

• co2-sensor

Configuration

{
  "topics": {
    "co2Level": {
      "get": "<read_topic>"
    }
  }
}

co2PeakLevel

Indicates the highest detected level of Carbon Dioxide detected by a sensor - a numeric value indicating parts per million (ppm).

Services

• co2-sensor

Configuration

{
  "topics": {
    "co2PeakLevel": {
      "get": "<read_topic>"
    }
  }
}

coDetected

Indicates if a sensor detects abnormal levels of Carbon Monoxide. By default, will look for 0 (indicating "not detected") or 1 (indicating "detected"). Values can be converted using the Booleans converter.

Services

• co-sensor

Configuration

{
  "topics": {
    "coDetected": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "'detected' value", "off": "'not-detected' value" }
    }
  }
}

coLevel

Indicates the detected level of Carbon Monoxide - a numeric value indicating parts per million (ppm).

Services

• co-sensor

Configuration

{
  "topics": {
    "coLevel": {
      "get": "<read_topic>"
    }
  }
}

coPeakLevel

Indicates the highest detected level of Carbon Monoxide detected by a sensor - a numeric value indicating parts per million (ppm).

Services

• co-sensor

Configuration

{
  "topics": {
    "coPeakLevel": {
      "get": "<read_topic>"
    }
  }
}

chargingState

Indicates whether the battery-ran device is currently charging or not. Values can be converted using the Booleans converter.

Services

• battery

Configuration

{
  "topics": {
    "chargingState": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "'charging' value", "off": "'not-charging' value" }
    }
  }
}

colorTemperature

Describes color temperature - a numeric value in the mirek scale Values can be converted using the Color Temperatures converter.

Services

• lightbulb

Configuration

{
  "topics": {
    "colorTemperature": {
      "get": "<read_topic>",
      "set": "<read_topic>",
      "converter"?: "kelvin"
    }
  }
}

contactSensorState

Describes the state of a contact sensor. By default, will look for 0 (indicating "no contact") and 1 (indicating "contact") Values can be converted using the Booleans converter.

Services

• contact-sensor

Configuration

{
  "topics": {
    "contactSensorState": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "'contact' value", "off": "'no-contact' value" }
    }
  }
}

coolingThreshold

Describes the cooling threshold in Celsius for accessories that support heating and cooling. If the thermostat operates in an "auto" mode and the current temperature goes above this threshold the thermostat will start cooling. Values can be converted using the Temperatures converter.

Services

• thermostat

Configuration

{
  "topics": {
    "coolingThreshold": {
      "get": "<read_topic>",
      "set": "<read_topic>",
      "converter"?: "fahrenheit"
    }
  }
}

currentFanState

!NOTE When used as part of a fan service, this can be shorten to currentState

Describes the current state of the fan. Expects the following numeric values:

• 0 - indicating "inactive" state
• 1 - indicating "idle" state
• 2 - indicating "blowing air" state

Other values can be converted using a value-map converter (as shown below).

Services

• fan

Configuration

{
  "topics": {
    "currentFanState": {
      "get": "<read_topic>",
      "converter"?: {
        "inactive"?:    "'inactive' state value",
        "idle"?:        "'idle' state value",
        "blowingAir"?:  "'blowing air' state value"
      }
    }
  }
}

currentHeatingCoolingState

!NOTE When used as part of a thermostat service, this can be shorten to currentState

Describes the current mode of a thermostat. Expects the following numeric values:

• 0 - indicating "off" state
• 1 - indicating "heat" state
• 2 - indicating "cool" state

Other values can be converted using a value-map converter (as shown below).

Services

• thermostat

Configuration

{
  "topics": {
    "currentHeatingCoolingState": {
      "get": "<read_topic>",
      "converter"?: {
          "off"?:   "'off' state value",
          "heat"?:  "'heat' state value",
          "cool"?:  "'cool' state value"
        }
    }
  }
}

currentHorizontalTiltAngle

Describes the current angle of the horizontal slats of the device. A numeric value in arc degrees, ranging between -90 - 90.

Services

• window-covering

Configuration

{
  "topics": {
    "currentHorizontalTiltAngle": {
      "get": "<read_topic>"
    }
  }
}

currentHumidifierDehumidifierState

!NOTE When used as part of a humidifier-dehumidifier service, this can be shorten to currentState

Describes the current state of a humidifier or/and a dehumidifier. Expecting the following numeric values:

• 0 - indicating inactive state
• 1 - indicating idle state
• 2 - indicating humidifying state
• 3 - indicating dehumidifying state

Other values can be converted using a value-map converter (as shown below).

Services

• humidifier-dehumidifier

Configuration

{
  "topics": {
    "currentHumidifierDehumidifierState": {
      "get": "<read_topic>",
      "converter"?: {
        "inactive"?:       "'inactive' state value",
        "idle"?:           "'idle' state value",
        "humidifying"?:    "'humidifying' state value",
        "dehumidifying"?:  "'dehumidifying' state value"
      }
    }
  }
}

currentPosition

Describes the current position of accessories as a percentage value. 0 typically indicates "fully closed" while 100 indicates "fully open". Some services (e.g. window-covering let you reverse this). Other values can be converted using the Percentages converter.

Services

• window
• door
• window-covering

Configuration

{
  "topics": {
    "currentPosition": {
      "get": "<read_topic>",
      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
    }
  }
}

currentRelativeHumidity

Describes the current relative humidity of the device's environment. By default, expecting a numeric value between 0 and 100 representing a percentage. Other values can be converted using the Percentages converter.

Services

• humidity-sensor
• humidifier-dehumidifier

Configuration

{
  "topics": {
    "currentRelativeHumidity": {
      "get": "<read_topic>",
      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
    }
  }
}

currentTemperature

Describes the current temperature of the environment in Celsius Other values can be converted using the Temperatures converter.

By default, values range between 10.0 and 38.0 with a minimum step of 0.1. This can be adjusted in the configuration (as shown below).

Services

• thermostat
• temperature-sensor

Configuration

{
  "topics": {
    "currentTemperature": {
      "get": "<read_topic>",
      "converter"?: "fahrenheit",
      "minValue"?: <number>, // in celsius (regardless of the converter), defaut: 10.0 
      "maxValue"?: <number>, // in celsius (regardless of the converter), defaut: 38.0
      "minStep"?: <number>   // in celsius (regardless of the converter), defaut: 0.1
    }
  }
}

currentVerticalTiltAngle

Describes the current angle of the vertical slats of the device. Expecting a numeric value representing arc degrees between -90 and 90.

Services

• window-covering

Configuration

{
  "topics": {
    "currentVerticalTiltAngle": {
      "get": "<read_topic>"
    }
  }
}

faultMessage

A non-standard homekit characteristic indicating a fault message in case the device if faulty.

!NOTE As a non-standard characteristic, this will no show up in the Home app, though other apps that support this custom characteristic will show it (e.g. Eve)

Services

This characteristic is optional and can be configured on all service types.

Configuration

{
  "topics": {
    "faultMessage": {
      "get": "<read_topic>"
    }
  }
}

heatingThreshold

Describes the heating threshold in Celsius for accessories that support heating and cooling. If the thermostat operates in an "auto" mode and the current temperature goes below this threshold the thermostat will start heating. Values can be converted using the Temperatures converter.

Services

• thermostat

Configuration

{
  "topics": {
    "heatingThreshold": {
      "get": "<read_topic>",
      "set": "<read_topic>",
      "converter"?: "fahrenheit"
    }
  }
}

holdPosition

Used to signal a device that it should stop it current operations in its current position (typically used for window-covering). This characteristic doesn't hold a value. To signal a "hold" it sets a value in the configured set topic. By default, it sets the value to 1, though this can be changed in the configuration (as shown below).

Services

• window-covering

Configuration

{
  "topics": {
    "holdPosition": {
      "set": "<write_topic>",
      "value"?: "any value that the device will understand as a 'hold' command"
    }
  }
}

hue

Describes hue or color. A hue is typically measured as an arc degree in a Hue Wheel. Expects, a numeric value between 0 and 360. Percentage values (e.g. 34% of 360) are also supported and be configured using the Hue Converter

Services

• lightbulb

Configuration

{
  "topics": {
    "hue": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "percent-integer" | "percent-decimal"
    }
  }
}

leakDetected

Indicates if a sensor detected a leak (e.g. water leak, gas leak). By default, will look for 0 (indicating "not detected") or 1 (indicating "detected"). Values can be converted using the Booleans converter.

Services

• leak-sensor

Configuration

{
  "topics": {
    "leakDetected": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
    }
  }
}

lockCurrentState

!NOTE When used as part of a lock service, this can be shorten to currentState

Describes the current state of a lock. Expecting the following numeric values:

• 0 - indicating "unsecured" state
• 1 - indicating "secured" state
• 2 - indicating "jammed" state
• 3 - indicating "unknown" state

Other values can be converted using a value-map converter (as shown below).

Services

• lock
• garage-door

Configuration

{
  "topics": {
    "lockCurrentState": {
      "get": "<read_topic>",
      "converter"?: {
        "unsecured"?:   "'unsecured' state value",
        "secured"?:     "'secured' state value",
        "jammed"?:      "'jammed' state value",
        "unknown"?:     "'unknown' state value"
      }
    }
  }
}

lockPhysicalControls

Describes a way to lock a set of physical controls on an accessory (eg. child lock). By default, will look for 0 (indicating "not detected") or 1 (indicating "detected"). Values can be converted using the Booleans converter.

Services

• fan
• humidifier-dehumidifier

Configuration

{
  "topics": {
    "lockPhysicalControls": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "boolean" | { "": "<value indicating 'locked'>", "off": "value indicating 'not-locked'" }
    }
  }
}

lockTargetState

!NOTE When used as part of a lock-mechansim service, this can be shorten to targetState

Describes the current state of a lock. Expecting the following numeric values:

• 0 - indicating "unsecured" state
• 1 - indicating "secured" state

Other values can be converted using a converter (as shown below).

Services

• lock
• garage-door

Configuration

{
  "topics": {
    "lockTargetState": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "boolean" | { "secured": "<value indicating 'secured'>", "unsecured": "value indicating 'unsecured'" } // a boolean 'true' indicates 'secured'
    }
  }
}

momentaryOn

This is a special case of an 'on' characteristic when turned on it immediately turns back off. When turned on, it publishes the configured value to the configured topic.

Services

• stateless-scene

Configuration

{
  "topics": {
    "momentaryOn": {
      "get": "<read_topic>",
      "value": number | string | boolean // the published value
    }
  }
}

motionDetected

Indicates if a sensor detected motion. By default, will look for true (indicating "detected") or false (indicating "not-detected"). Values can be converted using the Booleans converter.

Services

• motion-sensor

Configuration

{
  "topics": {
    "motionDetected": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
    }
  }
}

mute

Allows the control of audio input or output accessory. By default, will look for true (indicating "muted") or false (indicating "not-muted"). Values can be converted using the Booleans converter.

Services

• speaker
• doorbell

Configuration

{
  "topics": {
    "motionDetected": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "boolean" | { "on": "<value indicating 'muted'>", "off": "value indicating 'not-muted'" }
    }
  }
}

no2Density

Indicates the current Nitrogen Dioxide density. A numeric value in $micrograms/m^3$ units.

Services

• air-quality-sensor

Configuration

{
  "topics": {
    "no2Density": {
      "get": "<read_topic>"
    }
  }
}

obstructionDetected

Describes the current state of an obstruction sensor. By default, will look for true (indicating "detected") or false (indicating "not detected"). Values can be converted using the Booleans converter.

Services

• door
• window
• garage-door
• window-covering

Configuration

{
  "topics": {
    "obstructionDetected": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
    }
  }
}

occupancyDetected

Indicates if occupancy was detected (e.g. a person present). By default, will look for 1 (indicating "detected") or 0 (indicating "not detected"). Values can be converted using the Booleans converter.

Services

• occupancy-sensor

Configuration

{
  "topics": {
    "occupancyDetected": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
    }
  }
}

on

Represents the states for “on” and “off”. By default, will look for true (indicating "on") or false (indicating "off"). Values can be converted using the Booleans converter.

Services

• lightbulb
• outlet
• switch

Configuration

{
  "topics": {
    "on": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "boolean" | { "on": "<value indicating 'on'>", "off": "value indicating 'off'" }
    }
  }
}

outletInUse

describes if the power outlet has an appliance physically plugged in. By default, will look for true (indicating "in-use") or false (indicating "not-in-use"). Values can be converted using the Booleans converter.

Services

• outlet

Configuration

{
  "topics": {
    "outletInUse": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "<value indicating 'in-use'>", "off": "value indicating 'not-in-use'" }
    }
  }
}

ozoneDensity

Indicates the current ozone density. A numeric value in $micrograms/m^3$ units.

Services

• air-quality-sensor

Configuration

{
  "topics": {
    "ozoneDensity": {
      "get": "<read_topic>"
    }
  }
}

pm10Density

Indicates the current PM10 micrometer particulate density. A numeric value in $micrograms/m^3$ units.

Services

• air-quality-sensor

Configuration

{
  "topics": {
    "pm10Density": {
      "get": "<read_topic>"
    }
  }
}

pm25Density

Indicates the current PM2.5 micrometer particulate density. A numeric value in $micrograms/m^3$ units.

Services

• air-quality-sensor

Configuration

{
  "topics": {
    "pm25Density": {
      "get": "<read_topic>"
    }
  }
}

positionState

Describes the state of the position of accessories. Expecting the following numeric values:

• 0 - indicating "closing" state
• 1 - indicating "opening" state
• 2 - indicating "stopped" state

Other values can be converted using a value-map converter (as shown below).

Services

• door
• window
• window-covering

Configuration

{
  "topics": {
    "lockCurrentState": {
      "get": "<read_topic>",
      "converter"?: {
        "closing"?: "'closing' state value",
        "opening"?: "'opening' state value",
        "stopped"?: "'stopped' state value"
      }
    }
  }
}

pressEvent

Describes a press event generated by a button. This characteristic doesn't hold a value nor publishes a value to an MQTT topic. All it does is monitor an MQTT topic and based on the value received it triggers the appropriate event. By default, it expects the following numeric values:

• 0 - indicating "single-press" event
• 1 - indicating "double-press" event
• 2 - indicating "long-press" event

Other values can be converted using a value-map converter (as shown below).

Services

• button
• doorbell

Configuration

{
  "topics": {
    "pressEvent": {
      "get": "<read_topic>",
      "converter"?: {
        "single"?:  "value indicating a 'single' press event",
        "double"?:  "value indicating a 'double' press event",
        "long"?:    "value indicating a 'long' press event"
      }
    }
  }
}

dehumidifierThreshold

Describes the relative humidity dehumidifier threshold, representing the maximum relative humidity that must be reached before a dehumidifier is turned on. Expects a numeric value indicating the humidity in percentage between 0 and 100.

Other values can be converted using a Percentages converter (as shown below).

Services

• humidifier-dehumidifier

Configuration

{
  "topics": {
    "dehumidifierThreshold": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "decimal" | { "min": <number>, "max":  <number> }
    }
  }
}

humidifierThreshold

Describes the relative humidity humidifier threshold, representing the minimum relative humidity that must be reached before a humidifier is turned on. Expects a numeric value indicating the humidity in percentage between 0 and 100.

Other values can be converted using a Percentages converter (as shown below).

Services

• humidifier-dehumidifier

Configuration

{
  "topics": {
    "humidifierThreshold": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "decimal" | { "min": <number>, "max":  <number> }
    }
  }
}

rotationDirection

describes the direction of rotation of a fan. Expects the following numeric values:

• 0 - indicates clockwise direction
• 1 - indicates counter-clockwise direction

Other values can be converted using a value-map converter (as shown below).

Services

• fan

Configuration

{
  "topics": {
    "rotationDirection": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: { "clockwise": "value representing 'clockwise'", "counter-clockwise":  "value representing 'counter-clockwise'" }
    }
  }
}

rotationSpeed

Describes the rotation speed of a fan. A numeric value representing the speed as a percentage between 0 and 100, where 0 indicates no speed and 100 indicates maximum speed.

Other values are supported using the following converters:

• decimal - expects a values representing the speed as a percentage value between 0 and 1 (e.g. 0.36 indicates 36%)
• { "min": <number>, "max": <number> } - expects a value between the min and max value, from which it deduce the speed percentage.
• <number> - A converter holding a number indicates the number of supported speed levels, expecting a number between 0 and the configured number. For example, converter: 5 indicates there are 6 speed levels to look for - 0, 1, 2, 3, 4, 5.
• string[] - A converter holding an array of values, each representing a level. The speed level of each value is the index of that value in the array - the first value will always represent "no speed". For example, converter: [ "off", "low", "medium", "high" ] will expect all to receive any of these values. If, for example, it receives a low value, then it knows this value represents 33% speed level, as it's the first out of 3 possible speed levels (excl. the first one which is "no-speed").

Services

• fan
• humidifier-dehumidifier

Configuration

{
  "topics": {
    "rotationDirection": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "decimal" | { "min":  <number>, "max":  <number> } | <number> | string[]
    }
  }
}

saturation

Describes color saturation. A numeric value indicating a percentage.

Values can be converted using the Percentages converter.

Services

• lightbulb

Configuration

{
  "topics": {
    "saturation": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "decimal" | { "min": <number>, "max": <number> }
    }
  }
}

alarmType

describes the type of alarm triggered by a security system. The only alarm type that is currently supported by homekit is an "unknown" type. For this reason, by default, these are the values it expects:

• 0 - indicating the alarm is cleared
• any other value - indicating the generic "unknown" type.

It is possible to configure a different values to indicate the cleared state (as shown below)

Services

• security-system

Configuration

{
  "topics": {
    "alarmType": {
      "get": "<read_topic>",
      "converter"?: { "cleared":  "value representing a 'cleared` state"}
    }
  }
}

securitySystemCurrentState

!NOTE When used as part of a security-system service, this can be shorten to currentState

Describes the state of a security system. Expecting the following numeric values:

• 0 - "stay" state
• 1 - "away" state
• 2 - "night" state
• 3 - "disarmed" state
• 4 - "triggered" state

Other values can be converted using a value-map converter (as shown below).

Services

• security-system

Configuration

{
  "topics": {
    "securitySystemCurrentState": {
      "get": "<read_topic>",
      "converter"?: {
        "stay"?:      "'stay' state value",
        "away"?:      "'away' state value",
        "night"?:     "'night' state value",
        "disarmed"?:  "'disarmed' state value",
        "triggered"?: "'triggered' state value",
      }
    }
  }
}

securitySystemTargetState

!NOTE When used as part of a security-system service, this can be shorten to targetState

Describes the target state of the security system. Expecting the following numeric values:

• 0 - "stay" state
• 1 - "away" state
• 2 - "night" state
• 3 - "disarm" state

Other values can be converted using a value-map converter (as shown below).

It is also possible to limit the supported values using the validValues settings.

Services

• security-system

Configuration

{
  "topics": {
    "securitySystemTargetState": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: {
        "stay"?:      "'stay' state value",
        "away"?:      "'away' state value",
        "night"?:     "'night' state value",
        "disarm"?:    "'disarm' state value",
      },
      "validValues"?: string[] // e.g. [ "stay", "away", "disarm" ] to not show the 'night' option.
    }
  }
}

smokeDetected

Indicates if a sensor detects abnormal levels of smoke. By default, will look for 0 (indicating "not detected") or 1 (indicating "detected"). Values can be converted using the Booleans converter.

Services

• smoke-sensor

Configuration

{
  "topics": {
    "smokeDetected": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "<value indicating 'detected'>", "off": "value indicating 'not-detected'" }
    }
  }
}

so2Density

Indicates the current Sulphur Dioxide density. A numeric value in $micrograms/m^3$ units.

Services

• air-quality-sensor

Configuration

{
  "topics": {
    "so2Density": {
      "get": "<read_topic>"
    }
  }
}

statusFault

Indicates the device is faulty. Expecting a 1 indicating a "general fault" and 0 indicating there's no fault. Other values can be converted using the Booleans converter.

Services

This characteristic is optional on all services.

Configuration

{
  "topics": {
    "statusFault": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "'fault' value", "off":  "'no fault' value"}
    }
  }
}

statusLowBattery

Describes an accessory which has been tampered with. By default, will look for 0 indicating battery level is not low, and 1 indicating "low-battery" status. Other values can be converted using the Booleans converter.

Services

This characteristic is optional on all sensor services.

Configuration

{
  "topics": {
    "statusLowBattery": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "'low' status value", "off":  "'not-low' status value"}
    }
  }
}

statusTampered

Indicates if a battery-ran device is running low on battery. By default, will look for 0 indicating battery level is not low, and 1 indicating "low-battery" status. Other values can be converted using the Booleans converter.

Services

This characteristic is optional on all sensor services.

Configuration

{
  "topics": {
    "statusTampered": {
      "get": "<read_topic>",
      "converter"?: "boolean" | { "on": "'tampered' status value", "off":  "'not-tampered' status value"}
    }
  }
}

stickyOn

This is a special case of an 'on' characteristic that is associated with a value. When turned on, it publishes this value to the configured set topic, and it stays turned on until it receives a different value from the configured get topic. Trying to force it off will cause it to "silently" turn back on ("silently" in that it will not publish the value to the set topic).

Services

• stateful-scene

Configuration

{
  "topics": {
    "stickyOn": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "value": number | string | boolean // the published value
    }
  }
}

swingMode

Indicates if swing mode is enabled. By default, will look for 0 indicating swing "disabled" mode, and 1 indicating swing "enabled" mode. Other values can be converted using the Booleans converter.

Services

• fan
• humidifier-dehumidifier

Configuration

{
  "topics": {
    "swingMode": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "boolean" | { "on": "'enabled' mode value", "off":  "'disabled' mode value"}
    }
  }
}

targetFanState

!NOTE When used as part of a fan service, this can be shorten to targetState

Describes the target state of the fan. Expecting the following numeric values:

• 0 - indicates a "manual" state
• 1 - indicates an "auto" state

Other values can be converted using the value-map converter (as show below).

Services

• fan

Configuration

{
  "topics": {
    "targetFanState": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: { "auto": "'auto' state value", "manual":  "'manual' state value"}
    }
  }
}

targetHeatingCoolingState

!NOTE When used as part of a thermostat service, this can be shorten to targetState

Describes the target mode of a thermostat. Expects the following numeric values:

• 0 - indicating "off" state
• 1 - indicating "heat" state
• 2 - indicating "cool" state
• 3 - indicating "auto" state

Other values can be converted using a value-map converter (as shown below).

It is also possible to limit the possible values using the validValues setting.

Services

• thermostat

Configuration

{
  "topics": {
    "targetHeatingCoolingState": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: {
        "off"?:   "'off' state value",
        "heat"?:  "'heat' state value", 
        "cool"?:  "'cool' state value",
        "auto"?:  "'auto' state value",
      },
      "validValues": string[]  // e.g. [ "off", "auto" ] to only provide the user to stop the operation of the device
    }
  }
}

targetHorizontalTiltAngle

Describes the target angle of the horizontal slats of the device. A numeric value in arc degrees, ranging between -90 - 90.

Services

• window-covering

Configuration

{
  "topics": {
    "targetHorizontalTiltAngle": {
      "get": "<read_topic>",
      "set": "<write_topic>"
    }
  }
}

targetHumidifierDehumidifierState

!NOTE When used as part of a humidifier-dehumidifier service, this can be shorten to targetState

Describes the target state of a humidifier or/and a dehumidifier. Expecting the following numeric values:

• 0 - indicating humidifierDehumidifier state - only applicable to devices that are both humidifiers and dehumidifiers, this indicates that the device should always keep the humidity at bay, by both humidifying when humidity is low and dehumidifying when humidity is high (both low and high humidity levels are determined by the humidifierThreshold and dehumidifierThreshold characteristics.

• 1 - indicating humidifier state - only applicable to devices that are humidifiers. Indicating that the device should humidify if the humidity level is too low (reaches the humidifierThreshold).

• 2 - indicating dehumidifier state - only applicable to devices that are dehumidifiers. Indicating that the device should dehumidify if the humidity level is too hight (reaches the dehumidifierThreshold).

Other values can be converted using a value-map converter (as shown below).

Services

• humidifier-dehumidifier

Configuration

{
  "topics": {
    "targetHumidifierDehumidifierState": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: {
        "humidifierDehumidifier"?:  "'humidifierDehumidifier' state value",
        "humidifier"?:              "'humidifier' state value",
        "dehumidifier"?:            "'dehumidifier' state value"
      }
    }
  }
}

targetPosition

Describes the target position of accessories as a percentage value. 0 typically indicates "fully closed" while 100 indicates "fully open". Some services (e.g. window-covering let you reverse this). Other values can be converted using the Percentages converter.

Services

• window
• door
• window-covering

Configuration

{
  "topics": {
    "targetPosition": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
    }
  }
}

targetRelativeHumidity

Describes the target relative humidity that the device should actively attempt to reach. By default, expecting a numeric value between 0 and 100 representing a percentage. Other values can be converted using the Percentages converter.

Services

• thermostat

Configuration

{
  "topics": {
    "targetRelativeHumidity": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "decimal" | { "min": <number>,  "max": <number> }
    }
  }
}

targetTemperature

Describes the target temperature of the environment in Celsius. Other values can be converted using the Temperatures converter.

By default, values range between 10.0 and 38.0 with a minimum step of 0.1. This can be adjusted in the configuration (as shown below).

Services

• thermostat
• temperature-sensor

Configuration

{
  "topics": {
    "currentTemperature": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "fahrenheit",
      "minValue"?: <number>, // in celsius (regardless of the converter), defaut: 10.0 
      "maxValue"?: <number>, // in celsius (regardless of the converter), defaut: 38.0
      "minStep"?: <number>   // in celsius (regardless of the converter), defaut: 0.1
    }
  }
}

targetVerticalTiltAngle

Describes the target angle of the vertical slats of the device. Expecting a numeric value representing arc degrees between -90 and 90.

Services

• window-covering

Configuration

{
  "topics": {
    "targetVerticalTiltAngle": {
      "get": "<read_topic>",
      "set": "<write_topic>"
    }
  }
}

temperatureDisplayUnits

Describes units of temperature used for presentation purposes. Expecting the following numeric values:

• 0 - indicating celsius
• 1 - indicating fahrentheit

Other values can be converted using a value-map converter (as shown below).

Services

• thermostat

Configuration

{
  "topics": {
    "temperatureDisplayUnits": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: { "celsius": "value indicating 'celsius'", "fahrenheit": "value indicating 'fahrenheit'" }
    }
  }
}

vocDensity

Indicates the current volatile organic compound density. A numeric value in $micrograms/m^3$ units.

Services

• air-quality-sensor

Configuration

{
  "topics": {
    "vocDensity": {
      "get": "<read_topic>"
    }
  }
}

volume

Enables controlling the input or output volume of an audio device. By default, expecting a numeric value between 0 and 100 representing a percentage. Other values can be converted using the Percentages converter.

Services

• speaker
• doorbell

Configuration

{
  "topics": {
    "volume": {
      "get": "<read_topic>",
      "set": "<write_topic>",
      "converter"?: "decimal" | { "min": <number>, "max": <number> }
    }
  }
}

waterLevel

Indicating the current water level of the device. By default, expecting a numeric value between 0 and 100 representing a percentage. Other values can be converted using the Percentages converter.

Services

• humidifier-dehumidifier

Configuration

{
  "topics": {
    "waterLevel": {
      "get": "<read_topic>",
      "converter"?: "decimal" | { "min": <number>, "max": <number> }
    }
  }
}

Services Reference

• air-quality-sensor
• battery
• button
• co2-sensor
• contact-sensor
• co-sensor
• door
• doorbell
• fan
• humidifier-dehumidifier
• humidity-sensor
• leak-sensor
• lightbulb
• light-sensor
• lock
• microphone
• motion-sensor
• occupancy-sensor
• outlet
• security-system
• smoke-sensor
• speaker
• stateful-scene
• stateless-scene
• switch
• temperature-sensor
• thermostat
• window
• window-covering

air-quality-sensor

Characteristics:

• airQuality (required)
• airQuality (optional)
• ozoneDensity (optional)
• no2Density