Configuration SDK reference

overview

Configuration SDK main callflow:

整体框图

注意:

1.  Call the deviceProbe interface to get the device basic information deviceInfo from the LAN, and then call the devicePair interface to get the device details devicePairedInfo
2.  You need to save devicePairedInfo to the developer's own cloud database, and use this device information to control device by Cloud to Cloud API
3.  If the device is reset, after re-configuration, the saved devicePairedInfo must be deleted, and the deviceProbe and devicePair operations are performed again.

1.1 Object Definitions

deviceInfo
{
     "did":"",      //Device unique ID
     "pid":"",      //Device category ID
     "mac":"",      //Device MAC address
     "name":"",     //Device name
     "lanaddr":"",  //Device WLAN IP address
     "extend":""    //Device extension information
}


devicePairedInfo
{
     "did":"",      //Device unique ID
     "pid":"",      //Device category ID
     "mac":"",      //Device MAC address
     "cookie":""    //Device cookie during pairing
}

1.2 Things to be prepared

Get Kit module

Please contact us to get BroadLink DNA Kit module if you still not have it.

Create, test and publish product

If you do not have a product yet, please log in to our developer console and register an account to create, test and publish your product.

Apply license

For device security, all SDK users need to apply the license from BroadLink. The license is associated with your bundle ID. You need to apply different licenses for each bundle ID if necessary.

  1. Enter BroadLink DNA Kit developer platform.
  2. Log in with your account or register a new one.
  3. Choose My SDK.
  4. Go to “License Management” > “Apply New License” and fill in required information. If you also want to control third party devices, you need to specify the vendor name and model of specific device in note field and submit for approval.
  5. You will find the license on license management page after approval

1.3 How to integrate SDK

For Android

Import the JAR files and so files in SDK zip file to your project. The SDK supports Android 2.3.1 and later versions and command sets of armeabi/armeabi-v7a/arm64-v8a/mips/mips64/x86_64/x86.

You can use NetworkAPI.getInstanceBLNetwork(Content content) to instantiate the SDK on Android platform in singleton. The App requires the following permission during the use of 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" />

For iOS

The SDK supports iOS 6.0 and later versions and command sets of armv7/armv7s/arm64/i386/x86_64.

You can use [[BLSmartHomeAPI sharedDNASDK] sdkInit:[param toJSONString]] to instantiate the SDK on iOS platform in singleton.

1.4 Initialize SDK

public String sdkInit(String params);
- (NSString *)sdkInit:(NSString *)params
params: 
        {
            "loglevel": 0,                        // SDK journal printing level
            "license": "xxxxxxxxxxxxx",           // Applied license
            "packageName": "cn.com.broadlink.SDKDemo"    // Bundle ID associated with license
        }

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

1.5 API for EasyConfig

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

Start network configuration

action:     ConfigStart
params:
            {
                    "ssid":"Broadlink",      // wifi ssid
                    "password":"12345678",   // wifi password
                    "timeout": 60,           // Configuration timeout (unit: s)
                    "cfgversion": 2          // Version of configuration
            }

return:
            {
                    "status":0,
                    "msg": "success",           //Configuration result
                    "mac": "00:11:22:33:44:55"  //MAC address of configured device
            }

Cancel network configuration

action:     ConfigCancel
params:
            {
            }

return:
            {
                    "status":0,
                    "msg": "success",           //Configuration result
            }

1.6 API for SoftAP

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

Get AP list supported by the device

action:     ScanAPList
params:
            {
                    "timeout": 7000,    // Timeout for scaning AP list (recommended: 7000ms)
            }

return:
            {
                    "status":0,
                    "msg": "success",           //Scan result
                    "list": [
                        {
                            "ssid": "xxxxx",
                            "type": 0/1/2/3/4,   //Configure encryption for AP   0:no encryption 1:WEP 2:WPA1 3:WPA2 4:WPA/WPA2 mixed
                            "rssi": xxx 
                        },
                        ......
                    ]
            }

AP configuration

action:     APConfig
params:
            {
                    "APInfo": {
                            "ssid": "xxxxx",
                            "password":"xxxxx",         // password
                            "type": 0/1/2/3/4           //Configure encryption for AP   0:no encryption 1:WEP 2:WPA1 3:WPA2 4:WPA/WPA2 mixed
                    }
            }

return:
            {
                    "status":0,
                    "msg": "success",           //Configuration result
            }

1.7 API for device discovery

public String deviceProbe(String action, String params)
- (NSString *)deviceProbe:(NSString *)action params:(NSString *)params
action:     DeviceProbe
params:
            {
                    "scantime": 3000,           // Timeout for searching devices (default: 3000ms)
                    "version": 1,
                    "pids" : [
                             "xxxxxxxxxxxxxxxxxxx"                   // Search PID list of specified devices. The default value is null means no limit is set for device PID.
                        ],
            }

return:
            {
                    "status":0,
                    "msg": "success",           // Search result
                    "list": [
                        deviceInfo              // Found device list
                    ]
            }

1.8 API for pairing

public String devicePair(String action, String params)
- (NSString *)devicePair:(NSString *)action params:(NSString *)params
action: DevicePair
params:
            {
                    "deviceInfo": deviceInfo,    // Probed device information
                    "timeout": 3000,            // Timeout for pairing (default: 3000ms)
                    "version": 1                // Matching version
            }

return:
            {
                    "status":0,
                    "msg": "success", 
                    "devicePairedInfo": devicePairedInfo //Information of device paired successfully
            }

1.9 API for device control

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

Ircode testing

action: RM_Panel_Test
params:
            {
                    "devicePairedInfo": devicePairedInfo,    // Information of device paired successfully
                    "data" : {                      //  Information returned from cloud
                        "pid":"",                   // Device type
                        "ircodeid":"",              // IR code ID
                        "timestamp":1514736000000,  // Testing time tag returned from cloud
                        "ircode": {
                            "name": "Turn on aircon",                                  //Function name of current IR code
                            "function":"on",                                    //Functions supported in this IR code
                            "desc":"xxx",                                       //Description of current IR code
                            "code":"2600121343241325243521342342141"            //IR code value
                        }
                    },
                    "version": 1                // Matching version
            }

return:
            {
                    "status":0,
                    "msg": "success", 
                    "devicePairedInfo": devicePairedInfo    // Newly returned created device information
            }

Passthrough interface

action: dev_passthrough
params:
            {
                    "devicePairedInfo": devicePairedInfo,    // Information of device paired successfully
                    "command": "xxxxxx",         // Pass-through command,BASE64 EnCode
                    "version": 1                // Pairing version
            }

return:
            {
                    "status":0,
                    "msg": "success", 
                    "command": "xxxxxxxxx"    //  Pass-through returned command,BASE64 EnCode
            }

Lock device

After the interface is successfully executed, the device will no longer be probed by other mobile phones.

action: dev_info
params:
            {
                    "devicePairedInfo": devicePairedInfo,    // the device information after paired
             		"data" : { 
             			"lock":true				// lock device
             		},
                    "version": 1                // pairing version
            }

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