Characteristic Properties

Updated July 19, 2022 by luwol03, Shaquu and GogoVega

What is a Characteristic Property and how to use it.

What is that

A Service node is made up of one or more characteristics. The Characteristic Properties tell the Home.app to adapt its display to the chosen settings. It also allows you to define default values and usage limitations.

How to use it

Go to the section called Characteristic Properties of your HomeKit Service Node.

Characteristic Properties

To indicate that some Characteristic is used:

{ "Characteristic": true }

To indicate a default value for some characteristic (20 for example):

{ "Characteristic": {"defaultValue": 20 }}

Usage Limitation

To tell the Home.app some usage limitations on a characteristic:

Option Description
defaultValue Value by default
minValue Minimum value authorized
maxValue Maximum value authorized
minStep Minimum step (gap) authorized
validValues Value authorized [ ]

Examples

Below is an example list of characteristics.

Window covering with tilt option and default value

{
  "TargetHorizontalTiltAngle": {
    "defaultValue": 45,
    "minValue": 0,
    "maxValue": 90
  }
}

On/off bulb (No optional characteristics: empty JSON object)

{}

Dimmable bulb (Enable optional characteristic Brightness)

{
  "Brightness": true
}

Color changing bulb (Enable optional characteristics Brightness, Hue, Saturation)

{
  "Brightness": true,
  "Hue": true,
  "Saturation": true
}

Color Temperature bulb

It is also possible to define the range of the lightbulb if it has a light that can change temperature. You should watch out, that these values are in Reciprocal megakelvin so you have to ‘convert’ to this if your lamp is using Kelvin values (1000000 / Kelvin).

{
  "ColorTemperature": {
    "minValue": 150,
    "maxValue": 500
  }
}

Dimmable bulb with 5% increments

{
  "Brightness": {
    "minStep": 5
  }
}

Security system with no “night” mode

{
  "SecuritySystemCurrentState": {
    "validValues": [0, 1, 3, 4]
  },
  "SecuritySystemTargetState": {
    "validValues": [0, 1, 3, 4]
  }
}

Valve with only “irrigation” valve type (will show in Home.app as sprinkler)

{
  "ValveType": {
    "minValue": 1,
    "maxValue": 1
  }
}

Edit this page on GitHub