WiFi产品 Android SDK 2.0 集成指南

boboP · 发表于 2016-8-8 11:11:56

1. 设备接入SDK概述
1.1. SDK目的与功能

机智云的设备接入SDK（以下简称SDK）封装了手机（包括PAD等设备）与机智云智能硬件的通讯过程，以及手机与云端的通讯过程。这些过程包括配置入网、发现、连接、控制、心跳、状态上报、报警通知等。使用SDK，可以使得开发者快速完成APP开发，开发者仅需关注APP的UI和UE设计即可，而相对复杂的协议与错误处理等事项可忽略。

1.2. 机智云物联方案概况

1.3. 找到最合适的SDK

机智云目前提供3套SDK：iOS平台原生SDK、Android平台原生SDK、APICloud跨平台SDK。开发者可以根据项目需要自行选择，其中APICloud版本SDK可以用H5技术一次开发，同时适配iOS和Android两个平台，具体内容请参考：《APICloud SDK 集成指南》。

1.4. 相关名词定义1.4.1. GAgent

全称Gizwits Agent，运行于Wi-Fi模块中，设备通过GAgent接入机智云服务器。目前已兼容国内主流的Wi-Fi模块，开发者也可以通过获取GAgent二次开发包实现自定义的模块接入机智云。

1.4.2. 小循环

智能设备与手机、智能设备与智能设备之间，通过连接同一个路由器实现局域网内部的通信（查看状态或控制），我们称之为小循环。

1.4.3. 大循环

智能设备通过路由器或直接接入互联网以实现用户的远程监测与控制，我们称为大循环。

1.4.4. ProductKey

产品标识码，开发者通过机智云后台创建新产品后，自动生成的一个32位字符串。在机智云的数据库中是一个唯一的号码，开发者完成开发写入设备主控MCU后，机智云通过此标识码对设备进行识别并自动完成注册。

1.4.5. DID

设备号，当一个设备初次接入机智云时，机智云自动根据ProductKey以及设备Wi-Fi模块MAC地址为此设备注册一个did，此did全网唯一，用于与用户的绑定及后续操作。

1.4.6. PassCode

设备通行证，用于校验用户的绑定/控制权限。当用户发起设备绑定时，只要是合法操作即可拿到此通行证，通过此通行证绑定设备并对设备进行有效期内的查看、控制等操作。GAgent首次运行时生成随机数作为设备通行证，生成后保存在非易失性存储器上。设备上线时需要上报给服务器。

1.4.7. AppID

应用标识码，当开发者需要为一款智能产品开发应用（包括iOS、Android、Web应用等）时，后台会自动生成一个AppID，并与此设备进行关联。应用开发时需要填入此AppID。

1.4.8. Onboarding

也叫配置入网，用户将一款基于Wi-Fi的物联网设备配置连接上路由器的过程称为Onboarding。新设备第一次使用时需要知道路由器的账号和密码，以通过路由器连接互联网。由于大多数的物联网设备没有自带的屏幕和键盘，所以需要通过智能手机向设备发送路由器的SSID和密码，这个过程机智云称为Onboarding。机智云提供的Wi-Fi设备接入SDK中已经内置了此配置的功能。

1.4.9. AirLink

机智云对各种SmartConfig、SmartLink这种UDP广播报方式对设备配置入网的技术统称，兼容了多个Wi-Fi模块厂商的配置协议，总结了一套良好用户体验的标准Onboarding操作流程，机智云的Wi-Fi 设备接入SDK已经内置AirLink技术。

1.4.10. SoftAP

由于目前各个Wi-Fi模块厂商的Smart Config协议均未完全成熟，也不支持5G路由器信号。机智云在提供了AirLink配置模式的同时也支持SoftAP模式配置设备接入路由器。当设备进入SoftAP配置模式时，设备本身将成为一个AP，智能手机可直接与设备进行连接，然后在手机上的界面上输入路由器的SSID和密码，设备接收到信息的时候会自动尝试连接路由器，连接成功则自动切换到正常使用的模式。

1.5. 集成准备1.5.1. 注册机智云账号

在使用机智云服务前，你需要通过site.gizwits.com注册一个开发者账号。请完整填写你的注册信息。此部分请参考《快速入门》。

1.5.2. 新建设备接入

此部分请参考《快速入门》。

1.5.3. 获得 app ID 和产品标识码（productkey）

此部分请参考《快速入门》。

1.5.4. 下载SDK

1.5.5. 导入SDK

第一步，双击解开压缩包 GizWifiSDK-Android-xxx.zip。

第二步，将解压后的libs目录下所有内容拷贝到指定工程的libs目录，保证下图红框中的文件都加载到了工程中：

boboP · 发表于 2016-8-8 11:22:28

本帖最后由 boboP 于 2016-8-8 11:23 编辑

2. SDK流程简介
2.1. 通用流程图

2.2. 关键点说明

SDK已经封装了所有的用户、配置、发现、连接、控制的过程，开发者使用这些API可以完成上述流程中的功能开发，不需要再自行实现通讯协议。
SDK采取回调的工作方式，所以必须设置必要的监听，比如通用监听和设备监听，具体请参见流程详解。SDK在主线程中给APP回调。
SDK支持APP在Activity之间以及在Activity和Service之间传递对象。

1、如果是在activity之间传递对象的话可以用intent来传递

（传递）

Intent intent = new Intent(Context, A.class);
Bundle bundle = new Bundle();
bundle.putParcelable(“参数名”, 设备类对象);
intent.putExtras(bundle);
startActivity(intent);

复制代码

（接收）

Intent intent = getIntent();
intent.getParcelableExtra("参数名");

复制代码

2、在activity和service之间传递对象可以通过广播来传递数据，由一方发送数据另一方接收。

（注册广播）

IntentFilter filter = new IntentFilter();//创建IntentFilter对象
//注册一个广播，用于接收Activity传送过来的命令，控制Service的行为，如：发送数据，停止服务等
filter.addAction("AAAAAAA");
//注册Broadcast Receiver
registerReceiver(cmdReceiver, filter); s

复制代码

（发送广播）

Intent intent = new Intent();
intent.setAction("AAAAAAA");
Bundle bundle = new Bundle();
bundle.putParcelable(“参数名”, 设备类对象);
intent.putExtras(bundle);
sendOrderedBroadcast(intent, null);

复制代码

3、另外一种，是在Activity中通过bindService获取到Service对象，直接调用Service方法获取想要的设备对象

2.3. 混淆打包配置

如果您的项目使用了Proguard混淆打包，为了避免SDK被二次混淆导致无法正常使用SDK，请务必在 proguard-project.txt中添加以下代码：

-libraryjars libs/GizWifiSDK.jar
-dontwarn com.gizwits.**
-keep class com.gizwits.**{
*;
}

复制代码

并在project.properties中指向Android混淆文件：

proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt

boboP · 发表于 2016-8-8 11:29:09

