配网SDK接口参考

概述

配网SDK主要流程图:

graph TD A[sdkInit] --> B(deviceProbe) A[sdkInit] --> C(deviceEasyConfig) C --> D{配网结果} D --> |lanaddr| B B --> E{搜索设备} E --> |未发现新设备|B E --> |newconfig==true|F(devicePair) F --> |devicePairedInfo|G(deviceControl) F --> |devicePairedInfo|H(云端存储)

注意:

1.  调用 deviceEasyConfig 的同时,可以循环调用 deviceProbe 获取扫描局域网设备,如果 deviceProbe 返回的设备信息里面包含 newconfig 字段为 true,则认为该设备为新配置设备。
2.  deviceEasyConfig 配置失败,返回 -4000,而设备闪烁的灯在慢闪或者熄灭,设备也已经配置成功,需要继续循环调用 deviceProbe 获取扫描局域网设备, 返回的设备信息里面包含 newconfig 字段为 true,也认为该设备为新配置设备。
3.  调用 deviceProbe 接口从局域网获取到设备基本信息 deviceInfo ,然后再调用 devicePair 接口,获取设备详细信息 devicePairedInfo
4.  需要把 devicePairedInfo 保存到开发者自身的云端数据库,后续通过云云对接时,都是使用这个设备信息
5.  如果设备重置,重新配网之后,上述保存的 devicePairedInfo 必须删除,重新进行 deviceProbe 和 devicePair 操作才行

1.1 对象定义

deviceInfo
{
     "did":"",      //设备的唯一ID
     "pid":"",      //设备产品类型ID
     "mac":"",      //设备MAC地址
     "name":"",     //设备名称
     "lanaddr":"",  //设备局域网IP地址
     "extend":""    //设备扩展信息
}


devicePairedInfo
{
     "did":"",      //设备的唯一ID
     "pid":"",      //设备产品类型ID
     "mac":"",      //设备MAC地址
     "cookie":""    //设备Pair获取Cookie
}

1.2 准备工作

获取 kit 模块

如果你还没有 BroadLink DNA kit 模块,请联系我们咨询如何获取模块。

建立产品测试与发布

如果你还没有建立一个产品,请登录我们的开发者平台注册账号,进行产品的建立,测试与发布。

申请 License

为了设备的安全,所有使用 SDK 的用户必须向 BroadLink Co., Ltd. 申请 LicenseLicense 与应用的包名(packageName)相关联,不同的应用包名需要申请不同的 License

  1. 进入 BroadLink DNA kit 开发者平台。
  2. 登录账号,没有账号请先注册。
  3. 选择 我的 SDK
  4. 选择 License 申请 -> 新建 License 申请,按要求填写信息,若要控制第三方厂家设备,请在备注中说明厂家名称以及具体产品型号,提交审核。
  5. 审核通过之后,可以在申请页面看见 License

1.3 SDK集成方法

Android 集成

将SDK压缩包内的JAR文件和so文件导入到工程中,SDK 支持 Android2.3.1 以后版本,支持 armeabi/armeabi-v7a/arm64-v8a/mips/mips64/x86_64/x86 指令集。

Android 平台使用 BLSmartHomeAPI.getInstanceBLNetwork(Content content) 进行 SDK 实例化,SDK 为单例模式。

在使用 SDK 时,应用需要如下权限:

<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />

iOS 集成

SDK 支持 iOS6.0 以后版本, 支持 armv7/armv7s/arm64/i386/x86_64 指令集。

iOS 平台使用 [[BLSmartHomeAPI sharedDNASDK] sdkInit:[param toJSONString]] 进行 SDK 实例化,SDK 为单例模式。

1.4 SDK初始化

public String sdkInit(String params);
- (NSString *)sdkInit:(NSString *)params
params: 
        {
            "loglevel": 0,                                  // SDK日志打印级别
            "license": "xxxxxxxxxxxxx",                     // 申请的License
            "packageName": "cn.com.broadlink.SDKDemo"       // 申请License时的应用包名
        }

return: 
        {
            "status": 0,
            "msg": "init success"
        }

1.5 EasyConfig配置API

public String deviceEasyConfig(String action, String params)
- (NSString *)deviceEasyConfig:(NSString *)action params:(NSString *)params

设备开始配网

action:     ConfigStart
params:
            {
                    "ssid":"Broadlink",      // wifi ssid
                    "password":"12345678",   // wifi密码
                    "timeout": 60,           // 配置超时时间,单位秒
                    "cfgversion": 2          // 配网版本
            }

