├── 01-iOS独立开发简介.md ├── 02-SDK说明.md ├── 03-账户API简介.md ├── 04-设备API接口.md ├── 05-网络开发文档.md ├── 06-蓝牙开发文档.md ├── 07-TodayExtension文档.md ├── 08-国际化文档.md ├── 09-常见问题.md └── README.md /01-iOS独立开发简介.md: -------------------------------------------------------------------------------- 1 | 2 | # 米家独立sdk 开发文档 3 | 文档分七部分，如果只需要看链接WiFi设备，那么请看WiFi设备开发，如果需要链接蓝牙设备，那么请看蓝牙设备开发。 4 | 5 | - [SDK介绍](./2.SDK说明.md) 主要是介绍如何注册App和开通权限以及依赖库。 6 | - [账户API](./3.账户API简介.md) 账户相关API的使用，包括登录和获取用户信息。无论是蓝牙设备还是WiFi设备都必须看这一章。 7 | - [设备API接口](./4.设备API接口) 设备API接口 8 | - [WiFi设备开发](./5.网络开发文档.md) WiFi设备的常用使用API，包括WiFi快联，获取设备列表及控制WiFi设备。 9 | - [蓝牙设备开发](./6.蓝牙开发文档.md) 蓝牙设备常用API，包括Combo快联。蓝牙设备的连接API。 10 | - [Today Extension 开发](./7.TodayExtension文档.md) Today Extension的开发，以及于设备数据共享。 11 | - [国际化](./8.国际化文档.md) 国际化的注意事项 12 | - [常见问题](./9.常见问题.md) 常见问题解答。 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /02-SDK说明.md: -------------------------------------------------------------------------------- 1 | 2 | # SDK的文件构成 3 | 4 | 1. MiCombo_APConnectFramework: MiHome独立SDK的主体.封装了与设备快连,远程操作设备,拉取设备列表,帐号持久化等接口。 5 | 6 | 2. MiPassport: 小米官方给第三方开发者的基于OAuth2.0的账户登录SDK。 7 | 8 | ## SDK需要的条件 9 | 10 | 1. 注册 11 | 12 | 在[小米开放平台](http://dev.xiaomi.com/)注册小米账户服务。 取得appid，以及redirectURL。 13 | 14 | 2. 开通权限 15 | 16 | 1、在 “开放接口” 中 开启 “使用您的智能家庭服务“ 权限。 17 | 2、如果是在2018年6月1日后才申请的app，可能没有获取userId的权限，请使用公司邮件发送appid给负责对接的产品经理，开通获取userId的权限。 18 | 19 | 20 | # SDK 集成步骤 21 | 22 | 1. 本SDK统一使用CocoaPods管理。使用此SDK，请安装[CocoaPods](http://code4app.com/article/cocoapods-install-usage)。 23 | 本SDK需要关联的第三方库为： 24 | ``` 25 | pod 'AFNetworking','3.1.0' 26 | pod 'YYModel' 27 | ``` 28 | 2. 建立自己的工程，把两个framework（MiDeviceFramework，MiPassport）导入。 29 | ![导入framework](http://cdn.cnbj0.fds.api.mi-img.com/miio.files/commonfile_png_7b79a19d398bc7062b9947cd97fdcc81.png) 30 | 31 | 3. 改变工程的编译环境 32 | ![编译环境设置](http://cdn.cnbj0.fds.api.mi-img.com/miio.files/commonfile_png_f10d81ab5f1fd060aea93c9d927d1c65.png) 33 | 34 | 4. 完成上述步骤就可以正式开发了。 35 | -------------------------------------------------------------------------------- /03-账户API简介.md: -------------------------------------------------------------------------------- 1 | 2 | # 账户API 3 | 账户API 分三部分： 4 | 1. 初始化帐号系统 5 | 2. 登录 6 | 3. 获取账户信息 7 | 8 | 账户的主要类是MHAccount， 9 | ### 初始化帐号系统 10 | SDK需要登陆后才能操作设备，所以APP开发必须申请API和取得appid，以及redirectURL。当申请得到appid和redirectUrl后，在AppDelegate的application:didFinishLaunchingWithOptions: 方法中初始化账户 11 | 12 | ```objc 13 | - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { 14 | _account = [[MHAccount alloc] initWithAppId:@"申请的appid" redirectUrl:@"http://xiaomi.com"]; 15 | return YES; 16 | } 17 | ``` 18 | 19 | ### 登录 20 | 登录需要注册相关的通知事件，然后调用login 方法，权限为数组，更多的权限见[小米账户权限](https://dev.mi.com/docs/passport/scopes/) 21 | ```objc 22 | //注册相关通知 23 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(accountLogin:) name:MH_Account_Login_Sucess object:nil]; 24 | 25 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(accountLogout:) name:MH_Account_Logout_Sucess object:nil]; 26 | 27 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(accountLogCancel:) name:MH_Account_Login_Cancel object:nil]; 28 | 29 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(accountLoginFailure:) name:MH_Account_Login_Failure object:nil]; 30 | 31 | //登录 32 | [_account login:@[@1,@3,@6000]]; 33 | 34 | ``` 35 | 36 | ### 获取当前登录账户信息 37 | 当登录成功后， 可以调用fetchAccountProfile 方法获取登录账户的相关信息。MHAccountProfile 38 | ```objc 39 | -(void)accountLogin:(NSNotification*)notify { 40 | //保存登录信息 41 | BOOL saveResult = [UIAppDelegate.account save]; 42 | [_account fetchAccountProfile:^(MHAccountProfile *profile, NSError *error) { 43 | _profile = profile; 44 | NSLog(@"_profile.userId = %@",_profile.userId); 45 | }]; 46 | } 47 | 48 | ``` 49 | 50 | 51 | 52 | ### 注意事项 53 | 54 | MHAccount的login是一个异步请求，所以请在登录成功的回调中去拉取账户信息或者设备信息，而不是调用login方法后直接调用相关的方法。那样会因为账户没有登录成功而操作失败。代码类似如下 55 | ```objc 56 | - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { 57 | _account = [[MHAccount alloc] initWithAppId:@"申请的appid" redirectUrl:@"http://xiaomi.com"]; 58 | [self registerLoginNotifcation]; 59 | [_account login:@[@1,@3,@6000]]; 60 | return YES; 61 | } 62 | 63 | - (void)registerLoginNotifcation { 64 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(accountLogin:) name:MH_Account_Login_Sucess object:nil]; 65 | 66 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(accountLogout:) name:MH_Account_Logout_Sucess object:nil]; 67 | 68 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(accountLogCancel:) name:MH_Account_Login_Cancel object:nil]; 69 | 70 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(accountLoginFailure:) name:MH_Account_Login_Failure object:nil]; 71 | } 72 | 73 | -(void)accountLogin:(NSNotification*)notify { 74 | //保存登录信息。这个时候才表示登录成功，可以调用拉取设备列表，获取用户信息的API。 75 | BOOL saveResult = [UIAppDelegate.account save]; 76 | [_account fetchAccountProfile:^(MHAccountProfile *profile, NSError *error) { 77 | _profile = profile; 78 | NSLog(@"_profile.userId = %@",_profile.userId); 79 | }]; 80 | } 81 | ``` 82 | -------------------------------------------------------------------------------- /04-设备API接口.md: -------------------------------------------------------------------------------- 1 | 设备类的说明及常用API说明。 2 | 3 | 常用设备类 4 | ### 1. MHDevice.h 5 | 6 | 设备的基本信息。简单的理解为设备的基础数据结构 7 | 8 | ### 2. MHDevices.h 9 | 10 | 设备的一个集合。 11 | 12 | ### 3 MHDeviceManager.h 13 | 14 | 设备操作类。包含了拉取设备列表，获取新接入的设备，绑定设备，远程操作设备等接口。常见的API如下： 15 | 16 | #### 3.1 获取设备列表 （WiFi和蓝牙设备都可以获取） 17 | 18 | ```objc 19 | -(void)fetchDeviceListWithFilters:(NSArray*)dids 20 | DeviceListBlock:(void(^)(MHDevices* deviceList))deviceList 21 | failure:(void(^)(NSError* error))failure 22 | ``` 23 | 24 | param： dids，需要获取的设备属性的列表。如果想要获取指定设备的属性， 25 | 需要传入。如果默认拉取账户下所有的设备（包括蓝牙设备和WiFi设备），只需要传入nil。 26 | 27 | deviceListBlock：请求成功之后返回的设备列表。 28 | 29 | failure：请求失败返回的信息。 30 | 31 | 32 | #### 3.2 获取快连新接入的设备（WiFi设备或者Combo设备） 33 | ```objc 34 | -(void)fetchNewDeviceWith:(NSString*)ssid 35 | withBssid:(NSString*)bssid 36 | DeviceListBlock:(void(^)(MHDevices* deviceList))deviceList 37 | failure:(void(^)(NSError* error))failure; 38 | ``` 39 | param： ssid，路由器的ssid 40 | 41 | bssid，路由器的mac地址。设备需要跟路由器绑定。 42 | 有时需要返回整个局域网的设备。 43 | 44 | devicelistBlock：同上。 45 | 46 | failure：同上。 47 | 48 | #### 3.3 操作设备（只用于WiFi设备） 49 | ```objc 50 | -(void)callDeviceMethod:(MHDevice*) device 51 | method:(NSString *)method 52 | params:(id)params 53 | sucess:(void(^)(id result))sucess 54 | failure:(void(^)(NSError* error))failure; 55 | ``` 56 | 57 | param： device，需要操作的设备。 58 | method，具体的操作方法。 59 | params，操作需要传入的参数。 60 | sucess，操作成功的回调。 61 | failure，操作失败的回调。 62 | 63 | 64 | 65 | 3.4 设备分享 66 | 67 | ```objc 68 | -(void)shareDevice:(NSArray*)devices 69 | toUser:(NSString*)userId 70 | withType:(NSString*)type 71 | sucess:(void(^)(NSError* error))sucessBlock 72 | failure:(void(^)(NSError* error))failureBlock; 73 | ``` 74 | 75 | devices： 分享的设备 76 | 77 | userId： 小米账户ID。小米账户ID可以通过getUserProfile 来获得 78 | 79 | type: 分享类型:@""为可控制 @"readonly"为只读 80 | 81 | 82 | 83 | -------------------------------------------------------------------------------- /05-网络开发文档.md: -------------------------------------------------------------------------------- 1 | 2 | WiFI分为两部分， 3 | 1. API简介 4 | 2. API使用 5 | 6 | 7 | # API 简介 8 | 9 | ## 1. 设备操作接口 10 | 11 | ### 1.1 MHDeviceSmartConfig.h 设备快连的类 12 | ```objc 13 | -(void)startAPSmartConfigDeviceIp:(NSString*)deviceIp 14 | WithSSID:(NSString*)ssid 15 | WithBSSID:(NSString*)bssid 16 | password:(NSString*)password 17 | userId:(NSString*)userId 18 | domain:(NSString*)domain 19 | progressBlock:(void(^)(kSmartConfigState state, 20 | kSartConfigResult result,BOOL* stop))progressBlock; 21 | ``` 22 | param： deviceip，设备的ip地址。(demo中有获取设备ip的code) 23 | ssid： 路由器的ssid。 24 | bssid： 路由器的mac地址。（demo中有获取路由器mac地址的code） 25 | password:路由器的密码。 26 | userid：小米帐号的id。 27 | domain：用户所在的区域。 28 | progressBlock:每步快连后的回调，每一步快连后会通知快练当前的过程 29 | 以及成功的状态，以及是否进行下一步。 30 | 默认走完四步的话，整个快连就是一个完整的过程。 31 | 32 | ## 帐号网络相关接口 33 | 34 | ### 2.1 MHRequestSerializer.h 35 | 36 | #### 2.1.1 @protocol MHRequestConfig 37 | 这个protocol的作用是，如果一些需要自定义的参数需要在网络请求的时候加入的，需要一个comform这个 38 | protocol的实例。在这个里面你可以做任何事情，比如说把参数加密，或者在原有的参数的基础上增加某些 39 | 参数。 40 | 41 | #### 2.1.2 MHRequestBodySerializer 42 | 一个具体的实例。是把一些帐号信息加入到参数中 43 | 44 | #### 2.1.3 MHRequestCookieSerializer 45 | 一个具体的实例。把帐号信息设置成cookie。 46 | 47 | ### 2.2 MHNetworkEngine.h 48 | SDK的网络请求。 49 | ```objc 50 | +(void)callRemoteApi:(MHBaseRequest*)request 51 | httpMethod:(NSString*)method 52 | sucess:(void(^)(MHBaseRequest* request,id result))sucess 53 | failure:(void(^)(NSError* error))failure; 54 | ``` 55 | 自己继承MHBaseRequest,写一个自己的网络请求。然后发给小米的后台。前提 56 | 是你自己知道自己该调用哪个接口。 57 | 58 | param：request,自己重写的request。 59 | method,现在只支持GET。 60 | sucess，成功的返回。 61 | failure，失败后的返回。 62 | 63 | ## API 使用 64 | ### App开发 65 | App开发分三部分： 66 | 1. 快联设备 67 | 2. 获取设备列表 68 | 3. 操作设备 69 | 70 | #### 快连设备（如果已经快连，此步略过） 71 | 快联有三种方式： 72 | 1. AP方式 73 | 2. bindkey绑定方式 74 | 3. combo 快联（见[蓝牙文档 3.4 combo快联章节](./6.蓝牙开发文档.md#34-combo快联)） 75 | 76 | #### 1、AP方式快联 77 | APP要控制设备，需要先进行快联设备，告诉设备wifi 和对应的密码。设备快联成功后就可以操作设备了。(具体代码可以见Demo 程序中的 MHScanViewController.m 文件) 78 | ```objc 79 | - (void)authButtonClick:(id)sender{ 80 | _smartConfig = [[MHDeviceSmartConfig alloc] init]; 81 | [_smartConfig startAPSmartConfigDeviceIp:[self getRouterIp] 82 | WithSSID:@"Banana" 83 | WithBSSID:_bssid 84 | password:@"密码" 85 | userId:_profile.userId 86 | domain:@"cn" 87 | progressBlock:^(kSmartConfigState state, 88 | kSartConfigResult result, BOOL *stop) { 89 | NSLog(@"state = %d,result = %d",state,result); 90 | }]; 91 | } 92 | ``` 93 | #### 2、bindkey绑定方式 94 | 如果设备已经链接网络了，但是没有和小米帐号绑定，就需要要用bindkey的方式来绑定米家账户。 这时需要获取bindkey字符串，然后通过bindWithBindKey 方法来链接， 95 | ```objc 96 | -(void)init{ 97 | _deviceManager = [MHDeviceManager new]; 98 | } 99 | 100 | 101 | -(void)bind:(NSString*)bindKey{ 102 | [_deviceManager bindWithBindKey:bindKey success:^(id obj){ 103 | MHDeviceBindWithBindkeyResponse* rsp = (MHDeviceBindWithBindkeyResponse*)obj; 104 | if(rsp.ret == 0){ 105 | printf("绑定成功\r\n"); 106 | }else{ 107 | printf("绑定失败 errcode == %ld",rsp.ret); 108 | } 109 | 110 | } failure:^(NSError* err){ 111 | printf("bindKey fail\r\n"); 112 | }]; 113 | } 114 | 115 | [self init]; 116 | NSString* bindKey = @"";//获取的bindkey，通常是扫描二维码的方式得到 117 | [self bind:bindKey]; 118 | 119 | ``` 120 | 121 | #### 获取快联成功后的新设备 122 | 当快联成功后，想知道新添加的设备是那个。请使用fetchNewDeviceWith 来获得 123 | ```objc 124 | self.deviceManager = [MHDeviceManager new]; 125 | 126 | [self.deviceManager fetchNewDeviceWith:@"wifi名" withBssid:@"wifi名" withDeviceMac:nil channel:nil DeviceListBlock:^(MHDevices *devices) { 127 | NSLog(@"新设备是 %@",devices); 128 | } failure:^(NSError *error) { 129 | NSLog(@"%@",error); 130 | }]; 131 | ``` 132 | 133 | #### 获取设备列表 134 | 快联成后，就可以拉取设备列表，得到对应的Device。 135 | ```objc 136 | MHDeviceManager* manager = [MHDeviceManager new]; 137 | [manager fetchDeviceListWithFilters:nil DeviceListBlock:^(NSArray *devices) { 138 | NSLog(@"%@",devices); 139 | } failure:^(NSError *error) { 140 | NSLog(@"%@",error); 141 | }]; 142 | ``` 143 | 144 | 145 | #### 操作设备 146 | 获得设备之后，可以发对应的指令来操作，假设操作设备为一个插座，代码类似如下： 147 | 148 | ```objc 149 | NSString* method = @"set_power"; 150 | id params = nil; 151 | if (_isOn) { 152 | [self.oprationBtn setTitle:@"ON" forState:UIControlStateNormal]; 153 | params = @[@"off"]; 154 | }else{ 155 | [self.oprationBtn setTitle:@"OFF" forState:UIControlStateNormal]; 156 | params = @[@"on"]; 157 | } 158 | _isOn = !_isOn; 159 | [_deviceManager callDeviceMethod:_device method:method params:params sucess:^(id result) { 160 | NSLog(@"%@",result); 161 | } failure:^(NSError *error) { 162 | NSLog(@"%@",error); 163 | }]; 164 | ``` 165 | 更多的操作见 MiOprationController.m 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | -------------------------------------------------------------------------------- /06-蓝牙开发文档.md: -------------------------------------------------------------------------------- 1 | 2 | # MiBluetoothFramework 使用文档 3 | 如果单独使用蓝牙功能，需要MiBluetoothFramework.framework。如果是使用蓝牙WiFi使用 MiCombo_APConnectFramework.framework。这里单独介绍如何使用蓝牙Framework。如果WiFi蓝牙可以参见 [SDK](./2.SDK说明.md) 文档。 4 | 5 | ## 1 . Framework 构成 6 | 7 | 蓝牙设备根据绑定类型,分为不绑定,弱绑定,强绑定三种类型. 8 | 9 | 不绑定类型的framework构成:MiBluetoothFramework.framework 10 | 11 | 弱绑定,强绑定类型的framework构成: MiBluetoothFramework.framework , 12 | 13 | MiPassport.framework,MiPassport.bundle 14 | 15 | ## 2 .工程配置 16 | 如果是弱绑定,强绑定设备,那么需要网络操作,进行绑定,所以需要工程关联网络模块.本Framework 17 | 18 | 采用AFNetworking作为网络基础库.统一采用pod管理. 19 | 20 | ### 2.1 podfile 21 | 22 | ``` 23 | project 'MiSmartHomeBluetoothDemo.xcodeproj' 24 | target :MiSmartHomeBluetoothDemo do 25 | pod 'AFNetworking','~>3.1.0' 26 | end 27 | ``` 28 | 29 | ### 2.2 工程配置 30 | 工程需要按照以下图进行配置 31 | 32 | bitcode 设置 33 | ![bitcode](http://cdn.cnbj0.fds.api.mi-img.com/miio.files/commonfile_png_68553c5f7d727e4c3455e0f7e1a84a1e.png) 34 | 35 | other linker设置 36 | ![other linker Flags](http://cdn.cnbj0.fds.api.mi-img.com/miio.files/commonfile_png_0a8e8640c1a7212428b5cceec2f89265.png) 37 | 38 | compile source 设置 39 | ![compile source as](http://cdn.cnbj0.fds.api.mi-img.com/miio.files/commonfile_png_bde1426bc0eac0e6b98f610dd4d7c94b.png) 40 | 41 | ## 3. 接口说明 42 | 43 | ### 3.1 扫描设备 44 | 45 | MHBluetoothDiscovery 这个类主要的功能就是扫描普通的蓝牙设备.只是打开蓝牙的设备,都可以 46 | 扫描出来. 47 | 48 | ```objc 49 | [_bluetoothDiscovery startSearch:^(NSArray *bluetoothDevices,NSError* error) { 50 | if (error.code == 0) { 51 | weakSelf.bluetoothDevice = [bluetoothDevices mutableCopy]; 52 | [weakSelf.tableView reloadData]; 53 | }else if(error.code == CBManagerStatePoweredOff){ 54 | NSLog(@"请打开蓝牙"); 55 | } 56 | }]; 57 | ``` 58 | 59 | 60 | ### 3.2 连接设备 61 | 62 | MHXiaoMiConnectManager 这个类的主要功能是实现符合小米协议的蓝牙设备的连接操作.如果需要反复链接的话，可以保存MHXiaoMiConnectManager的实例。 63 | 64 | ```objc 65 | MHBluetoothDevice* device = _bluetoothDevice[indexPath.row]; 66 | 67 | NSData* token = [[NSUserDefaults standardUserDefaults] valueForKey:@"loginToken"]; 68 | if ([token length]) { 69 | if (device) { 70 | MHXiaoMiConnectManager* connectManager = [[MHXiaoMiConnectManager alloc] init]; 71 | [connectManager loginXiaoMiBluetoothDeviceWith:device loginToken:token 72 | miDevice:^(MHXiaoMiBluetoothDevice * _Nullable bleDevice) { 73 | if (bleDevice) { 74 | NSLog(@"成功login符合小米协议的设备"); 75 | }else{ 76 | NSLog(@"login 失败"); 77 | } 78 | }]; 79 | } 80 | }else{ 81 | if (device) { 82 | MHXiaoMiConnectManager* connectManager = [[MHXiaoMiConnectManager alloc] init]; 83 | [connectManager registerXiaoMiBluetoothDeviceWith:device miDevice:^(MHXiaoMiBluetoothDevice *bleDevice) { 84 | if (bleDevice) { 85 | NSLog(@"成功注册一个符合小米协议的设备"); 86 | //存储一下logintoken 300c84ca 3a261223 446376c0 87 | NSLog(@"loginToken = %@",bleDevice.loginToken); 88 | [[NSUserDefaults standardUserDefaults] setValue:bleDevice.loginToken forKey:@"loginToken"]; 89 | [[NSUserDefaults standardUserDefaults] synchronize]; 90 | }else{ 91 | NSLog(@"register 失败"); 92 | } 93 | }]; 94 | } 95 | } 96 | ``` 97 | 当不在需要MHXiaoMiConnectManager 连接后，请调用 MHXiaoMiConnectManager的disconnect的方法，释放对象。 98 | 99 | 如果想了解蓝牙连接设备的连接情况，可以调用 MHXiaoMiConnectManager 的 registerCentralManagerDelegate方法，并且实现CBCentralManagerDelegate 定义的方法，就可以知道在蓝牙连接过程中 连接是否断开。 100 | 101 | ### 3.3 蓝牙设备生成 102 | 103 | MHBluetoothDeviceFactory 可以通过传入package生成一个MHBluetoothDevice . 104 | 105 | MHBluetoothBroadcastPackage 通过传入的最原始的蓝牙数据生成一个package. 106 | 原始数据是通过NSDictionary 传入,对应的key-value 107 | 108 | ```objc 109 | data[@"centralManager"] = centralManager; 110 | data[@"peripheral"] = peripheral; 111 | data[@"advertisementData"] = advertisementData; 112 | data[@"RSSI"] = RSSI 113 | ``` 114 | 115 | ### 3.4 combo快联 116 | 如果设备支持WIFI和蓝牙，就是combo快联设备，combo快联第一步也是调用MHBluetoothDiscovery 发现设备，然后通过comboConnect api去链接设备，连接代码类似如下 117 | ```objc 118 | _comboConnect = [[MHComboConnectManager alloc] init]; 119 | _comboConnect.uid = @"用户账户"; 120 | _comboConnect.ssid = @"wifi名"; 121 | _comboConnect.password = @"密码"; 122 | _comboConnect.country = comboConnectCountryChina; //服务器位置 123 | 124 | [_comboConnect comboConnect:device success:^{ 125 | NSLog(@"commbo sucess"); 126 | } failure:^(NSError *error) { 127 | 128 | }]; 129 | ``` 130 | 131 | ###3.5. 私人定制 132 | 133 | 如果不需要我们的sdk提你扫描蓝牙设备,可以通过MHBluetoothDeviceFactory传入package生成一个MHBluetoothDevice,然后传给MHXiaoMiConnectManager,让我们的sdk替你实现连接即可. 134 | 135 | ## Demo 136 | MiSmartHomeBluetoothDemo 包括两种连接，一种是批量链接设备，一种是单点链接某个设备。 137 | 138 | 1、批量链接设备的代码见bluetoothController.m的beginLoop 方法。 139 | 140 | 2、单点链接的代码见bluetoothController.m的tableview:didSelectRowAtIndexPath: 方法 141 | 142 | -------------------------------------------------------------------------------- /07-TodayExtension文档.md: -------------------------------------------------------------------------------- 1 | 2 | # Today Extension 开发 3 | 如果想开发iOS的today Extension。 设备访问的 API跟App 一样，但是widget没有登陆界面，所以watch和app共享账户信息。不然网络请求会发送失败 4 | 5 | ## 主app 登陆后，需要保存共享信息，代码类似如下（具体代码参见 ViewController.m 的 fecthDatas 方法） 6 | ```objc 7 | - (void)setWidgetShareData{ 8 | NSUserDefaults *shared = [[NSUserDefaults alloc] initWithSuiteName:@"group.mismarthome.1"]; 9 | NSDictionary* dict = [MHPassport accountLoginParameters]; 10 | [shared setObject:dict forKey:@"group.mismarthome.1.dict"]; 11 | [shared synchronize]; 12 | } 13 | ``` 14 | 15 | ## Today Extension 发送网络请求 16 | 17 | 首先自定义MHRequestSerializer 的子类。 18 | ```objc 19 | @interface MHPGHPassportSerializer : MHRequestSerializer 20 | @property (nonatomic, copy) NSString *locale; 21 | @end 22 | 23 | @implementation MHPGHPassportSerializer 24 | -(NSDictionary*)configHttpRequest:(NSDictionary*)parameters{ 25 | NSUserDefaults *shared = [[NSUserDefaults alloc] initWithSuiteName:@"group.mismarthome.1"]; 26 | 27 | NSDictionary* dict = [shared objectForKey:@"group.mismarthome.1.dict"]; 28 | NSMutableDictionary* mDict = [[NSMutableDictionary alloc] initWithCapacity:10]; 29 | if(dict){ 30 | [mDict addEntriesFromDictionary:dict]; 31 | } 32 | if(parameters){ 33 | [mDict addEntriesFromDictionary:parameters]; 34 | } 35 | 36 | return mDict; 37 | } 38 | ``` 39 | 当today Extension 发送请求的时候，设置自定义的Serializer 40 | 41 | ```objc 42 | _deviceManager = [MHDeviceManager new]; 43 | _deviceManager.serializer = [MHPGHPassportSerializer serializer]; 44 | [_deviceManager fetchDeviceListWithFilters:nil DeviceListBlock:^(MHDevices* deviceList) { 45 | _devices = [deviceList.devices copy]; 46 | [self sendRPC]; 47 | } failure:^(NSError *error) { 48 | NSLog(@"%@",error); 49 | }]; 50 | ``` 51 | 52 | 53 | -------------------------------------------------------------------------------- /08-国际化文档.md: -------------------------------------------------------------------------------- 1 | 2 | # 国际化 3 | 如果要做国际化的请求，需要自己设置调用MHBaseRequest的 setupBaseRequestUrl:的方法设置对应的请求服务器。 4 | 5 | 默认为中国的地址（https://openapp.io.mi.com/openapp），不需要设置 6 | 7 | 如果要请求美国的地址，徐需要在openapp前面加us。请求url变为 8 | https://us.openapp.io.mi.com/openapp 9 | 10 | ```objc 11 | [MHBaseRequest setupBaseRequestUrl:@"https://us.openapp.io.mi.com/openapp"] 12 | ``` -------------------------------------------------------------------------------- /09-常见问题.md: -------------------------------------------------------------------------------- 1 | 2 | # 常见问题 3 | 1. 分享是通过 -(void)shareDevice:(NSArray*)devices toUser:(NSString *)userId withType:(NSString *)type sucess:(void (^)(NSError *))sucessBlock failure:(void (^)(NSError *))failureBlock 来分享的，但是只接受小米id的方式，如果拿到用户小米id，可以通过 getUserProfile 方法来获取用户信息再分享。 4 | 5 | 2. combo快联是集合了蓝牙和WiFi。所以它有两个mac地址。所以combo 快联设备不能使用mac地址来做key，因为快联前拿到的是蓝牙的mac地址，但是成功后获取的是WiFi 模块的mac地址。两者不一样。 6 | 7 | 3. 如果无法快联设备，可以尝试一下办法 8 | ``` 9 | 3.1 如果设备还没有发布，固件是否已经按规范实现，比如combo快联的时候，固件提前结束连接过程，导致SDK无法获取信息。从而快联失败 10 | 11 | 3.2 检查账户是否在白名单内，不在白名单内的用户无法快联。 12 | 13 | 3.3 如果账户在白名单内，使用Demo 程序快联。看是否成功。 如果能成功，检查一下代码与Demo中有什么不一样的地方。 14 | 15 | 3.4 如果Demo 快联失败，使用米家App 快联一下。如果米家也不能成功，检查一下固件的实现。应该是固件实现的有问题。 16 | ``` 17 | 18 | 4. SDK只支持小米账户登录的方式，不支持第三方的账户登录方式。使用第三方登录方式会导致SDK一些功能无法使用。比如设备无法拉取，无法控制设备。 19 | 5. 小米账户SDK在2018年6月1号后不会返回userId，导致SDK无法使用，如果你的App是在2018年6月1号以后申请的，麻烦联系负责对接的产品经理,把AppId給他，我们会找小米账号的同学开通权限。 20 | 6. MiHomeSDK.framework 是老版本的SDK。目前已经不再维护。如要使用最新功能，请使用最新版本的SDK。如果只是维护，但是私有API问题，可以询问对接产品经理，下载移除版本。 21 | 7. SDK中内置了小米账户的SDK，如果同时添加新的小米账户SDK，可能会导致接受不到登录成功的push。 22 | 8. SDK的下载地址请咨询负责对接的产品经理。 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | # ** 最新文档请访问 [米家开发平台](https://iot.mi.com/new/guide.html?file=首页) 开发引导** github以后不再更新 3 | ## 米家独立sdk 开发文档 4 | 文档分七部分，如果只需要看链接WiFi设备，那么请看WiFi设备开发，如果需要链接蓝牙设备，那么请看蓝牙设备开发。 5 | 6 | - [SDK介绍](./2.SDK说明.md) 主要是介绍如何注册App和开通权限以及依赖库。 7 | - [账户API](./3.账户API简介.md) 账户相关API的使用，包括登录和获取用户信息。无论是蓝牙设备还是WiFi设备都必须看这一章。 8 | - [设备API接口](./4.设备API接口) 设备API接口 9 | - [WiFi设备开发](./5.网络开发文档.md) WiFi设备的常用使用API，包括WiFi快联，获取设备列表及控制WiFi设备。 10 | - [蓝牙设备开发](./6.蓝牙开发文档.md) 蓝牙设备常用API，包括Combo快联。蓝牙设备的连接API。 11 | - [Today Extension 开发](./7.TodayExtension文档.md) Today Extension的开发，以及于设备数据共享。 12 | - [国际化](./8.国际化文档.md) 国际化的注意事项 13 | - [常见问题](./9.常见问题.md) 常见问题解答。 14 | 15 | 16 | 17 | 18 | --------------------------------------------------------------------------------