3.1. SDK初始化部分
3.1.1. 初始化部分流程图

3.1.2. 配置AndroidManifest.xml

请将下面权限配置代码复制到 AndroidManifest.xml 文件中：

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />

复制代码

权限说明：

[td]

权限	用途
ACCESS_NETWORK_STATE	允许程序访问有关GSM网络信息
ACCESS_WIFI_STATE	允许程序访问WiFI网络状态信息
READ_PHONE_STATE	允许程序访问手机状态信息
ACCESS_COARSE_LOCATION	允许程序访问CellID或WiFi热点来获取粗略的位置
ACCESS_FINE_LOCATION	允许程序访问精良位置（如GPRS）
WRITE_EXTERNAL_STORAGE	允许程序写入外部SD卡
INTERNET	允许程序打开网络接口
CHANGE_WIFI_STATE	允许程序改变WiFi连接状态
CHANGE_WIFI_MULTICAST_STATE	允许程序改变WiFi多播状态

3.1.3. 注册SDK通用**

注册SDK通用**是为了能让APP收到来自GizWifiSDK类的响应事件，包含了注册、登录、配置设备、绑定设备等回调接口。该**是SDK使用中十分重要的一个**，与GizWifiSDK类相关的操作都会在这里会回调。如果没有正确注册通用**，将无法正常使用SDK。注册监听时，APP可以根据自己的需求实现回调接口。建议两种设置方式：

1、在每一个使用到的Activity中都实例化一次**并注册一次，且只实现需要的回调接口。该种方式比较灵活，可在service中使用。但要注意必须每次打开activity都监听一次，且无法多个Activity同时收到回调。

【示例代码】

// 实例化**
GizWifiSDKListener mListener = new GizWifiSDKListener() {
// 实现手机号注册用户回调
@Override
public void didRegisterUser(GizWifiErrorCode result, String uid, String token){
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 注册成功，处理注册成功的逻辑
} else {
// 注册失败，处理注册失败的逻辑
}
}
};
public void onCreate() {
super.onCreate();
// 注册**
GizWifiSDK.sharedInstance().setListener(mListener);
// 调用SDK的手机号注册接口
GizWifiSDK.sharedInstance().registerUser("HelloGizwits", "12345678");
}

复制代码

2、在一个基类中实例化一次**，并把回调抛出，子类继承基类，这就不需要每个子类都实例化一次**。该种方式通过继承的方式，可以多个Activity都收到回调。但该种方式无法在Service中使用。如无特别说明，文档中的范例都是使用该方法注册**。

【示例代码】

// 创建基类，在基类中实例化和注册**
public class BaseActivity extends Activity {
private GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didRegisterUser(GizWifiErrorCode result, String uid, String token) {
BaseActivity.this.didRegisterUser(result, uid, token);
}
};
public void didRegisterUser(GizWifiErrorCode result, String uid, String token){
// 实现逻辑
}
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
//每次启动activity都要注册一次sdk**，保证sdk状态能正确回调
GizWifiSDK.sharedInstance().setListener(mListener);
}
}
//子类继承基类，实现基类的回调接口。
public class TestActivity extends BaseActivity {
protected void onCreate(android.os.Bundle savedInstanceState) {
//调用父类方法
super.onCreate(savedInstanceState);
//调用用户注册方法
GizWifiSDK.sharedInstance().registerUser ("your_phone_number", "your_ password", “your_verify_code”, GizUserAccountType.GizUserPhone);
}
@Override
public void didRegisterUser(GizWifiErrorCode result, String uid, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 注册成功
} else {
// 注册失败
}
}
}

复制代码

3.1.4. 初始化 sdk

SDK启动前，任何功能都是无法正常使用的。SDK启动时，会进行SDK初始化，并自动发现当前局域网设备。SDK将通过通用监听，上报已发现的设备以及相应的事件。APP可以先设置SDK的通用监听，再启动SDK，以便处理这些事件通知。

SDK启动时需要指定应用程序的AppID，开发者需要先在机智云网站上为自己的APP申请一个AppID，请在应用的Application或者第一个启动的Activity的onCreate中调用该方法指定应用的APPID。该方法只需要调用一次。

SDK的日志可以帮助开发者发现APP运行时发生的问题，SDK默认将所有日志信息输出到调试终端和日志文件中。如果手机有SD卡，则日志文件会保存在SD卡上，如果没有SD卡，就只保存在应用程序路径下。SD卡上的日志文件目录为手机SD卡路径下的app_package_name/GizWifiSDK/GizSDKLog。APP如果不希望在调试终端输出日志，可以通过日志级别设置接口，把日志输出级别修改为GizLogPrintNone。

【示例代码】

public void onCreate() {
super.onCreate();
GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().startWithAppID(getApplicationContext(), "your_app_id");
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didNotifyEvent(GizEventType eventType, Object eventSource, GizWifiErrorCode eventID, String eventMessage) {
if (eventType == GizEventType.GizEventSDK) {
// SDK的事件通知
Log.i("GizWifiSDK", "SDK event happened: " + eventID + ", " + eventMessage);
} else if (eventType == GizEventType.GizEventDevice) {
// 设备连接断开时可能产生的通知
GizWifiDevice mDevice = (GizWifiDevice)eventSource;
Log.i("GizWifiSDK", "device mac: " + mDevice.getMacAddress() + " disconnect caused by eventID: " + eventID + ", eventMessage: " + eventMessage);
} else if (eventType == GizEventType.GizEventM2MService) {
// M2M服务返回的异常通知
Log.i("GizWifiSDK", "M2M domain " + (String)eventSource + " exception happened, eventID: " + eventID + ", eventMessage: " + eventMessage);
} else if (eventType == GizEventType.GizEventToken) {
// token失效通知
Log.i("GizWifiSDK", "token " + (String)eventSource + " expired: " + eventMessage);
}
}
};
}

复制代码

boboP · 发表于 2016-8-8 11:37:18

3.2. 用户部分

机智云的用户系统包含了用户的注册、登录、重置密码、修改个人信息等功能，机智云以APPID区分用户系统，不同APPID的用户系统相互独立。更换APPID后，需要重新注册用户。以下流程中涉及到的**注册方法是用子类继承基类的方式实现的。

3.2.1. 用户部分主要流程图

用户的注册方式有多种，比如手机号、普通用户名、邮箱等，APP可以根据需要采取不同的方式。其他流程比如登录、密码修改、个人信息修改等部分，请直接阅读下面的流程文档。

3.2.2. 用户注册

机智云提供三种用户注册方式：手机注册、普通用户注册、邮箱注册。

3.2.2.1. 注册手机用户

通过手机注册账号，需要一个有效的手机号。注册时需要两步操作：获取短信验证码、用短信验证码注册用户。

