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 or initialize which characteristics you may send to your specific item.

An example of this is a simple light bulb, a dimmable light bulb, and a color changing light bulb. The "Characteristic Properties" field for each of these items would be: On/off bulb:

{}

Dimmable bulb:

{"Brightness":true}

Color changing bulb

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

The characteristic properties are used to tell the Home app the properties of the bulb, they do not send any values to Brightness, Hue, or Saturation.

Available Characteristics

Here is a non-comprehensive 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
Cooling threshold	float	10 - 35	Celsius, step value = 0.1
Current door state	uint8	0 - 4	Open=0, closed=1, opening=2, closing=3, stopped=4
Current heating cooling state	uint8	0 - 4	Off=0, heat=1, cool=2
Current relative humidity	float	0 - 100	Percentage, step value = 1
Current temperature	float	0 - 100	Celsius, step value = 0.1
Heating threshold temperature	float	0 - 25	Celsius, step value = 0.1
Hue	float	0 - 360	Arcdegrees, step value = 1
Lock current state	uint8	0 - 3	Unsecured=0, secured=1, jammed=2, unknown=3
Lock target state	uint8	0, 1	Unsecured=0, secured=1
Motion detected	bool	true/false
Obstruction detected	bool	true/false
On	bool	true/false
Outlet in use	bool	true/false
Rotation direction	int	0, 1	Clockwise=0, counter clockwise=1
Rotation speed	int	0 - 100	Percentage, step value = 1
Saturation	float	0 - 100	Percentage, step value = 1
Target door state	uint8	0, 1	Open=0, closed=1
Target heating cooling state	uint8	0 - 3	Off=0, heat=1, cool=2, auto=3
Target relative humidity	float	0 - 100	Percentage, step value = 1
Target temperature	float	10 - 38	Celsius, step value = 0.1
Temperature display units	uint8	0, 1	Celsius=0, Fahrenheit=1
Air particulate density	float	0 - 1000	Micrograms/m^3
Security system current state	uint8	0 - 4	Stay armed=0, away armed=1, night armed=2, disarmed=3, alarm triggered=4
Security system target state	uint8	0 - 4	Stay armed=0, away armed=1, night armed=2, disarmed=3
Battery level	uint8	0 - 100	Percentage, step value = 1
Carbon monoxide detected	uint8	0, 1	Normal=0, abnormal (danger)=1
Contact sensor state	uint8	0, 1	Contact detected=0, contact not detected=1
Current ambient light level	float	0.0001 - 100,000	Lux (lumens/m^2)
Current horizontal tilt angle	int	-90 - 90	Arcdegrees, step value = 1
Current position	uint8	0 - 100	Percentage, step value = 1
Current vertical tilt angle	int	-90 - 90	Arcdegrees, step value = 1
Hold position	bool	true/false	Used to stop a door or window immediately
Leak detected	uint8	0, 1	No leak=0, leak detected=1
Occupancy detected	uint8	0, 1	Not occupied=0, occupied=1
Position state	uint8	0 - 2	Going to minimum value=0, going to maximum value=1, stopped=2
Programmable switch event	uint8	0 - 2	Single press=0, double press=1, long press=2
Status active	bool	true/false	True indicates the accessory is active and has no errors
Smoke detected	uint8	0, 1	Smoke not detected=0, smoke detected=1
Status jammed	uint8	0, 1	Not jammed=0, jammed=1
Status low battery	uint8	0, 1	Normal battery=0, low battery=1
Status tampered	uint8	0, 1	Normal=0, tampered=1
Target horizontal tilt angle	int	-90 - 90	Arcdegrees, step value = 1
Target position	uint8	0 - 100	Percentage, step value = 1
Target vertical tilt angle	int	-90 - 90	Arcdegrees, step value = 1
Carbon monoxide level	float	0 - 100	Carbon monoxide level in parts per million
Carbon monoxide peak level	float	0 - 100	Carbon monoxide peak level in parts per million
Carbon dioxide detected	uint8	0, 1	Normal=0, abnormal=1
Carbon dioxide level	float	0 - 100,000	Carbon dioxide level in parts per million
Carbon dioxide peak level	float	0 - 100,000	Carbon dioxide peak level in parts per million
Air quality	uint8	0 - 5	Unknown=0, excellent=1, good=2, fair=3, inferior=4, poor=5
Current air purifier state	uint8	0 - 2	Inactive=0, idle=1, purifying=2
Current slat state	uint8	0 - 2	Fixed=0, jammed=1, swinging=2
Slat type	uint8	0, 1
Target air purifier state	uint8	0, 1	Manual=0, auto=1
Target fan state	uint8	0, 1	Manual=0, auto=1
Current fan state	uint8	0 - 2	Inactive=0, idle=1, blowing air=2
Active	uint8	0, 1	Inactive=0, active=1
Swing mode	uint8	0, 1	Swing disabled=0, swing enabled=1
Current tilt angle	int	-90 - 90	Arcdegrees, step value = 1
Target tilt angle	int	-90 - 90	Arcdegrees, step value = 1
Ozone density	float	0 - 1,000	Micrograms/m^3
Nitrogen dioxide density	float	0 - 1,000	Micrograms/m^3
Sulphur dioxide density	float	0 - 1,000	Micrograms/m^3
PM2.5 density	float	0 - 1,000	Micrograms/m^3
PM10 density	float	0 - 1,000	Micrograms/m^3
VOC density	float	0 - 1,000	Micrograms/m^3
Color temperature	uint32	50 - 400	Reciprocal megakelvin, step value=1