return:
            {
                    "status":0,
                    "msg": "success",           //配网结果
                    "mac": "00:11:22:33:44:55"  //配网设备MAC
            }

设备取消配网

action:     ConfigCancel
params:
            {
            }

return:
            {
                    "status":0,
                    "msg": "success",           //配网结果
            }

1.6 soft-ap 模式API

public String deviceAPConfig(String action, String params)
- (NSString *)deviceAPConfig:(NSString *)action params:(NSString *)params

获取设备支持的AP列表

action:     ScanAPList
params:
            {
                    "timeout": 7000,      // 扫描AP列表超时时间,推荐7000ms
            }

return:
            {
                    "status":0,
                    "msg": "success",           //扫描结果
                    "list": [
                        {
                            "ssid": "xxxxx",
                            "type": 0/1/2/3/4,   //配置AP的加密方式 0:无加密 1:WEP 2:WPA1 3:WPA2 4:WPA/WPA2 mixed
                            "rssi": xxx 
                        },
                        ......
                    ]
            }

AP配网

action:     APConfig
params:
            {
                    "APInfo": {
                            "ssid": "xxxxx",
                            "password":"xxxxx",         // 配置AP的密码
                            "type": 0/1/2/3/4,          // 配置AP的加密方式 0:无加密 1:WEP 2:WPA1 3:WPA2 4:WPA/WPA2 mixed
                            "timeout": 5000,            // 配置AP超时时间
                    }
            }

return:
            {
                    "status":0,
                    "msg": "success",           //配置结果
            }

1.7 设备发现API

public String deviceProbe(String action, String params)
- (NSString *)deviceProbe:(NSString *)action params:(NSString *)params
action:     DeviceProbe
params:
            {
                    "scantime": 3000,           // 搜索设备的超时时间,默认 3000ms
                    "version": 1,
                    "pids" : [
                             "xxxxxxxxxxxxxxxxxxx"                   // 搜索指定设备Pid列表,默认为空,不限制设备Pid
                        ],
            }

return:
            {
                    "status":0,
                    "msg": "success",           // 搜索结果
                    "list": [
                        deviceInfo              // 搜索到的设备列表
                    ]
            }

1.8 配对API

public String devicePair(String action, String params)
- (NSString *)devicePair:(NSString *)action params:(NSString *)params
action: DevicePair
params:
            {
                    "deviceInfo": deviceInfo,    // Probe搜索到的设备信息
                    "timeout": 3000,            // 配对超时实际,默认3000ms
                    "version": 1                // 配对版本
            }

return:
            {
                    "status":0,
                    "msg": "success", 
                    "devicePairedInfo": devicePairedInfo //配置成功上的设备信息
            }

1.9 设备控制API

public String deviceControl(String action, String params)
- (NSString *)deviceControl:(NSString *)action params:(NSString *)params

红外码测试

action: RM_Panel_Test
params:
            {
                    "devicePairedInfo": devicePairedInfo,    // 配置成功上的设备信息
                    "data" : {                      //  云端返回信息
                        "pid":"",                   // 设备类型
                        "ircodeid":"",              // 红外码ID
                        "timestamp":1514736000000,  // 云端返回测试时间戳
                        "ircode": {
                            "name": "打开空调",                                  //本条红外码功能名称
                            "function":"on",                                    //本条红外码功能
                            "desc":"xxx",                                       //本条红外码描述信息
                            "code":"2600121343241325243521342342141"            //红外码值
                        }
                    },
                    "version": 1                // 配对版本
            }

return:
            {
                    "status":0,
                    "msg": "success", 
                    "devicePairedInfo": devicePairedInfo    // 新返回创建的设备信息
            }

透传接口

action: dev_passthrough
params:
            {
                    "devicePairedInfo": devicePairedInfo,    // 配置成功上的设备信息
                    "command": "xxxxxx",         // 透传指令,BASE64 EnCode
                    "version": 1                // 配对版本
            }

return:
            {
                    "status":0,
                    "msg": "success", 
                    "command": "xxxxxxxxx"    // 透传返回指令,BASE64 EnCode
            }

设备锁定

该接口执行成功之后,设备将不再被其他手机发现配对。

action: dev_info
params:
            {
                    "devicePairedInfo": devicePairedInfo,    // 配置成功上的设备信息
             		"data" : { 
             			"lock":true				// 设备lock
             		},
                    "version": 1                // 配对版本
            }

return:
            {
                    "status":0,
                    "msg": "success"
            }