第一步：APP获取短信验证码时，SDK向云端发送短信验证码请求，如果请求成功，云端会给手机发送短信验证码。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().requestSendPhoneSMSCode ("your_app_secret", "your_phone_number");
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didRequestSendPhoneSMSCode(GizWifiErrorCode result, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 请求成功
} else {
// 请求失败
}
}
}

复制代码

第二步：用短信验证码注册时，APP把手机收到的短信验证码传给SDK，填上手机号和密码就可以注册了。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().registerUser("your_phone_number", "your_password", "your_verify_code", GizUserAccountType.GizUserPhone);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didRegisterUser(GizWifiErrorCode result, String uid, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 注册成功
} else {
// 注册失败
}
}
}

复制代码

3.2.2.2. 注册普通用户

注册普通用户，使用用户名、密码即可创建一个账号。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().registerUser("your_user_name", "your_password", null, GizUserAccountType.GizUserNormal);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didRegisterUser(GizWifiErrorCode result, String uid, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 注册成功
} else {
// 注册失败
}
}
}

复制代码

3.2.2.3. 注册邮箱用户

通过有效的电子邮箱地址，注册一个账号。注册成功后，云端会给指定邮箱发送注册成功的邮件。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().registerUser("your_email_address", "your_password", null, GizUserAccountType.GizUserEmail);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didRegisterUser(GizWifiErrorCode result, String uid, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 注册成功
} else {
// 注册失败
}
}
}

复制代码

3.2.3. 用户登录

机智云提供三种用户登录方式：实名登录、匿名登录、第三方账号登录。实名登录适用于设计了登录界面，必须使用用户名密码注册登录以后才能使用的APP。匿名登录适用于没有设计登录界面，由后台自动生成用户账号的APP。登录后获取到的token有效期为7天。

3.2.3.1. 实名登录

实名用户登录时，用户名可以是注册过的手机号、邮箱、普通用户名。登录账号要先注册好，如果更换了AppID，登录账号需要重新注册。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().userLogin("your_user_name", "your_password");
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didUserLogin(GizWifiErrorCode result, String uid, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 登录成功
} else {
// 登录失败
}
}
}

复制代码

3.2.3.2. 匿名登录

用户每次匿名登录时，获取到的uid是相同的。Android SDK使用Android ID生成登录账号。每个Android系统都有一个独立的Android ID，系统刷机后将改变。因此，系统刷机后匿名登录的用户信息将无法保留。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().userLoginAnonymous();
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didUserLogin(GizWifiErrorCode result, String uid, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 登录成功
} else {
// 登录失败
}
}
}

复制代码

3.2.3.3. 第三方账号登录

目前支持的第三方账号有百度、新浪、腾讯。用户可以使用这三者的API获取到uid和token登录机智云，使用第三方账号登录时无需在机智云上注册，可直接登录。开发者可通过新浪、百度或腾讯api获取uid和token, 具体方法请参考各第三方平台的开发者文档。

【示例代码】

// 以新浪账号为例
GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().loginWithThirdAccount(GizThirdAccountType.GizThirdSINA, "your_third_uid", "your_third_token");
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didUserLogin(GizWifiErrorCode result, String uid, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 登录成功
} else {
// 登录失败
}
}
}

复制代码

3.2.4. 重置密码

如果忘记了用户密码，可以通过手机验证码或邮箱设置新的密码。SDK支持手机号重置密码和邮箱重置密码两种，手机号重置需要接收验证码，邮箱重置需要进⼊邮箱，根据链接提示进行重置。

3.2.4.1. 手机号重置密码

手机号重置密码时，需要先获取短信验证码再重置。获取短信验证码方式与手机注册时相同。

第一步：获取短信验证码

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().requestSendPhoneSMSCode("your_app_secret", "your_phone_number");
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didRequestSendPhoneSMSCode(GizWifiErrorCode result, String token) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 请求成功
} else {
// 请求失败
}
}
}

复制代码

第二步：用短信验证码重置密码

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().resetPassword("your_phone_number", "your_verify_code", "your_new_password", GizUserAccountType.GizUserPhone);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didChangeUserPassword(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 修改成功
} else {
// 修改失败
}
}
}

复制代码

3.2.4.2. 邮箱重置密码

邮箱重置密码时，云端会给指定邮箱发送安全链接。用户需要到邮箱中查收邮件，并按邮件指示执行重置操作。重置密码邮件有可能进入用户的邮箱的垃圾箱中，需提醒用户。

邮件发送成功回调与密码修改成功回调一致，因此需要注意在回调的时候区分。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().resetPassword("your_email_address", null, "your_new_password", GizUserAccountType.GizUserEmail);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didChangeUserPassword(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
//重置密码邮件发送成功，提示用户查收
} else {
//重置密码邮件发送失败，弹出错误信息
}
}
}

复制代码

3.2.5. 修改密码

用户登录后可以修改密码。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().changeUserPassword("your_token", "your_old_password", "your_new_password");
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didChangeUserPassword(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 修改成功
} else {
// 修改失败
}
}
}

复制代码

3.2.6. 匿名用户转换

匿名注册的用户可以转换为普通用户或者手机用户，转换后匿名用户的信息会转移到实名用户下，原匿名账号失效。但普通用户和手机用户必须是还未注册过的，已注册的用户名是无法转换的。

3.2.6.1. 匿名用户转普通用户

转普通用户时，填入待转换的用户名、密码，以及登录的token就可以了。

【示例代码】

// 匿名转手机用户
GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().transAnonymousUser("your_token", "your_user_name", "your_password", null, GizUserAccountType.GizUserNormal);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didTransAnonymousUser(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 转换成功
} else {
// 转换失败
}
}
}

复制代码

3.2.6.2. 匿名用户转手机用户

转手机用户时，需要填入待转换的手机号、密码、短信验证码，登录的token。获取短信验证码的过程与手机注册时一样。

【示例代码】

// 匿名转手机用户
GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().transAnonymousUser("your_token", "your_phone_number", "your_password", "your_verify_code", GizUserAccountType. GizUserPhone);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didTransAnonymousUser(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 转换成功
} else {
// 转换失败
}
}
}

复制代码

3.2.7. 修改用户信息

实名用户不支持修改普通用户名，可以修改邮箱、手机号，可以补充个人信息。实名用户必须登录后才能修改这些信息，并且待修改的邮箱或手机号必须是已经注册过的。

实名用户修改邮箱或手机号成功后，可以使用修改后的邮箱或手机号登录。登录后获得的绑定设备列表与原实名用户一致。

修改邮箱或手机号时，可以同时补充个人信息。不想修改个人信息时，对应参数可以传null。同时修改个人信息时，如果邮箱或用户名修改成功而个人信息修改失败，回调会返回成功并在errorMessage中提示个人信息修改失败的原因。

3.2.7.1. 修改用户邮箱

