Characteristics

Characteristics are the values sent to the service item. They are generally true/false or number values. All services have at least one required characteristic. For example the switch has only the required characteristic of On.

Characteristic Properties#

The HomeKit service node has a section called “Characteristic Properties”. This section is used to define limits or initialize which characteristics you may send to your specific item.

The characteristic properties do not set any value in the item, instead they tell HomeKit that the item will be using that characteristic and define limits on the valid values.

Here are some examples of how Characteristic Properties work. These will be moved to their respective example pages as more documentation is written (help wanted).

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 which 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
    }
}

General Characteristics#

Some characteristics are available to almost all services but do not do much to change the use of the item in the Home.app. For example Active, Tampered, or Fault. These characteristics are optional and are used to show extra status information in the Home.app.

This list is not meant to be a comprehensive or exhaustive list of general characteristics.

When these values are used, the detail screen of your accessory will show new fields under “status” to display these values. Example:

Edit this page on GitHub