HomeKit Accessory Protocol Specification (Non-Commercial Version)

256 Pages·2017·1.49 MB·English

by  Apple Inc.

HomeKit Accessory
Protocol Specification
(Non-Commercial Version)
Release R1
Contents
Document Revision History 15
1. Introduction 22
1.1Requirements,Recommendations,andPermissions 22
1.2Terminology 23
1.2.1Accessory,Device,andProduct 23
1.2.2Component 23
1.2.3Feature 23
2. Core Concepts 24
2.1Transports 24
2.2Security 24
2.2.1Pairing 24
2.2.2SessionKeys 25
2.3Attributes 25
2.3.1Accessories 25
2.3.2Services 25
2.3.3Characteristics 26
2.3.4AdditionalHomeKitAccessoryProtocolRequirements 28
2.4Profiles 28
2.5Roles 29
2.5.1HAPClient 29
2.5.2HAPAccessoryServer 29
2.5.3HAPAccessoryObjects 29
2.6 Accessory Attribute Database 30
2.6.1 Instance IDs 30
3. Requirements 32
3.1 Overview 32
3.2 General Requirements 32
3.3 Wi-Fi Requirements 32
3.4 Firmware Updates 33
3.5 Coalescing Requirements 33
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
2
Contents
4. Pairing 34
4.1Overview 34
4.2CryptographicKeyStorage 34
4.3SetupCodes 34
4.3.1DisplayingSetupCodes 34
4.3.2InvalidSetupCodes 35
4.4Admins 36
4.5DeviceID 36
4.6SecureRemotePassword(SRP) 36
4.6.1SRPModifications 36
4.6.2SRPTestVectors 36
4.7PairSetup 39
4.7.1M1:iOSDevice->Accessory--`SRPStartRequest' 39
4.7.2M2:Accessory->iOSDevice--`SRPStartResponse' 40
4.7.3M3:iOSDevice->Accessory--`SRPVerifyRequest' 41
4.7.4M4:Accessory->iOSDevice--`SRPVerifyResponse' 41
4.7.5M5:iOSDevice->Accessory--`ExchangeRequest' 43
4.7.6M6:Accessory->iOSDevice--`ExchangeResponse' 45
4.8PairVerify 47
4.8.1M1:iOSDevice->Accessory--`VerifyStartRequest' 47
4.8.2M2:Accessory->iOSDevice--`VerifyStartResponse' 48
4.8.3M3:iOSDevice->Accessory--`VerifyFinishRequest' 49
4.8.4M4:Accessory->iOSDevice--`VerifyFinishResponse' 50
4.9FragmentationandReassembly 51
4.10AEADAlgorithm 51
4.11AddPairing 51
4.11.1M1:iOSDevice->Accessory--`AddPairingRequest' 51
4.11.2M2:Accessory->iOSDevice--`AddPairingResponse' 52
4.12RemovePairing 53
4.12.1M1:iOSDevice->Accessory--`RemovePairingRequest' 54
4.12.2M2:Accessory->iOSDevice--`RemovePairingResponse' 54
4.13ListPairings 55
4.13.1M1:iOSDevice->Accessory--`ListPairingsRequest' 55
4.13.2M2:Accessory->iOSDevice--`ListPairingsResponse' 56
4.14PairingoverBluetoothLE 56
4.14.1PairingService 57
4.15PairingoverIP 59
4.16Methods,ErrorCodes,andTLVValues 60
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
3
Contents
5. HomeKit Accessory Protocol for IP Accessories 62
5.1Overview 62
5.2Requirements 62
5.2.1IPRequirements 62
5.2.2BonjourRequirements 62
5.2.3TCPRequirements 63
5.2.4HTTPServerRequirements 63
5.2.5ApplicationRequirements 63
5.2.6GeneralRequirements 63
5.3HAPObjects 63
5.3.1AccessoryObjects 63
5.3.2ServiceObjects 64
5.3.3CharacteristicObjects 64
5.4Discovery 68
5.5SecurityforIPAccessories 70
5.5.1Pairing 70
5.5.2SessionSecurity 70
5.6IPAccessoryAttributeDatabase 71
5.6.1ServiceandCharacteristicTypes 72
5.6.2GettingtheAccessoryAttributeDatabase 72
5.6.3ExampleAccessoryAttributeDatabaseinJSON 73
5.7ControllingIPAccessories 79
5.7.1HandlingHTTPRequests 79
5.7.2WritingCharacteristics 80
5.7.3ReadingCharacteristics 84
5.7.4ControlPointCharacteristics 87
5.7.5IdentifyRoutine 87
5.7.6IdentifyHTTPURL 88
5.8Notifications 88
5.8.1AccessoryUpdatesStateNumberInternally 89
5.8.2AccessorySendsEventstoController 89
5.9HTTPURLs 91
5.10TestingIPAccessories 92
6. HomeKit Accessory Protocol for Bluetooth LE Accessories 94
6.1Overview 94
6.2AccessoryRequirements 94
6.3HAPforBluetoothLE 94
6.3.1HAPTransactionsandProcedures 94
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
4
Contents
6.3.2AttributeDatabaseAuthentication 95
6.3.3HAP-BLEPDUFormat 95
6.3.4HAP-BLEPDUPayloads 100
6.3.5HAPProcedures 104
6.3.6HAPStatusCodes 116
6.3.7Pair-ResumeProcedure 116
6.4BluetoothLE 122
6.4.1Generalrequirements 122
6.4.2HAPBLE2.0AdvertisementFormat 123
6.4.3HAP-BLE2.0ProtocolInformationService 126
6.4.4AttributesofHAPServicesandCharacteristics 126
6.4.5AdditionalHAPCharacteristicRequirements 131
6.4.6HAPNotifications 133
6.4.7Security 133
6.4.8FirmwareUpdateRequirements 135
6.5 Testing Bluetooth LE Accessories 135
7.This chapter has been omitted
8.Apple-defined Characteristics 144
8.1 Overview 144
8.1.1 Overriding Properties 144
8.2 Administrator Only Access 145
8.3 Audio Feedback 145
8.4 Brightness 145
8.5 Cooling Threshold Temperature 146 8.6
Current Door State 146
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
5
Contents
8.7CurrentHeatingCoolingState 147
8.8CurrentRelativeHumidity 148
8.9CurrentTemperature 148
8.10FirmwareRevision 149
8.11HardwareRevision 150
8.12HeatingThresholdTemperature 151
8.13Hue 151
8.14Identify 152
8.15LockControlPoint 152
8.16LockCurrentState 153
8.17LockLastKnownAction 153
8.18LockManagementAutoSecurityTimeout 154
8.19LockTargetState 155
8.20Logs 155
8.21Manufacturer 156
8.22Model 156
8.23MotionDetected 156
8.24Name 157
8.25ObstructionDetected 157
8.26On 157
8.27OutletInUse 158
8.28RotationDirection 158
8.29RotationSpeed 159
8.30Saturation 159
8.31SerialNumber 160
8.32TargetDoorState 160
8.33TargetHeatingCoolingState 161
8.34TargetRelativeHumidity 162
8.35TargetTemperature 162
8.36TemperatureDisplayUnits 163
8.37Version 164
8.38AirParticulateDensity 164
8.39AirParticulateSize 164
8.40SecuritySystemCurrentState 165
8.41SecuritySystemTargetState 166
8.42BatteryLevel 167
8.43CarbonMonoxideDetected 167
8.44ContactSensorState 168
8.45CurrentAmbientLightLevel 169
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
6
Contents
8.46CurrentHorizontalTiltAngle 169
8.47CurrentPosition 170
8.48CurrentVerticalTiltAngle 170
8.49HoldPosition 171
8.50LeakDetected 171
8.51OccupancyDetected 172
8.52PositionState 173
8.53ProgrammableSwitchEvent 174
8.54StatusActive 174
8.55SmokeDetected 175
8.56StatusFault 175
8.57StatusJammed 176
8.58StatusLowBattery 177
8.59StatusTampered 178
8.60TargetHorizontalTiltAngle 178
8.61TargetPosition 179
8.62TargetVerticalTiltAngle 179
8.63SecuritySystemAlarmType 180
8.64ChargingState 181
8.65CarbonMonoxideLevel 181
8.66CarbonMonoxidePeakLevel 182
8.67CarbonDioxideDetected 182
8.68CarbonDioxideLevel 183
8.69CarbonDioxidePeakLevel 183
8.70AirQuality 184
8.71StreamingStatus 185
8.72SupportedVideoStreamConfiguration 185
8.73SupportedAudioStreamConfiguration 188
8.74SupportedRTPConfiguration 190
8.75SetupEndpoints 191
8.76SelectedRTPStreamConfiguration 194
8.77Volume 197
8.78Mute 197
8.79NightVision 198
8.80OpticalZoom 198
8.81DigitalZoom 199
8.82ImageRotation 199
8.83ImageMirroring 200
8.84AccessoryFlags 201
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
7
Contents
8.85LockPhysicalControls 201
8.86CurrentAirPurifierState 202
8.87CurrentSlatState 202
8.88SlatType 203
8.89FilterLifeLevel 204
8.90FilterChangeIndication 204
8.91ResetFilterIndication 205
8.92TargetAirPurifierState 205
8.93TargetFanState 206
8.94CurrentFanState 207
8.95Active 207
8.96SwingMode 208
8.97CurrentTiltAngle 209
8.98TargetTiltAngle 210
8.99OzoneDensity 210
8.100NitrogenDioxideDensity 211
8.101SulphurDioxideDensity 211
8.102PM2.5Density 211
8.103PM10Density 212
8.104VOCDensity 212
8.105ServiceLabelIndex 213
8.106ServiceLabelNamespace 213
8.107ColorTemperature 214
9. Apple-defined Services 216
9.1AccessoryInformation 216
9.2Fan 216
9.3GarageDoorOpener 217
9.4Lightbulb 217
9.5LockManagement 218
9.6LockMechanism 219
9.7Outlet 219
9.8Switch 219
9.9Thermostat 220
9.10AirQualitySensor 220
9.11SecuritySystem 221
9.12CarbonMonoxideSensor 222
9.13ContactSensor 222
9.14Door 223
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
8
Contents
9.15HumiditySensor 224
9.16LeakSensor 224
9.17LightSensor 225
9.18MotionSensor 225
9.19OccupancySensor 226
9.20SmokeSensor 226
9.21StatelessProgrammableSwitch 227
9.22TemperatureSensor 228
9.23Window 228
9.24WindowCovering 229
9.25BatteryService 230
9.26CarbonDioxideSensor 230
9.27CameraRTPStreamManagement 231
9.28Microphone 231
9.29Speaker 232
9.30Doorbell 232
9.31Fanv2 233
9.32Slat 233
9.33FilterMaintenance 234
9.34AirPurifier 235
9.35ServiceLabel 236
10. Apple-defined Profiles 237
10.1Overview 237
10.2Lock 237
10.2.1LockMechanismService 237
10.2.2LockManagementService 237
11. IP Cameras 240
11.1Overview 240
11.2Requirements 240
11.2.1StreamingRequirements 240
11.2.2OptionalRequirements 241
11.3ServiceDefinitions 241
11.3.1IPCamera 241
11.3.2VideoDoorbellProfile 241
11.4RTPconfiguration 242
11.4.1RTCPBasedFeedback 242
11.4.2RTPExtensionforCoordinationofVideoOrientation 244
11.4.3ReconfiguringaStreamingSession 244
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
9
Contents
11.5ImageSnapshot 245
11.6IPCameraStreamingProcedure 246
11.7MultipleCameraRTPStreamManagement 248
11.8MediaCodecs 248
11.8.1MandatoryVideoRTPServiceSettings 248
11.8.2MandatoryAudioRTPservicesettings 249
11.8.3MandatoryRTPProfile 249
11.9MediaTransport 250
11.10TestingIPCameras 250
12. Appendix 251
12.1TLVs 251
12.1.1TLVRules 251
12.1.2TLVExamples 252
12.2AccessoryCategories 254
2017-06-07 | Copyright © 2017 Apple Inc. All Rights Reserved.
10