IOS Device Pairing SDK (HomeKit Certified Devices)

This SDK includes the logical part and UI interface of Aqara device network distribution; the iOS version that the SDK depends on cannot be lower than 11.0
Compiler environment: XCode14.0 or above
Language: Object-C

Integrated SDK

1.Environment Build

The Device Pairing SDK needs to use the permission functions of HomeKit and Wi-Fi, and the host project needs to add the following Capability:

1. Homeikit
2. Wireless Accessory Configuration

2.Permission Profile

The SDK needs to apply to iOS for the following system permissions:

1.NSHomeKitUsageDescription Access to HomeKit 2.NSCameraUsageDescription Camera access permission (scan the QR code on the device for network configuration) 3.NSLocalNetworkUsageDescription Local network search authority (Device Pairing by LAN) 4.NSLocationWhenInUseUsageDescription Use geographic location permission (mobile phone obtains WiFi name, iOS 13 needs to confirm that the App has enabled the location permission. iOS 14 needs to confirm that the App has enabled the precise location permission. If the WiFi name is still not obtained after the above configuration, the developer needs to deal with it separately, such as Manually enter the WiFi name).

1. NSBluetoothAlwaysUsageDescription Obtain Bluetooth permission (Device Pairing by Bluetooth)
2. NSBonjourServicesUse the mDNS service to discover Greenmi devices, and set the service name "_aqara._tcp."

You can quickly add the following configuration in the info.plist file of the host project:

<plist version="1.0">
   <key>NSBonjourServices</key>
   <array>
          <string>_aqara._tcp.</string>
   </array>
   <key>NSCameraUsageDescription</key>
   <string>Allows the app to use the camera to add accessories</string>
   <key>NSHomeKitUsageDescription</key>
   <string>Allow this App to control HomeKit-enabled devices</string>
   <key>NSLocalNetworkUsageDescription</key>
   <string>Need to use local network to discover device information on LAN</string>
   <key>NSLocationWhenInUseUsageDescription</key>
   <string>Need your location information to provide better service</string>
   <key>NSBluetoothAlwaysUsageDescription</key>
   <string>Allow this app to use bluetooth connection</string>
</dict>
</plist>

4.Import SDK

The following SDK needs to be imported in the host project:

1. LMAppleHomeConnect.framework HomeKit-related API packaging SDK
2. LMFramework.framework Basic SDK, basic configuration of Aqara, macro definition and encapsulation of general logic

Resource:

1. LMFramework.bundle Aqara multilingual files

5.Sequence Diagram and Description

Reference header file #import <LMAppleHomeConnect/LMAppleHomeConnect.h>

Get HomeKit permissions at the right time:

- (void)requestHomeKitAuthroization:(void (^)(NSError *error))completion;

Interface 1

- (void)getHomekitHomes:(void (^)(NSArray<HMHome *> * _Nullable homeList, NSError *error))compleiton;

This interface will return the home information list under HomeKit in the closure. If the data returned by the interface is empty, it may be due to the following reasons:

1. Check if the AppleID has enabled keychain permissions.
2. Open Apple's Home APP to see if there is family data.

Interface 2

- (void)addAccessoryWithHome:(HMHome *)home settingDoneCompletion:(void (^)(NSArray <HMAccessory *> *accessoryList, NSError *error))completion;

Calling this interface will pop up the HomeKit configuration window:

After the method closure returns HMAccessory object data, initiate a bindkey request to AIoT.

Request 3

Obtain bindkey request from AIoT:

/app/v1.0/lumi/dev/bindkey

Request example:

{
 "positionId":  "real2.550691449629310976",
 "appUrl": "https://aiot-rpc.aqara.cn"
}

Return data: |Name|Type |Remark| |----|----|---| |bindKey|string|Network access using bindKey| |controlUnitId|string|Parameters returned by the miot device connected to the network|

Return example:

{
    "code": 0,
    "requestId": "",
    "message": "Success",
    "result": {
        "bindKey": "HVFLFgHgPy56X"
    }
}

**For details, please refer to the Aqara Developer Platform Interface Documentation.

Interface 4

- (void)bindAccessory:(HMAccessory *)accessory countryDomain:(NSString *)countryDomain bindKey:(NSString *)bindKey compeltion:(void (^)(NSError *error))completion;

Request 5

Polling the request result to AIoT:

/app/v1.0/lumi/dev/bind/query

Request data

Return data

Return example:

{
    "code": 0,
    "requestId": "",
    "message": "Success",
    "result": {
        "code": 0
    }
}  

For details, please refer to the Aqara Developer Platform Interface Documentation.