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

{}

Dimmable bulb

{
    "Brightness":true
}

Color changing bulb

{
    "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 this 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.

Characteristic	Format	Accepted Values	Notes
StatusActive	bool	true/false	True indicates the accessory is active and has no errors
StatusTampered	uint8	0, 1	Normal=0, tampered=1
StatusFault	uint8	0, 1	Normal=0, fault=1

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

Available Characteristics

Here is a non-exhaustive list of services. Use this table to help determine which values and formats may be sent to each service node.

Characteristic	Format	Accepted Values	Notes
Brightness	int	0 - 100	Percentage, step value = 1
CoolingThreshold	float	10 - 35	Celsius, step value = 0.1
CurrentDoorState	uint8	0 - 4	Open=0, closed=1, opening=2, closing=3, stopped=4
CurrentHeatingCoolingState	uint8	0 - 4	Off=0, heat=1, cool=2
CurrentRelativeHumidity	float	0 - 100	Percentage, step value = 1
CurrentTemperature	float	-100 - 100	Celsius, step value = 0.1
HeatingThresholdTemperature	float	0 - 25	Celsius, step value = 0.1
Hue	float	0 - 360	Arcdegrees, step value = 1
LockCurrentState	uint8	0 - 3	Unsecured=0, secured=1, jammed=2, unknown=3
LockTargetState	uint8	0, 1	Unsecured=0, secured=1
MotionDetected	bool	true/false
ObstructionDetected	bool	true/false
On	bool	true/false
OutletInUse	bool	true/false
RotationDirection	int	0, 1	Clockwise=0, counter clockwise=1
RotationSpeed	int	0 - 100	Percentage, step value = 1
Saturation	float	0 - 100	Percentage, step value = 1
TargetDoorState	uint8	0, 1	Open=0, closed=1
TargetHeatingCoolingState	uint8	0 - 3	Off=0, heat=1, cool=2, auto=3
TargetRelativeHumidity	float	0 - 100	Percentage, step value = 1
TargetTemperature	float	10 - 38	Celsius, step value = 0.1
TemperatureDisplayUnits	uint8	0, 1	Celsius=0, Fahrenheit=1
AirParticulateDensity	float	0 - 1000	Micrograms/m^3
SecuritySystemCurrentState	uint8	0 - 4	Stay armed=0, away armed=1, night armed=2, disarmed=3, alarm triggered=4
SecuritySystemTargetState	uint8	0 - 4	Stay armed=0, away armed=1, night armed=2, disarmed=3
BatteryLevel	uint8	0 - 100	Percentage, step value = 1
CarbonMonoxideDetected	uint8	0, 1	Normal=0, abnormal (danger)=1
ContactSensorState	uint8	0, 1	Contact detected=0, contact not detected=1
CurrentAmbientLightLevel	float	0.0001 - 100,000	Lux (lumens/m^2)
CurrentHorizontalTiltAngle	int	-90 - 90	Arcdegrees, step value = 1
CurrentPosition	uint8	0 - 100	Percentage, step value = 1
CurrentVerticalTiltAngle	int	-90 - 90	Arcdegrees, step value = 1
HoldPosition	bool	true/false	Used to stop a door or window immediately
LeakDetected	uint8	0, 1	No leak=0, leak detected=1
OccupancyDetected	uint8	0, 1	Not occupied=0, occupied=1
PositionState	uint8	0 - 2	Going to minimum value=0, going to maximum value=1, stopped=2
ProgrammableSwitchEvent	uint8	0 - 2	Single press=0, double press=1, long press=2
StatusActive	bool	true/false	True indicates the accessory is active and has no errors
SmokeDetected	uint8	0, 1	Smoke not detected=0, smoke detected=1
StatusJammed	uint8	0, 1	Not jammed=0, jammed=1
StatusLowBattery	uint8	0, 1	Normal battery=0, low battery=1
StatusTampered	uint8	0, 1	Normal=0, tampered=1
TargetHorizontal tilt angle	int	-90 - 90	Arcdegrees, step value = 1
TargetPosition	uint8	0 - 100	Percentage, step value = 1
TargetVertical tilt angle	int	-90 - 90	Arcdegrees, step value = 1
CarbonMonoxideLevel	float	0 - 100	Carbon monoxide level in parts per million
CarbonMonoxidePeakLevel	float	0 - 100	Carbon monoxide peak level in parts per million
CarbonDioxideDetected	uint8	0, 1	Normal=0, abnormal=1
CarbonDioxideLevel	float	0 - 100,000	Carbon dioxide level in parts per million
CarbonDioxidePeakLevel	float	0 - 100,000	Carbon dioxide peak level in parts per million
AirQuality	uint8	0 - 5	Unknown=0, excellent=1, good=2, fair=3, inferior=4, poor=5
CurrentAirPurifierState	uint8	0 - 2	Inactive=0, idle=1, purifying=2
CurrentSlatState	uint8	0 - 2	Fixed=0, jammed=1, swinging=2
SlatType	uint8	0, 1
TargetAirPurifierState	uint8	0, 1	Manual=0, auto=1
TargetFanState	uint8	0, 1	Manual=0, auto=1
CurrentFanState	uint8	0 - 2	Inactive=0, idle=1, blowing air=2
Active	uint8	0, 1	Inactive=0, active=1
SwingMode	uint8	0, 1	Swing disabled=0, swing enabled=1
CurrentTiltAngle	int	-90 - 90	Arcdegrees, step value = 1
TargetTiltAngle	int	-90 - 90	Arcdegrees, step value = 1
OzoneDensity	float	0 - 1,000	Micrograms/m^3
NitrogenDioxideDensity	float	0 - 1,000	Micrograms/m^3
SulphurDioxideDensity	float	0 - 1,000	Micrograms/m^3
PM2.5Density	float	0 - 1,000	Micrograms/m^3
PM10Density	float	0 - 1,000	Micrograms/m^3
VOCDensity	float	0 - 1,000	Micrograms/m^3
ColorTemperature	uint32	50 - 400	Reciprocal megakelvin, step value=1