Android （Native）配网开发实践
更新时间：2018-10-19 11:29:34
1. 概述
平台已提供了一套完整的配网页面，如果开发者希望自己使用native开发自己的定制化配网页面，可以阅读本文，使用配网SDK进行开发。
配网 SDK 提供了把 WiFi 设备配置上家庭路由器以及局域网内已联网设备的发现能力，具体方案包括一键广播配网（P2P）、手机热点配网、智能路由器配网以及设备间相互配网（以下简称零配）等。各配网方式简介请参考 配网方案介绍 文档。各独立接口介绍文档请参见 配网接口文档（api reference）。
2. 配网方式详细说明
2.1 一键配网
2.1.1 一键配网接入详细流程
1、发现设备
发现设备即获取待配设备的ProductKey和DeviceName。获取的设备信息主要包括设备的 ProductKey（可以理解为产品类型）、DeviceName（设备名称），可通过以下方式获取：
1）通过直接调用云端接口获取产品列表（非配网 SDK 提供接口），选择待配网设备对应的产品拿到 ProductKey；
2）通过扫描二维码获得待配设备信息，包含设备 ProductKey 和 DeviceName（可选）；
3）调用 SDK LocalDeviceMgr startDiscovery() 本地发现接口发现设备（一键配网情况下使用这种方式发现需要当前局域网有一个已配的设备，具体可参考 配网 SDK 发现 章节 ）。
2、开始配网
使用 1 中获取到的待配网设备信息构造 DeviceInfo 对象，设置使用的配网方式 linkType 的值，然后调用 SDK setDeviceInfo 设置待配网设备信息。
调用 SDK startAddDevice 配网方法，开始配网。需要注意的是：设备有可能需要触发让它进入配网模式，请根据提示操作。
3、配网中
收到 provisionPrepare 回调后，调用 SDK toggleProvision 方法传入当前连接路由器的 ssid 和 password。
4、配网结果
监听配网的最终结果回调。
可以在配网完成之后调用 LocalDeviceMgr getDeviceToken 接口获取绑定 token，完成绑定操作。
2.1.2 示例代码
/**
* 第一步 发现设备
*/
String productKey = "xxx";//TODO 用户根据实际情况设置
String deviceName = "xxx";//TODO 用户根据实际情况设置，可为空。
/**
* 第二步 开始配网
* 设置待配信息 开始配网
*/
DeviceInfo info = new DeviceInfo();
info.productKey = productKey;
info.deviceName = deviceName;
info.linkType = LinkType.ALI_BROADCAST.getName();
AddDeviceBiz.getInstance().setDevice(info);
AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener() {
@Override
public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) {
}
@Override
public void onProvisionPrepare() {
/**
* 第三步 配网中 传入WiFi 信息
*/
AddDeviceBiz.getInstance().toggleProvision(mSsid, mPwd, 60);
}
@Override
public void onProvisioning() {} // 配网中
@Override
public void onProvisionStatus(ProvisionStatus provisionStatus) {} //Deprecated
@Override
public void onProvisionedResult(boolean isSuccess, DeviceInfo info, DCErrorCode dcErrorCode) {
/**
* 第四步 监听结果回调
*/
});
2.1.3 异常处理
在收到 onProvisionedResult 并且配网失败的时候可按照错误信息做进一步的处理。
1）如果收到 codeName="NETWORK_ERROR"&subcode=60101 错误信息，则表示当前手机连接的是 5G WiFi，可以提示用户切换到 2.4G WiFi；
2） 如果收到 codeName="NETWORK_ERROR"&subcode= 60102错误信息，则表示当前手机未连接 WiFi，可提示用户连接 WiFi。
2.2 热点配网
2.2.1 热点配网详细流程
1、发现设备（可选）
发现设备即获取待配设备的ProductKey和DeviceName。获取的设备信息主要包括设备的 ProductKey（可以理解为产品类型）、DeviceName（设备名称），可通过以下方式获取：
1）通过直接调用云端接口获取产品列表（非配网 SDK 提供接口），选择待配网设备对应的产品拿到 ProductKey；
2）通过扫描二维码获得待配设备信息，包含设备 ProductKey 和 DeviceName（可选）；
3）调用 SDK LocalDeviceMgr startDiscovery() 本地发现接口发现设备（热点配网情况下使用这种方式发现需要当前局域网有一个已配的设备，具体可参考 配网 SDK 发现 章节 ）。
2、开始配网
2.1、手机开启热点
调用 HotspotHelper setupWifiAP 接口开启热点接口开启指定热点，根据回调结果进行下一步的流程。
如果返回失败，提示和用户手动开启 aha 热点，开启成功之后进入第二步；
如果返回成功，则进行第二步；
2.2、发现连上热点的设备
调用接口发现连上热点的设备，根据设备信息匹配发现的设备是否即是需要配网的设备，如果是则进入下一步。一般手机在通知栏会提示有设备连接上热点。需要注意的是：设备有可能需要触发让它进入配网模式，请根据提示操作。
2.3、设置 WiFi 连接信息
调用 SDK 接口发送WiFi 连接信息到 2 中选择的设备。接口参数可以直接透传 2 中获得的设备信息对象。
2.4、恢复网络连接
调用SDK接口关闭热点，并恢复网络连接。如果恢复网络连接默认连接的不是之前连接的热点，需要提示用户手动切换到之前连接的热点。
2.5、设置待配网设备信息
使用 2 获取的设备信息，构造 DeviceInfo 对象，并设置配网方式 linkType 为热点配网，然后调用 SDK setDeviceInfo 设置待配网设备信息。
调用 SDK startAddDevice 配网方法，开始配网。3、配网中
配网中间状态回调。
4、配网结果
监听配网结果。
可以在配网完成之后调用 LocalDeviceMgr getDeviceToken 接口获取绑定 token，完成绑定操作。
2.2.2 示例代码
/**
* 第一步 发现设备
*/
String productKey = "xxx";//TODO 用户根据实际情况设置
String deviceName = "xxx";//TODO 用户根据实际情况设置，可为空。
/**
* 第二步 开始配网
* 前置步骤 设置待配信息 开始配网
*/
// 2.1 开启热点
HotspotHelper.getInstance().setupWifiAP(context, new HotspotHelper.ISetupWifiAPListener() {
@Override
public void onEnable() {
// 热点开启成功
}
@Override
public void onFail() {
//TODO 热点开启失败，提示用户手动开启 aha 热点，密码 12345678，之后进行下一步操作。
}
});
// 2.2 发现连接到热点的设备 （开启热点成功之后调用）
private LocalDevice foundDevice = null;
HotspotHelper.getInstance().discoveryDevices(new HotspotHelper.IPAPDiscoveryListener() {
@Override
public void onFound(final LocalDevice device) {
// 每发现一个设备返回一个
if(device != null && device.productKey.equals(productKey)){ // TODO 根据需要配置的设备做匹配
foundDevice = device; //发现了需要配网的设备
}
}
});
// 2.3 发送 ssid 和 password （发现需要配网的设备之后调用）
String ssid = "xxx"; //TODO 开启热点之前的ssid，可以开启热点之前获取并保留
String password = "xxx"; //TODO 由用户输入
DeviceInfo toProvisionDeviceInfo = null;
HotspotHelper.getInstance().switchAP(foundDevice, ssid,
mPassword, new HotspotHelper.ISwitchApResultListenr() {
@Override
public void onSucc(final DeviceInfo deviceInfo) {
toProvisionDeviceInfo = deviceInfo;
// 2.4 恢复网络连接
HotspotHelper.getInstance().recoverWiFiConnect(this);
// 2.5 设置待配设备信息 开始监听配网结果
startConfig(toProvisionDeviceInfo);
}
@Override
public void onFail(String msg) {
// 切换失败 可根据错误信息判断是否
}
});
public void startConfig(DeviceInfo toProvisionDeviceInfo){
DeviceInfo info = toProvisionDeviceInfo;
info.linkType = LinkType.ALI_PHONE_AP.getName();
AddDeviceBiz.getInstance().setDevice(info);
AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener() {
@Override
public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) {}
@Override
public void onProvisionPrepare() {}
@Override
public void onProvisioning() {
/**
* 第三步 配网中
* 根据实际场景处理
*/
}
@Override
public void onProvisionStatus(ProvisionStatus provisionStatus) {}
@Override
public void onProvisionedResult(boolean isSuccess, DeviceInfo info, DCErrorCode dcErrorCode) {
// TODO 配网成功或失败的处理操作
/**
* 第四步 配网结果
* 根据实际场景处理
*/
}
});
}
2.2.3 异常处理
针对以下场景 APP 可以做部分兼容操作：
1）热点返回开启失败的时候提示用户开启指定热点，建议使用文字描述如何开启热点；成功则不需要做任何操作；
2）发现连接到热点的设备没有超时，如果不需要用户干预选择某一设备进行配网，可以做个超时；
3）如果收到 onProvisionedResult codeName="NETWORK_ERROR"&subcode= 60103错误信息，则表示当前手机未开启手机流量，可提示用户开启手机流量或者添加有效 SIM 卡或者切换另外一种配网方式；
4）recoverWiFiConnect 恢复 WiFi 连接有可能会出现连接的 WiFi 不是配网的 WiFi，这个时候可以手动切换到指定的 WiFi。
2.3 零配
2.3.1 零配详细流程
1、发现设备
调用配网SDK LocalDeviceMgr startDiscovery() 接口获取已配网设备和待配网设备，此时使用的是其中的待配网设备（已配设备和待配设备是通过不同接口返回的）
2、开始配网
使用 1 中获取到设备信息（DeviceInfo 对象），调用方法设置待配网设备。无需设置配网方式，直接透传发现到的设备信息对象（DeviceInfo 对象），SDK自动匹配使用哪种配网方式，当然也可以强制指定使用其他配网方式。
调用开始配网接口，设置监听回调。
3、配网中
配网中间状态回调。
4、配网结果
监听配网结果。
可以在配网完成之后调用 LocalDeviceMgr getDeviceToken 接口获取绑定 token，完成绑定操作。
2.3.2 示例代码
/**
* 第一步 发现设备
*/
DeviceInfo toProvisionDeviceInfo = null;
LocalDeviceMgr.getInstance().startDiscovery(context, new IDiscoveryListener() {
@Override
public void onLocalDeviceFound(DeviceInfo deviceInfo) {
// 发现到的已配网设备 发现一个返回一个 可用来做绑定操作
}
@Override
public void onEnrolleeDeviceFound(List<DeviceInfo> devices) {
// 发现到的待配网设备 可能多次返回
if(true){//TODO 用户根据需要配置的设备做匹配或者将设备全部露出，让用户点击选择
toProvisionDeviceInfo = devices.get(i);
}
}
});
/**
* 第二步 开始配网
* 使用前面选择的待配设备的信息透传到设置设备信息接口并开始配网
*/
AddDeviceBiz.getInstance().setDevice(toProvisionDeviceInfo);
AddDeviceBiz.getInstance().startAddDevice(getApplicationContext(), new IAddDeviceListener() {
@Override
public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) { }
@Override
public void onProvisionPrepare() {}
@Override
public void onProvisioning() {
/**
* 第三步 配网中
* 根据实际场景处理
*/
}
@Override
public void onProvisionStatus(ProvisionStatus provisionStatus) {}
@Override
public void onProvisionedResult(boolean isSuccess, DeviceInfo info, DCErrorCode dcErrorCode) {
// TODO 配网成功或失败的处理操作
/**
* 第四步 配网结果
* 根据实际场景处理
*/
});
2.2.3 异常处理
针对以下场景 APP 可以做部分兼容操作：
1）配网失败的时候可以考虑切换到其他配网方式，调用 AddDeviceBiz.getInstance().setAliProvisionMode("xxx") 接口，替换 xxx 为具体的配网方式，如 "ForceAliLinkTypeBroadcast" 使用一键广播。
2）可以根据配网结果中的错误码做对应的处理操作。
2.4 路由器配网
2.4.1 智能路由器配网详细流程
1、发现设备
调用配网SDK LocalDeviceMgr startDiscovery() 接口获取已配网设备和待配网设备，此时使用的是其中的待配网设备（已配设备和待配设备是通过不同接口返回的）
2、开始配网
使用 1 中获取到设备信息（DeviceInfo 对象），调用方法设置待配网设备。无需设置配网方式，直接透传发现到的设备信息对象（DeviceInfo 对象），SDK自动匹配使用哪种配网方式，当然也可以强制指定使用其他配网方式。
调用开始配网接口，设置监听回调。
3、配网中
配网中间状态回调。
4、配网结果
监听配网结果。
可以在配网完成之后调用 LocalDeviceMgr getDeviceToken 接口获取绑定 token，完成绑定操作。
2.4.2 示例代码
/**
* 第一步 发现本地设备
*/
DeviceInfo toProvisionDeviceInfo = null;
LocalDeviceMgr.getInstance().startDiscovery(context, new IDiscoveryListener() {
@Override
public void onLocalDeviceFound(DeviceInfo deviceInfo) {
// 发现到的已配网设备 发现一个返回一个 可用来做绑定操作
}
@Override
public void onEnrolleeDeviceFound(List<DeviceInfo> devices) {
// 发现到的待配网设备 可能多次返回
if(true){//TODO 用户根据需要配置的设备做匹配或者将设备全部露出，让用户点击选择
toProvisionDeviceInfo = devices.get(i);
}
}
});
/**
* 第二步 开始配网
* 使用前面选择的待配设备的信息透传到设置设备信息接口并开始配网
*/
AddDeviceBiz.getInstance().setDevice(toProvisionDeviceInfo);
AddDeviceBiz.getInstance().startAddDevice(getApplicationContext(), new IAddDeviceListener() {
@Override
public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) { }
@Override
public void onProvisionPrepare() {}
@Override
public void onProvisioning() {
/**
* 第三步 配网中
* 根据实际场景处理
*/
}
@Override
public void onProvisionStatus(ProvisionStatus provisionStatus) {}
@Override
public void onProvisionedResult(boolean isSuccess, DeviceInfo info, DCErrorCode dcErrorCode) {
// TODO 配网成功或失败的处理操作
/**
* 第四步 配网结果
* 根据实际场景处理
*/
});
2.2.3 异常处理
针对以下场景 APP 可以做部分兼容操作：
1）配网失败的时候可以考虑切换到其他配网方式，调用 AddDeviceBiz.getInstance().setAliProvisionMode("xxx") 接口，替换 xxx 为具体的配网方式，如 "ForceAliLinkTypeBroadcast" 使用一键广播；
2）可以根据配网结果中的错误码做对应的处理操作。
3.设备绑定
这里主要介绍本 SDK 提供的获取绑定 token 的接口。绑定接口非本 SDK 提供。
3.1 简介
设备配网成功之后，要想控制设备，需要先将设备绑定到用户的账号下面。用户可以通过调用本地发现接口，通过 DeviceInfo 对象拿到绑定需要的 token，或者用户主动调用 SDK 的 getDeviceToken 获取绑定需要使用的token。拿到 token 之后就可以调用绑定接口绑定设备。
注：绑定接口非本 SDK 提供。
3.2 绑定详细流程
3.2.1 获取绑定 token
可通过以下方式拿到绑定使用的 token：
1）调用本地发现接口，返回的已配设备列表设备信息中包含 token；
2）主动调用 SDK 接口获取 token；
这里主要介绍第二种方式，第一种方式可以参考零配或者路由器配网的本地发现接口调用示例。
3.2.2 绑定
使用设备的 ProductKey、DeviceName、Token 调用绑定接口进行绑定。
3.3 示例代码
/**
* 第一步 获取绑定 token
*/
LocalDeviceMgr.getInstance().getDeviceToken(productKey, deviceName, 60*1000, new IOnDeviceTokenGetListener() {
@Override
public void onSuccess(String token) {
// 拿到绑定需要的token
/**
* 第二步 调用绑定接口
*/
//TODO 用户根据具体业务场景调用
}
@Override
public void onFail(String reason) {
}
});
3.4 异常处理
针对以下场景 APP 可以做部分兼容操作：
1）使用本地发现的设备信息进行绑定的时候，如果出现超时（比如获取 token 之后过了很久才去绑定），可以主动调用 getDeviceToken 接口更新绑定 token，然后重新调用绑定接口；
2）绑定 token 有一定的有效时限，失败的时候可以主动重试。