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 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	int	0, 1	0: Normal, 1: Tampered
StatusFault	int	0, 1	0: Normal, 1: Fault

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 list of Characteristics. Use this table to help determine which values and formats may be sent to each service node.

Characteristic	Format	Accepted values	Notes
AccessControlLevel	int	0-2
AccessoryFlags	int
Active	int	0,1	0: inactive, 1: active. Default: 0
ActivityInterval	int	>=0
AdministratorOnlyAccess	bool	true,false
AirParticulateDensity	float	0-1000
AirParticulateSize	int	0,1	0: 2.5M, 1: 10M. Default: 0
AirQuality	int	0,1,2,3,4,5	0: unknown,1: excellent,2: good,3: fair,4: inferior,5: poor
AudioFeedback	bool
BatteryLevel	int	0-100
Brightness	int	0-100
CameraOperatingModeIndicator	int	0,1	0: disable, 1: enable. Default: 0
CarbonDioxideDetected	int	0,1	0: normal, 1: abnormal. Default: 0
CarbonDioxideLevel	float	0-100000
CarbonDioxidePeakLevel	float	0-100000
CarbonMonoxideDetected	int	0,1	0: normal, 1: abnormal. Default: 0
CarbonMonoxideLevel	float	0-100
CarbonMonoxidePeakLevel	float	0-100
CCAEnergyDetectThreshold	int
CCASignalDetectThreshold	int
CharacteristicValueTransitionControl	TLV8
ChargingState	int		0: not charging, 1: charging, 2: not chargeable. Default: 0
ColorTemperature	int	140-500
ContactSensorState	int		0: detected, 1: not detected. Default: 0
CoolingThresholdTemperature	float10-35
CurrentAirPurifierState	int	0,1,2	0: inactive, 1: idle, 2: active. Default: 0
CurrentAmbientLightLevel	float	0.0001-100000
CurrentDoorState	int	0,1,2,3,4	0: open, 1: closed, 2: opening, 3: closing, 4: stopped. Default: 0
CurrentFanState	int	0,1,2	0: inactive, 1: idle, 2: active. Default: 0
CurrentHeaterCoolerState	int	0,1,2,3	0: inactive, 1: idle, 2: heating, 3: cooling. Default: 0
CurrentHeatingCoolingState	int	0,1,2	0: off, 1: heat, 2: cool. Default: 0
CurrentHorizontalTiltAngle	int	-90-90
CurrentHumidifierDehumidifierState	int		0: inactive, 1: idle, 2: humidifying, 3: dehumidifying. Default: 0
CurrentPosition	int	0-100
CurrentRelativeHumidity	float	0-100
CurrentSlatState	int	0,1,2	0: fixed, 1: jammed, 2: swinging. Default: 0
CurrentTemperature	float	0-100
CurrentTiltAngle	int	-90-90
CurrentTransport	bool	true,false
CurrentVerticalTiltAngle	int	-90-90
DataStreamHAPTransport	TLV8
DataStreamHAPTransportInterrupt	TLV8
DigitalZoom	float
EventRetransmissionMaximum	int
EventSnapshotsActive	int	0,1	0: disable, 1: enable. Default: 0
EventTransmissionCounters	int
FilterChangeIndication	int	0,1	0: filter ok, 1: change filter. Default: 0
FilterLifeLevel	float	0-100
FirmwareRevision	string
HardwareRevision	string
HeatingThresholdTemperature	float	0-25	step: 0.1
HoldPosition	bool	true,false
HomeKitCameraActive	int	0,1	0: off, 1: on. Default: 0
Hue	float	0-360	step: 1
Identify	bool	true,false
ImageMirroring	bool	true,false
ImageRotation	float	0-270	step: 90
InUse	int		0: not in use, 1: in use. Default: 0
IsConfigured	int	0,1	0: not configured, 1: configured
LeakDetected	int	0,1	0: not detected, 1: detected. Default: 0
LockControlPoint	TLV8
LockCurrentState	int	0,1,2,3	0: unsecured, 1: secured, 2: jammed, 3: unknown. Default: 0
LockLastKnownAction	int	0,1,2,3,4,5,6,7,8	0: secured physically interior, 1: unsecured physically interior, 2: secured physically exterior, 3: unsecured physically exterior, 4: secured by keypad, 5: unsecured by keypad, 6: secured remotely, 7: unsecured remotely, 8: secured by timeout. Default: 0
LockManagementAutoSecurityTimeout	int		Seconds
LockPhysicalControls	int	0,1	0: lock disabled, 1: lock enabled. Default: 0
LockTargetState	int	0,1	0: unsecured, 1: secured. Default: 0
Logs	TLV8
MACRetransmissionMaximum	int
MACTransmissionCounters	binary data
ManagedNetworkEnable	int	0,1,2	0: disabled, 1: enabled, 2: unknown. Default: 0
ManuallyDisabled	int	0,1	0: enabled, 1: disabled. Default: 0
Manufacturer	string
Model	string
MotionDetected	bool	true,false
Mute	bool	true,false
Name	string
NetworkAccessViolationControl	TLV8
NetworkClientProfileControl	TLV8
NetworkClientStatusControl	TLV8
NightVision	bool	true,false
NitrogenDioxideDensity	float	0-1000	step: 1
ObstructionDetected	bool	true,false
OccupancyDetected	int	0,1	0: not detected, 1: detected
On	bool	true,false
OperatingStateResponse	TLV8
OpticalZoom	float
OutletInUse	bool	true,false
OzoneDensity	float	0-1000	step: 1
PairingFeatures	int
PairingPairings	TLV8
PairSetup	TLV8
PairVerify	TLV8
PasswordSetting	TLV8
PeriodicSnapshotsActive	int	0,1	0: disable, 1: enable
Ping	binary data
PM10Density	float	0-1000	step: 1
PM2_5Density	float	0-1000	step: 1
PositionState	int	0,1,2	0: deing, 1: increasing, 2: stopped. Default: 0
ProductData
ProgrammableSwitchEvent	int	0,1,2	0: single press, 1: double press, 2: long press
ProgramMode	int	0,1,2	0: no program scheduled, 1: program scheduled, 2: manual mode. Default: 0
ReceivedSignalStrengthIndication	int
ReceiverSensitivity	int
RecordingAudioActive	int	0,1	0: disable, 1: enable. Default: 0
RelativeHumidityDehumidifierThreshold	float	0-100
RelativeHumidityHumidifierThreshold	float	0-100	step: 1
RemainingDuration	int	0-3600	step: 1
ResetFilterIndication	int	0,1	0: not indicated, 1: indicated. Default: 0
RotationDirection	int	0,1	0: clockwise, 1: anticlockwise. Default: 0
RotationSpeed	float	0-100	step: 1
RouterStatus	int	0,1	0:y. 1: noty. Default: 0
Saturation	float	0-100	step: 1
SecuritySystemAlarmType	int	0,1	0: no alarm, 1: alarm. Default: 0
SecuritySystemCurrentState	int	0,1,2,3,4	0: stay armed, 1: away armed, 2: night armed, 3: disarmed, 4: alarm triggered. Default: 0
SecuritySystemTargetState	int	0,1,2,3	0: stay armed, 1: away armed, 2: night armed, 3: disarmed. Default 0
SelectedCameraRecordingConfiguration	TLV8
SelectedRTPStreamConfiguration	TLV8
SerialNumber	string
ServiceLabelIndex	int	0-255
ServiceLabelNamespace	int	0,1	0: dots, 1: numerals. Default: 0
SetDuration	int	0-3600
SetupEndpoints	TLV8
SetupTransferTransport	TLV8
SignalToNoiseRatio	int
SlatType	int	0,1	0: horizontal, 1: vertical. Default: 0
SleepInterval	int	>=0
SmokeDetected	int	0,1	0: not detected, 1: detected. Default: 0
StatusActive	bool	true,false
StatusFault	int	0,1	0: no fault, 1: fault. Default: 0
StatusJammed	int	0,1	0: not jammed, 1: jammed. Default: 0
StatusLowBattery	int	0,1	0: normal, 1: low. Default: 0
StatusTampered	int	0,1	0: not tampered, 1: tampered. Default: 0
StreamingStatus	TLV8
SulphurDioxideDensity	float	0-1000	step: 1
SupportedAudioRecordingConfiguration	TLV8
SupportedAudioStreamConfiguration	TLV8
SupportedCameraRecordingConfiguration	TLV8
SupportedCharacteristicValueTransitionConfiguration	TLV8
SupportedDiagnosticsSnapshot	TLV8
SupportedRouterConfiguration	TLV8
SupportedRTPConfiguration	TLV8
SupportedTransferTransportConfiguration	TLV8
SupportedVideoRecordingConfiguration	TLV8
SupportedVideoStreamConfiguration	TLV8
SwingMode	int	0,1	0: disabled, 1: enabled. Default: 0
TargetAirPurifierState	int	0,1	0: manual, 1: auto. Default: 0
TargetAirQuality	int	0,1,2	0: excellent, 1: good, 2: fair. Default: 0
TargetDoorState	int	0,1	0: open, 1: closed. Default: 0
TargetFanState	int	0,1	0: manual, 1: auto. Default: 0
TargetHeaterCoolerState	int	0,1,2	0: auto, 1: heat, 2: cool. Default: 0
TargetHeatingCoolingState	int	0,1,2,3	0: off, 1: heat, 2: cool, 3: auto. Default: 0
TargetHorizontalTiltAngle	int	-90-90	step: 1
TargetPosition	int	0-100
TargetRelativeHumidity	float	0-100	step: 1
TargetSlatState	int	0,1	0: manual, 1: auto. Default: 0
TargetTemperature	float	10-38	step: 0.1. In celsius
TargetTiltAngle	int	-90-90	step: 1
TargetVerticalTiltAngle	int	-90-90	step: 1
TemperatureDisplayUnits	int	0,1	0: celsius, 1: fahrenheit. Default: 0
ThirdPartyCameraActive	int	0,1	0: off, 1: on. Default: 0
TransmitPower	int
TransmitPowerMaximum	int
ValveType	int	0,1,2,3	0: generic valve, 1: irrigation, 2: shower head, 3: water faucet. Default: 0
Version	string
VideoAnalysisActive	int
VOCDensity	float	0-1000	step: 1
Volume	int	0-100
WakeConfiguration	TLV8
WANConfigurationList	TLV8
WANStatusList	TLV8
WaterLevel	float	0-100
WiFiCapabilities	int
WiFiConfigurationControl	TLV8
WiFiSatelliteStatus	int	0,1,2	0: unknown, 1: connected, 2: not connected. Default: 0