只修改用户邮箱时，个人信息的参数传null，用户类型可以指定为邮箱用户。以下为修改用户邮箱的示例代码。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().changeUserInfo("your_token", "your_email_address", null, GizUserAccountType.GizUserEmail, null);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didChangeUserInfo(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 修改成功
} else {
// 修改失败
}
}
}

复制代码

3.2.7.2. 修改用户手机号

只修改用户手机号时，个人信息参数传null，用户类型可以指定为手机用户。修改手机号之前，需要先获取手机验证码。以下示例代码为修改用户手机号的代码，获取短信验证码的代码请参考手机号注册。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().changeUserInfo("your_token", "your_phone_number", "your_verify_code", GizUserAccountType.GizUserPhone, null);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didChangeUserInfo(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 修改成功
} else {
// 修改失败
}
}
}

复制代码

3.2.7.3. 修改用户个人信息

只修改用户个人信息时，手机号或邮箱参数传null，用户类型可以指定为普通用户。个人信息包含多项内容，通过GizUserInfo类指定。其中不想修改的信息填null，云端会保留上次修改过的值。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizUserInfo additionalInfo = new GizUserInfo();
additionalInfo.setName("nickname");
additionalInfo.setGender(GizUserGenderType.Male);
additionalInfo.setBirthday("1990-1-1");
additionalInfo.setAddress("Beijing");
additionalInfo.setRemark("home");
GizWifiSDK.sharedInstance().changeUserInfo("your_token", null, null, GizUserAccountType.GizUserNormal, additionalInfo);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didChangeUserInfo(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 修改成功
} else {
// 修改失败
}
}
}

复制代码

3.2.7.4. 同时修改邮箱和个人信息

修改邮箱同时修改个人信息时，用户类型需指定为邮箱用户。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizUserInfo additionalInfo = new GizUserInfo();
additionalInfo.setName("nickname");
additionalInfo.setGender(GizUserGenderType.Male);
additionalInfo.setBirthday("1990-1-1");
additionalInfo.setAddress("Beijing");
additionalInfo.setRemark("home");
GizWifiSDK.sharedInstance().changeUserInfo("your_token", "your_email_address", null, GizUserAccountType.GizUserEmail, additionalInfo);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didChangeUserInfo(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 修改成功
} else {
// 修改失败
}
}
}

复制代码

3.2.7.5. 同时修改手机号和个人信息

修改手机号同时修改个人信息时，用户类型需指定为手机用户。修改手机号同样需要先获取手机验证码，获取短信验证码的代码请参考手机号注册。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizUserInfo additionalInfo = new GizUserInfo();
additionalInfo.setName("nickname");
additionalInfo.setGender(GizUserGenderType.Male);
additionalInfo.setBirthday("1990-1-1");
additionalInfo.setAddress("Beijing");
additionalInfo.setRemark("home");
GizWifiSDK.sharedInstance().changeUserInfo("your_token", "your_phone_number", "your_verify_code", GizUserAccountType.GizUserPhone, additionalInfo);
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didChangeUserInfo(GizWifiErrorCode result) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 修改成功
} else {
// 修改失败
}
}
}

复制代码

boboP · 发表于 2016-8-8 11:40:26

3.3. 配置设备入网部分

控制设备前，需要先让设备连到路由器上。连上路由器的设备，如果路由器能接入外网，设备会自动注册到机智云。

有两种配置方式能够让设备连到路由器上，一种是Airlink方式，一种是Softap方式，APP可以根据产品需求采取相应的配置方式。在开始配置前，设备要先进入配置模式，然后APP调用配置接口发送要配置的路由器ssid和密码。设备配置成功后，SDK给APP返回已配置成功的设备mac地址和产品类型标识，便于APP做下一步的操作。如果设备是重置后进入的配置模式，如果配置成功时设备还来不及从云端获取到DID，则APP得到的DID为空。

SDK的设备配置接口如果超时时间还未结束，无法进行下一次配置。此外，因为设备配置成功的广播包只有APP连到同一路由上才能收取，因此这个超时时间应该预留出APP连接路由器的时间。

需要注意的是，如果配置上线的设备不是APP要获取的产品类型，该设备就不会出现在设备列表中。

3.3.1. 设备配置流程图

3.3.2. AirLink配置

AirLink使⽤UDP广播方式，由手机端发出含有目标路由器名称和密码的广播，设备上的Wifi模块接收到广播包后自动连接目标路由器，连上路由器后发出配置成功广播，通知手机配置已完成。模块开启AirLink模式后，如果一分钟内未收到AirLink广播或无法正确连上路由器，将进入SoftAP模式。

【示例代码】

// 让手机连上目标Wifi
// MCU发出开启AirLink串口指令，通知模组开启AirLink模式。详情请参考《智能云空调-机智云接入串口通信协议文档》
//配置设备入网，发送要配置的wifi名称、密码
GizWifiSDK.sharedInstance().setListener(mListener);
List<GizWifiGAgentType> types = new ArrayList<GizWifiGAgentType> ();
types.add(GizWifiGAgentType.GizGAgentESP); GizWifiSDK.sharedInstance().setDeviceOnboarding("your_ssid", "your_key", GizWifiConfigureMode.GizWifiAirLink, null, 60, types);
GizWifiSDKListener mListener = new GizWifiSDKListener() {
//等待配置完成或超时，回调配置完成接口
@Override
public void didSetDeviceOnboarding (GizWifiErrorCode result, String mac, String did, String productKey) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 配置成功
} else {
// 配置失败
}
}
};

复制代码

3.3.3. SoftAP配置

设备进入SoftAP模式后，会产生一个Wifi热点。手机连上此热点后，将要配置的SSID和密码发给设备。设备上的Wi-Fi模块接收到SoftAP配置包后自动连接目标路由器，与airlink一样，连上路由器后发出配置成功广播，通知手机配置已完成。

使用机智云提供的模组固件，设备产生的Wifi热点以“XPG-GAgent-”开头，密码为” 123456789”。其他厂商提供的模组，SoftAP热点名称由各自厂商指定。APP可以根据需要传入正确的热点前缀。

【示例代码】

// MCU发出进入SoftAP串口指令，通知模组开启SoftAP模式。详情请参考《智能云空调-机智云接入串口通信协议文档》
//让手机连接模组的SoftAP热点
//配置设备入网，发送要配置的wifi名称、密码
GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().setDeviceOnboarding("your_ssid", "your_key", GizWifiConfigureMode.GizWifiSoftAP, "your_gagent_hotspot_prefix", 60, null);
//模块收到配置信息，尝试连接路由器并自动关闭热点
//让手机连接到配置的wifi上
GizWifiSDKListener mListener = new GizWifiSDKListener() {
//等待配置完成或超时，回调配置完成接口
@Override
public void didSetDeviceOnboarding (GizWifiErrorCode result, String mac, String did, String productKey) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 配置成功
} else {
// 配置失败
}
}
};

复制代码

boboP · 发表于 2016-8-8 11:43:54

3.4. 设备发现和订阅部分
3.4.1. 设备发现和订阅流程图

3.4.2. 设备发现

APP设置好监听，启动SDK后，就可以收到SDK的设备列表推送。每次局域网设备或者用户绑定设备发生变化时，SDK都会主动上报最新的设备列表。设备断电再上电、有新设备上线等都会触发设备列表发生变化。用户登录后，SDK会主动把用户已绑定的设备列表上报给APP，绑定设备在不同的手机上登录帐号都可获取到。

如果APP想要刷新绑定设备列表，可以调用绑定设备列表接口，同时可以指定自己关心的产品类型标识，SDK会把筛选后的设备列表返回给APP。

SDK提供设备列表缓存，设备列表中的设备对象在整个APP生命周期中一直有效。缓存的设备列表会与当前最新的已发现设备同步更新。

【示例代码】

// 使用缓存的设备列表刷新UI
List<GizWifiDevice> devices = GizWifiSDK.sharedInstance().getDeviceList();
// 接收设备列表变化上报，刷新UI
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didDiscovered(GizWifiErrorCode result, List<GizWifiDevice> deviceList) {
// 提示错误原因
if(result != GizWifiErrorCode.GIZ_SDK_SUCCESS) {
Log.d("", "result: " + result.name());
}
// 显示变化后的设备列表
Log.d("", "discovered deviceList: " + deviceList);
devices = deviceList;
}
};
// 主动刷新绑定设备列表、指定筛选的设备productKey
List<String> pks = new ArrayList<String> ();
pks.add("your_productKey");
GizWifiSDK.sharedInstance().getBoundDevices("your_uid", "your_token", pks);

复制代码

3.4.3. 设置设备的**

在设备列表中得到设备对象，为其设置设备**，以便于刷新设备UI。APP根据自己的需要实现相应的回调。

3.4.4. 设备订阅和绑定

APP得到设备列表后，给设备设置监听后，可以订阅设备。已订阅的设备将被自动绑定和自动登录，设备登录成功后会主动上报最新状态。

自动绑定仅限于局域网设备。对于无法在局域网内发现的设备，APP可以通过手动绑定的方式完成绑定。绑定成功的设备，需要订阅后才能使用。

无论是手动绑定还是自动绑定，设备的remark和alias信息，都需要在设备绑定成功后再设置。解除订阅的设备，连接会被断开，不能再继续下发控制指令了。

3.4.4.1. 设备订阅

所有通过SDK得到的设备，都可以订阅，订阅结果通过回调返回。订阅成功的设备，要在其网络状态变为可控时才能查询状态和下发控制指令。

【示例代码】

// 以设备列表中的第一个设备实例为例，为其设置监听
GizWifiDevice mDevice = null;
for (int i = 0; i < deviceList.size(); i++) {
mDevice = deviceList[0];
mDevice.setListener(mListener);
mDevice.setSubscribe(true);
break;
}
GizWifiDeviceListener mListener = new GizWifiDeviceListener() {
@Override
public void didSetSubscribe(GizWifiErrorCode result, GizWifiDevice device, boolean isSubscribed) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 订阅或解除订阅成功
} else {
// 失败
}
}
};

复制代码

3.4.4.2. 非局域网设备绑定

APP可以通过设备的mac、productKey、productSecret完成非局域网设备的绑定,可以用上述信息生成二维码，APP通过扫码方式绑定。GPRS设备、蓝牙设备等都是无法通过Wifi局域网发现的设备，都属于非局域网设备。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().bindRemoteDevice ("your_uid", "your_token", "your_device_mac", "your_device_product_key", "your_product_secret");
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didBindDevice(GizWifiErrorCode result, String did) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 绑定成功
} else {
// 绑定失败
}
}
};

复制代码

3.4.4.3. 设置设备的绑定信息

不订阅设备也可以设置设备的绑定信息。在设备列表中找到要修改的设备，如果是已绑定的，可以修改remark和alias信息。

【示例代码】

// mDevice是从设备列表中获取到的设备实体对象，设置监听
mDevice.setCustomInfo("your_remark", "your_alias");
// 实现回调
GizWifiDeviceListener mListener = new GizWifiDeviceListener() {
@Override
public void didSetCustomInfo(GizWifiErrorCode result, GizWifiDevice device) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 修改成功
} else {
// 修改失败
}
}
};

复制代码

3.4.5. 设备解绑

已绑定的设备可以解绑，解绑需要APP调用接口完成操作，SDK不支持自动解绑。对于已订阅的设备，解绑成功时会被解除订阅，同时断开设备连接，设备状态也不会再主动上报了。设备解绑后，APP刷新绑定设备列表时就得不到该设备了。

【示例代码】

GizWifiSDK.sharedInstance().setListener(mListener);
GizWifiSDK.sharedInstance().unbindDevice("your_uid", "your_token", "your_device_did");
// 实现回调
GizWifiSDKListener mListener = new GizWifiSDKListener() {
@Override
public void didUnbindDevice(GizWifiErrorCode result, String did) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 解绑成功
} else {
// 解绑失败
}
}
};

复制代码

3.4.6. 获取设备硬件信息

不订阅设备也可以获取到硬件信息。APP可以获取模块协议版本号，mcu固件版本号等硬件信息，但是只能在小循环下才能获取。

【示例代码】

// mDevice是从设备列表中获取到的设备实体对象，设置监听
mDevice.setListener(mListener);
mDevice.getHardwareInfo();
// 实现回调
GizWifiDeviceListener mListener = new GizWifiDeviceListener() {
@Override
public void didGetHardwareInfo(GizWifiErrorCode result, GizWifiDevice device, ConcurrentHashMap<String, String> hardwareInfo) {
StringBuilder sb = new StringBuilder();
if(result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
sb.append("Wifi Hardware Version:" + hardwareInfo.get("wifiHardVersion")
+ "\r\n");
sb.append("Wifi Software Version:" + hardwareInfo.get("wifiSoftVersion")
+ "\r\n");
sb.append("MCU Hardware Version:" + hardwareInfo.get("mcuHardVersion")
+ "\r\n");
sb.append("MCU Software Version:" + hardwareInfo.get("mcuSoftVersion")
+ "\r\n");
sb.append("Firmware Id:" + hardwareInfo.get("wifiFirmwareId") + "\r\n");
sb.append("Firmware Version:" + hardwareInfo.get("wifiFirmwareVer")
+ "\r\n");
sb.append("Product Key:" + hardwareInfo.get("productKey") + "\r\n");
sb.append("Device ID:" + device.getDid() + "\r\n");
sb.append("Device IP:" + device.getIPAddress() + "\r\n");
sb.append("Device MAC:" + device.getMacAddress() + "\r\n");
}else{
sb.append("获取失败，错误号：" + result);
}
Message msg = new Message();
msg.what = HARDWARE;
msg.obj = sb.toString();
handler.sendMessage(msg);
}
};

复制代码

boboP · 发表于 2016-8-8 11:46:54

3.5. 设备控制部分

SDK通过字典键值对方式进行设备控制和状态接收。SDK接收到APP下发的指令字典后，对应解析为设备可识别的数据，发送给设备。反之，SDK收到设备回复或上报的数据后，对应解析为字典键值对上报给APP。

智能设备需正确烧写了GAgent固件和机智云串口通讯协议。如果设备定义了数据点，APP发送的指令必须符合数据点定义。如果设备没有定义数据点，设备指令可以按照透传数据以自定义格式下发。

3.5.1. 设备控制流程图

3.5.2. 发送控制指令

设备订阅变成可控状态后，APP可以发送操作指令。操作指令是字典格式，键值对为数据点名称和值。操作指令的确认回复，通过didReceiveData回调返回。

APP下发操作指令时可以指定sn，通过回调参数中的sn能够对应到下发指令是否发送成功了。但回调参数dataMap有可能是空字典，这取决于设备回复时是否携带当前数据点的状态。

如果APP下发指令后只关心是否有设备状态上报，那么下发指令的sn可填0，这时回调参数sn也为0。

【示例代码】

/*
* 以下代码为App使用sn的示例。如果App不使用sn，sn可设为0，回调中也不需要判断sn
*/
// mDevice是从设备列表中获取到的设备实体对象，设置监听
mDevice.setListener(mListener);
// 订阅设备并变为可控状态后，执行开灯动作
int sn = 5; // 如果App不使用sn，此处可写成 int sn = 0;
ConcurrentHashMap<String, Object> command = new ConcurrentHashMap<String, Object> ();
command.put("LED_OnOff", true);
mDevice.write(command, sn);
// 实现回调
GizWifiDeviceListener mListener = new GizWifiDeviceListener() {
@Override
public void didReceiveData(GizWifiErrorCode result, GizWifiDevice device, ConcurrentHashMap<String, Object> dataMap, int sn) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 如果App不使用sn，此处不需要判断sn
if (sn == 5) {
// 命令序号相符，开灯指令执行成功
} else {
// 其他命令的ack或者数据上报
}
} else {
// 操作失败
}
}
};

复制代码

3.5.3. 接收设备状态

设备订阅变成可控状态后，APP可以随时收到设备状态的主动上报，仍然通过didReceiveData回调返回。设备上报状态时，回调参数sn为0，回调参数dataMap为设备上报的状态。

【示例代码】

GizWifiDeviceListener mListener = new GizWifiDeviceListener() {
@Override
public void didReceiveData(GizWifiErrorCode result, GizWifiDevice device, ConcurrentHashMap<String, Object> dataMap, int sn) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 已定义的设备数据点，有布尔、数值和枚举型数据
if (dataMap.get("data") != null) {
ConcurrentHashMap<String, Object> map = (ConcurrentHashMap<String, Object>) dataMap.get("data");
// 普通数据点，打印对应的key和value
StringBuilder sb = new StringBuilder();
for (String key : map.keySet()) {
sb.append(key + " :" + map.get(key) + "\r\n");
Toast.makeText(DeviceControlActivity.this,
sb.toString(), Toast.LENGTH_SHORT).show();
}
// 扩展数据点，key如果是“BBBB”
byte[] bytes = (byte[]) map.get("BBBB");
String string = Arrays.toString(bytes);
Toast.makeText(DeviceControlActivity.this,
string, Toast.LENGTH_SHORT).show();
}
// 已定义的设备故障数据点，设备发生故障后该字段有内容，没有发生故障则没内容
if (dataMap.get("faults") != null) {
ConcurrentHashMap<String, Object> map = (ConcurrentHashMap<String, Object>)dataMap.get("faults");
StringBuilder sb = new StringBuilder();
for (String key : map.keySet()) {
sb.append(key + " :" + map.get(key) + "\r\n");
Toast.makeText(DeviceControlActivity.this,
sb.toString(), Toast.LENGTH_SHORT).show();
}
}
// 已定义的设备报警数据点，设备发生报警后该字段有内容，没有发生报警则没内容
if (dataMap.get("alerts") != null) {
ConcurrentHashMap<String, Object> map = (ConcurrentHashMap<String, Object>)dataMap.get("alerts");
StringBuilder sb = new StringBuilder();
for (String key : map.keySet()) {
sb.append(key + " :" + map.get(key) + "\r\n");
Toast.makeText(DeviceControlActivity.this,
sb.toString(), Toast.LENGTH_SHORT).show();
}
}
// 透传数据，无数据点定义，适合开发者自行定义协议自行解析
if (dataMap.get("binary") != null) {
byte[] binary = (byte[]) dataMap.get("binary");
Log.i("", "Binary data:"
+ bytesToHex(binary, 0, binary.length));
}
}
}
};

复制代码

3.5.4. 设备状态查询

设备订阅变成可控状态后，APP可以查询设备状态。设备状态查询结果也通过didReceiveData回调返回，回调参数sn为0。回调参数dataMap为设备回复的状态。

【示例代码】

// mDevice是从设备列表中获取到的设备实体对象，设置监听
mDevice.setListener(mListener);
mDevice.getDeviceStatus();
// 实现回调
GizWifiDeviceListener mListener = new GizWifiDeviceListener() {
@Override
public void didReceiveData(GizWifiErrorCode result, GizWifiDevice device, ConcurrentHashMap<String, Object> dataMap, int sn) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 数据解析与3.5.3相同
} else {
// 查询失败
}
}
};

复制代码

boboP · 发表于 2016-8-8 11:47:38

新旧SDK兼容手册
1. 兼容目的

由于机智云品牌规范要求，新版SDK的类名前缀由XPG变更为Giz，因此APP需要相应修改类名前缀。

2. 兼容方法

把所有已废弃接口，替换成1.6.2 SDK的最新接口
把App工程中的SDK，更换成 2.00.00 SDK，如下图：

- 把类名中的XPG前缀改为Giz

以下表格列出了所有需要变更类名的接口：

【GizWifiSDK】

public void didSetDeviceWifi(int error, XPGWifiDevice device)

public void didSetDeviceWifi(int error, GizWifiDevice device)

public void didGetSSIDList(int error, List<XPGWifiSSID> ssidInfoList)

public void didGetSSIDList(int error, List<GizWifiSSID> ssidInfoList)

public void didDiscovered(int error, List<XPGWifiDevice> devicesList)

public void didDiscovered(int error, List<GizWifiDevice> devicesList)

【GizWifiDevice】

public void didQueryHardwareInfo(XPGWifiDevice device, int result, ConcurrentHashMap<String, String> hardwareInfo)

public void didQueryHardwareInfo(GizWifiDevice device, int result, ConcurrentHashMap<String, String> hardwareInfo)

public void didDeviceOnline(XPGWifiDevice device,boolean isOnline)

public void didDeviceOnline(GizWifiDevice device,boolean isOnline)

public void didLogin(XPGWifiDevice device, intresult)

public void didLogin(GizWifiDevice device, intresult)

public void didDisconnected(XPGWifiDevice device, int result)

public void didDisconnected(GizWifiDevice device, int result)

public void didReceiveData(XPGWifiDevice device, ConcurrentHashMap<String, Object> dataMap, intresult)

public void didReceiveData(GizWifiDevice device, ConcurrentHashMap<String, Object> dataMap, intresult)

【GizWifiCentralControlDevice】

public void didDiscovered(int error, List<XPGWifiSubDevice> subDeviceList)

public void didDiscovered(int error, List<GizWifiSubDevice> subDeviceList)

【GizWifiBinary】

XPGWifiBinary

GizWifiBinary

boboP · 发表于 2016-8-8 11:48:09

1. 新旧SDK兼容方式

SDK采取以下兼容方式：

兼容接口参数对应转换为新接口参数后，在兼容接口内调用新接口。
回调时同时回调兼容接口。之前使用1.6.2 SDK的APP，仍然可以收到兼容接口的回调。

新版SDK对1.6.2 SDK的未废弃接口做了无缝兼容。

2. 新旧SDK功能对比

下面对新旧SDK的功能做些对比说明：

下载配置文件功能

2.0 SDK会自动探测配置文件是否有更新，有更新时会主动推送给APP。APP只保留didUpdateProduct回调即可，不需要再使用updateDeviceFromServer这个兼容接口做强制更新了。

获取设备列表功能

2.0 SDK会主动发现当前局域网设备，用户登录、绑定或解绑后也会主动刷新已绑定设备，并推送给APP。APP只要实现didDiscovered回调即可得到最新的设备列表。2.0 SDK提供设备列表缓存，APP可以使用deviceList缓存刷新界面。

APP仍然可以使用getBoundDevices接口调用，但getBoundDevices接口需要访问外网获取绑定设备列表，回调刷新的快慢取决于网络请求时间。

设备绑定功能

对于局域网wifi设备，只要用户登录了，2.0 SDK就会自动绑定已订阅的设备；对于非局域网设备，APP需要调用绑定接口手动绑定。使用passcode绑定的兼容接口将被新的mac地址绑定接口取代。

用户注销功能

云端一直都不支持用户注销功能，2.0 SDK也仅对接口调用做兼容，并不实现真正的用户注销功能。 APP如果不想继续使用当前用户，可以切换用户登录。

设备passcode属性值

设备passcode仅在设备绑定时会被使用到。从安全角度考虑，2.0 SDK的新接口中，不推荐继续使用passcode绑定的兼容接口，并且也不再提供有效的passcode值。

设备登录功能

设备登录兼容接口，会触发设备订阅。2.0 SDK对已订阅设备会自动登录，只要不取消订阅，自动登录会一直尝试直到成功为止。APP只需要订阅设备，接收设备的netStatus变化上报即可。

2.0 SDK设备登录过程，包含设备连接、获取passcode、登录验证、获取设备状态四个步骤。其中有一个步骤失败，即登录失败。登录失败后，SDK会间隔1秒重试。

设备断开连接功能

设备断开连接兼容接口，会触发设备解除订阅。2.0 SDK对已解除订阅的设备，不再推送任何状态更新，同时会断开设备连接。

设备控制指令下发功能

旧的设备write接口，不带sn参数。SDK在兼容处理时，sn按0下发。新的write接口中，控制指令下发时可以指定sn，2.0 SDK就可以精确回调该条指令对应的应答。

2.0 SDK对于下发的设备指令，对以下数据类型做了约定，并且要求只能包含可写指令。不符合类型约定和要求的指令，被视为无效指令，下发指令格式支持字典键值对。

布尔类型	命令参数必须传true或false
枚举类型	命令参数只能传索引值或枚举字符串
数值类型	命令参数只能是数值
扩展类型	直接传二进制数据，不需要再做base64编码了
透传数据	直接传二进制数据，不需要再做base64编码了

设备状态上报功能

新的回调接口中会携带下发指令的sn。上报的数据点，以字典键值对的格式回调，数据点标识名和值组成键值对。

扩展类型和透传数据，回调的数据格式是二进制数据，不需要APP做base64转码。

3. 新旧SDK枚举定义对比

APP端替换新SDK时不需要替换枚举，以下仅列出新旧枚举的对应关系，APP端可以查阅。

【XPGConfigureMode】

兼容枚举	新定义枚举
XPGConfigureMode	GizWifiConfigureMode
1: XPGWifiSDKSoftAPMode	0: GizWifiSoftAP
2: XPGWifiSDKAirLinkMode	1: GizWifiAirLink

【XPGWifiDeviceType】

兼容枚举	新定义枚举
XPGWifiDeviceType	GizWifiDeviceType
0: XPGWifiDeviceTypeNormal	0: GizDeviceNormal
1: XPGWifiDeviceTypeCenterControl	1: GizDeviceCenterControl

【XPGWifiThirdAccountType】

兼容枚举	新定义枚举
XPGWifiThirdAccountType	GizThirdAccountType
0: XPGWifiThirdAccountTypeBAIDU	0: GizThirdBAIDU
1: XPGWifiThirdAccountTypeSINA	1: GizThirdSINA
2: XPGWifiThirdAccountTypeQQ	2: GizThirdQQ

【XPGUserAccountType】

兼容枚举	新定义枚举
XPGUserAccountType	GizUserAccountType
0: XPGUserAccountTypeNormal	0: GizUserNormal
1: XPGUserAccountTypePhone	1: GizUserPhone
2: XPGUserAccountTypeEmail	2: GizUserEmail

【XPGWifiGAgentType】

兼容枚举	新定义枚举
XPGWifiGAgentType	GizWifiGAgentType
0: XPGWifiGAgentTypeMXCHIP	0: GizGAgentMXCHIP
1: XPGWifiGAgentTypeHF	1: GizGAgentHF
2: XPGWifiGAgentTypeRTK	2: GizGAgentRTK
3: XPGWifiGAgentTypeWM	3: GizGAgentWM
4: XPGWifiGAgentTypeESP	4: GizGAgentESP
5: XPGWifiGAgentTypeQCA	5: GizGAgentQCA
6: XPGWifiGAgentTypeTI	6: GizGAgentTI
7: XPGWifiGAgentTypeFSK	7: GizGAgentFSK
8: XPGWifiGAgentTypeMXCHIP3	8: GizGAgentMXCHIP3
9: XPGWifiGAgentTypeBL	9: GizGAgentBL

【XPGUserGenderType】

兼容枚举	新定义枚举
XPGUserGenderType	GizUserGenderType
0: Male	0: GizUserGenderMale
1: Female	1: GizUserGenderFemale
2: Unknown	2: GizUserGenderUnknown

【XPGWifiErrorCode】

兼容枚举	新定义枚举
XPGWifiErrorCode	GizWifiErrorCode
0	XPGWifiError_NONE	0	GIZ_SDK_SUCCESS
-1	XPGWifiError_GENERAL	8100	GIZ_SDK_OTHERWISE
-7	XPGWifiError_CONNECTION_CLOSED	8047	GIZ_SDK_CONNECTION_CLOSED
-9	XPGWifiError_LOGIN_VERIFY_FAILED	8049	GIZ_SDK_DEVICE_LOGIN_VERIFY_FAILED
-11	XPGWifiError_NOT_CONNECTED	8029	GIZ_SDK_DEVICE_NOT_SUBSCRIBED
-15	XPGWifiError_THREAD_CREATE	8102	GIZ_SDK_THREAD_CREATE_FAILED
-19	XPGWifiError_CONNECTION_ERROR	8046	GIZ_SDK_CONNECTION_ERROR
-20	XPGWifiError_INVALID_PARAM	8006	GIZ_SDK_PARAM_INVALID
8033	GIZ_SDK_DEVICE_CONTROL_WITH_INVALID_COMMAND
8036	GIZ_SDK_DEVICE_CONTROL_VALUE_TYPE_ERROR
8037	GIZ_SDK_DEVICE_CONTROL_VALUE_OUT_OF_RANGE
8038	GIZ_SDK_DEVICE_CONTROL_NOT_WRITABLE_COMMAND
-21	XPGWifiError_CONNECT_TIMEOUT	8044	GIZ_SDK_CONNECTION_TIMEOUT
-23	XPGWifiError_INSUFFIENT_MEM	8101	GIZ_SDK_MEMORY_MALLOC_FAILED
-25	XPGWifiError_HTTP_FAIL	8099	GIZ_SDK_HTTP_REQUEST_FAILED
-27	XPGWifiError_DNS_FAILED	8041	GIZ_SDK_DNS_FAILED
-30	XPGWifiError_UDP_PORT_BIND_FAILED	8004	GIZ_SDK_UDP_PORT_BIND_FAILED
-39	XPGWifiError_CONFIGURE_SSID_NOT_MATCHED	8310	GIZ_SDK_PHONE_NOT_CONNECT_TO_SOFTAP_SSID
8311	GIZ_SDK_DEVICE_CONFIG_SSID_NOT_MATCHED
-40	XPGWifiError_CONFIGURE_TIMEOUT	8023	GIZ_SDK_DEVICE_CONFIG_TIMEOUT
8308	GIZ_SDK_REQUEST_TIMEOUT
-41	XPGWifiError_CONFIGURE_SENDFAILED	8021	GIZ_SDK_DEVICE_CONFIG_SEND_FAILED
-42	XPGWifiError_NOT_IN_SOFTAPMODE	8312	GIZ_SDK_NOT_IN_SOFTAPMODE
-45	XPGWifiError_CONNECTION_REFUSED	8045	GIZ_SDK_CONNECTION_REFUSED
-46	XPGWifiError_IS_RUNNING	8022	GIZ_SDK_DEVICE_CONFIG_IS_RUNNING
8315	GIZ_SDK_PRODUCT_IS_DOWNLOADING
-47	XPGWifiError_UNSUPPORTED_API	8307	GIZ_SDK_UNSUPPORTED_API
-49	XPGWifiError_START_SDK_FAILED	8002	GIZ_SDK_CLIENT_NOT_AUTHEN

旧的错误码在以上对照表中没有的，新SDK一律按新的错误码8100处理。

boboP · 发表于 2016-8-8 11:48:55

本帖最后由 boboP 于 2016-8-8 11:55 编辑

FAQ

1.扩展数据点透传收发：

1.1 定义数据点：

在机智云产品管理中的数据点中定义一个拓展类型的数据点，如图所示：定义数据长度为60个byte（透传情况下，数据长度暂时支持900字节内数据传输）

1.2 设备数据上报：

设备mcu按照数据点的定义格式上传即可，在完成新产品的定义后，每个新产品都有相应的串口通信协议文档，文档下载路径：机智云官网 –>硬件接入 ->设备列表-> 新产品 ->产品开发资源 ->《XXX-机智云接入串口通信协议文档》

在串口通信协议文档文档的4.9部分则有MCU上报数据的格式，如下图：

图中的dev_status(60B)即为需要透传的数据

1.3 APP回调接口说明

APP端接收到MCU上报数据的回调接口：didReceiveData，判断result为GizWifiErrorCode.GIZ_SDK_SUCCESS，则接收到的数据可能为普通数据点或者扩展数据点。

Andriod接收到MCU上报拓展数据类型代码示例：

final protected static char[] hexArray = "0123456789ABCDEF".toCharArray();
// 将16进制的byte转为string，比如byte值为{0x62,0x63}，那么将转为“6263”
public static String bytesToHex(byte[] bytes) {
char[] hexChars = new char[bytes.length * 3];
for (int j = 0; j < bytes.length; j++) {
int v = bytes[j] & 0xFF;
hexChars[j * 3] = hexArray[v >>> 4];
hexChars[j * 3 + 1] = hexArray[v & 0x0F];
hexChars[j * 3 + 2] = ' ';
}
return new String(hexChars);
}
@Override
protected void didReceiveData(GizWifiErrorCode result, GizWifiDevice device, ConcurrentHashMap<String, Object> dataMap, int sn) {
if (result == GizWifiErrorCode.GIZ_SDK_SUCCESS) {
// 普通数据点类型，有布尔型、整形和枚举型数据，该种类型一般为可读写
if (dataMap.get("data") != null) {
ConcurrentHashMap<String, Object> map = (ConcurrentHashMap<String, Object>) dataMap.get("data");
// 扩展数据点，key为"kuozhan"
byte[] bytes = (byte[]) map.get("kuozhan");
String string = bytesToHex(bytes);
Toast.makeText(this, string, Toast.LENGTH_SHORT).show(); }
}
}

复制代码

1.4 APP下发

APP在GizWifiDevice类的write接口中，按照数据点定义发送扩展数据。

Andriod下发拓展数据类型命令代码示例：

byte[] input1 = { 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77 };
// byte[] input2 = { 11, 22, 33, 44, 55, 66, 77, 88, 99};
ConcurrentHashMap<String, Object> dataMap = new ConcurrentHashMap<String, Object>();
dataMap.put("kuozhan", input1);
device.write(dataMap, 0);

复制代码

上述代码中，input1与input2的透传结果是不一样的，input1中定义的是十六进制的数值，input2中则是十进制的数值。如果使用input1中0x11的值下发给设备，那么设备将收到0x11的十六进制值，如果使用input2中11的值下发给设备，那么设备收到将是0x0b（十进制11对应十六进制b）。使用input1下发设备，MCU收到的数据为：

FF FF 00 43 03 45 00 00 01 01 11 22 33 44 55 66 77 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 69