App SDK device management description

API Overview

1. Introduction of Basic Functions

It is developed based on previous DNASDK, providing device configuration, discovery, pairing and unified device control functions.

Basic Concept

Device configuration

The SDK sends UDP messages in broadcast or multicast mode to devices with Wi-Fi SSID and password input on your phone. The device then sends DHCP request to the router after it receives the configuration information and completes the configuration process.

Discover Device

The SDK can discover devices with BroadLink protocol in the same WLAN.

Device Paring

The SDK will get the unique ID and key for device control. You need to use these two values during any device control, otherwise the SDK will return -7.
Id and key are the necessary parameters for remote control of the device. The id and key are generated by the device and will only be changed if the device is reset and reconfigured.

Device Control

Types by network: Local control and remote control
Types by command: Direct control and script control

Local control

The SDK sends commands to devices by UDP packets to control devices.

The device information contains device IP address in WLAN

Remote control

The SDK sends device control messages via device control server to enable remote control.

You must use BLLetAccount to complete account login before control.

The main callflow as below ：

The main process：

1. 1.Account Login ，You need to log in before remote control.
2. 2.Device Configuration ， The process of sending SSID and password to router and configuring device connecting to router.设备无法配置入网点击这里?
3. Device discovery Automatic discovery of devices in WLAN using startProbe and return to the developer result by callback.
4. Device Pairing Use pair to set obtained id and key to device
5. Add Device ，Use addDevice to add device information to SDK for management.
6. Download Script ，The device profile contains device configuration and standard control commands.
7. Device Control ，APPSDK can automatically detect your network environment (mainly from your IP address) to determine using local control or remote control.

Device control is divided into Direct control and script control:

Direct control

The SDK directly sends binary data to device and device returns with binary data. The App needs to resolve the binary data.

Script control

A control script will be generated for each product created on BroadLink DNAKit. The device profile contains device configuration and standard control commands.

The SDK can download the script to specified path and convert different control commands to be binary data during controlling. Conversely, it can also convert returned script to be binary data for App use.

2. API Description

Device management interfaces will be instantiated as singleton after initialization of BLLet class in BLLetCore library.

You can invoke controller attribute in BLLet class and relevant instance on iOS.

You can invoke controller static method in BLLet class on Android.

2.1 Configure Device

deviceConfig sends UDP packets in WLAN to configure the device in the network.

Note: 1.We provide 3 versions of device configuration protocol for developers and they are compatible. However, it is recommended for developers to choose the suitable protocol in interface in advance to improve the configuration efficiency.
2.This function will return when one of devices is correctly configured if you have more than one device to be added. The SDK cannot guarantee all devices can be added in WLAN for configuration of multiple devices at the same time.
3.You may get error code “-4000” for configuration failure under specific routers because of the high data load on router against fast sending of configuration packets, causing failure of device obtaining IP address from router DHCP. For this issue, the developers need to determine by themselves the result of configuration using device discovery function.

    public static BLDeviceConfigResult deviceConfig(BLDeviceConfigParam deviceConfigParam, int timeout);

Request Parameter

BLDeviceConfigParam

Return Parameter

BLDeviceConfigResult

2.2 Configure in AP Mode

For AP configuration, developers need to prompt the user to switch the device to AP mode and connect the phone to this AP. Then developers can call specific interfaces to complete this process.

You can obtain the available Wi-Fi SSID list by the following interface:

public static BLGetAPListResult deviceAPList(int timeOut);

Request Parameter

Return Parameter

BLGetAPListResult

BLAPInfo

Then specify the SSID from list for configuration:

public static BLAPConfigResult deviceAPConfig(String ssid, String password, int type, BLConfigParam configParam);

After completion, the developers need to determine by themselves the result of configuration using device discovery function.

2.3 Discover Device in WLAN

The SDK can discover devices with BroadLink protocol in the same WLAN.

The discovery process may take long time and single scan may not find all devices. So the SDK will open background threads during the process and report to the developer by call-back function.

2.3.1 Enable/disable device discovery

public static void startProbe(int probeInterval);
public static void stopProbe();

Request Parameter

2.3.2 Listen device return

You can invoke the interface BLDeviceScanListener to enable report of device discovery return during each scan.

public static void setOnDeviceScanListener(BLDeviceScanListener scanListener);

public abstract class BLDeviceScanListener {
    public abstract void onDeviceUpdate(BLDNADevice device, boolean isNewDevice);
}

BLDNADevice

Note:

1.SDK reports the scan result each time by the interface onDeviceUpdate. 2.onDeviceUpdate You can know if the device is already added by the interface isNewDevice. 3.You can check the device information from newConfig attribute in BLDNADevice device to determine if the device is the device newly added.

2.4 Add Device

For better control of devices, the newly found devices need to be added to SDK for caching of its configuration. For subsequent operations, the developers only need to pass the device unique DID.

The SDK will query and maintain the status of all devices added in SDK.

If the device is not needed in SDK for controlling, the developers need to delete the device DID in SDK.

public static void addDevice(BLDNADevice device);
public static void addDevice(ArrayList<BLDNADevice> listDevice);

Note：

1.The developers must use addDevice to add the device or accessory to SDK before controlling.No matter which is wifi device or subdevice

2.5 Pair Device

Each device with BroadLink protocol will generate a control ID and key for secured control.

The key is unique if the device is not reset. The device will generate a new pair of control ID and key if it is reset.

public static BLPairResult pair(BLDNADevice device, BLConfigParam configParam);

Note:

1.This interface can be only used when device and phone are in the same WLAN. 2.If the interface returns -7 during control, please call again to obtain the new control ID and key. 3.The obtained ID and key need to be set to the information of device

2.6 Device Control - Direct Control

In this way, the SDK will pass the original data to device and vice versa.

public static BLPassthroughResult dnaPassthrough(String deviceId, String sDeviceId, byte[] data, BLConfigParam configParam);

Request Parameter

Return Parameter

BLPassthroughResult Parameter Name |Parameter Type | Note ———-| ———-| ————– data | byte[] | Returned control data

2.7 Device Control - Script Control

The device profile contains device configuration and standard control commands.

The PID is associated with a certain product category. For different products in the same category, you only need to download the script once.

2.7.1 Query script version

Device script contains version information. Please download the newer version if it is update

public static BLQueryResoureVersionResult queryScriptVersion(List<String> pidList);

Request Parameter

Return Parameter

BLQueryResoureVersionResult

BLResourceVersion

2.7.2 Download script

public static BLDownloadScriptResult downloadScript(String pid);

Request Parameter

Return Parameter

BLDownloadScriptResult

Note:

1.This interface needs to download files and may require longer time.
2.If the script download returns 403, please confirm whether the device has been added to the license.
3.If the script download returns 404, please confirm whether the script exists on the download platform and confirm that the download platform is a new platform or an old platform. View this parameter BLConfigParam.CONTROLLER_SCRIPT_DOWNLOAD_VERSION

2.7.3 Get profile

The device profile contains device configuration and standard control commands.

SDK will cache device profile. The profile will be updated if script changes. You need to manually delete the profile information in cache.

public static BLProfileStringResult queryProfileByPid(String pid, String profilePath);

Request Parameter

Return Parameter

BLProfileStringResult

2.7.4 Device Control - Direct Control

In this way, the device control commands must be sent following SDK specified rules.

The SDK will resolve the scripts sent from application layer to be device recognizable commands and send them to devices.

The data returned from devices will be also processed by the script to be formatted commands and sent back to the application.

You need to set data compliant with SDK interface and fill value and param to SDK interface.

The SDK then will pack the data to be standard JSON commands and send to the modules with resolved commands by control script.

The data returned from devices will be also processed by the script to be formatted commands and sent back to the application.

public static BLStdControlResult dnaControl(String deviceId, String sDeviceId, BLStdControlParam stdControlParam, BLConfigParam configParam);

Request Parameter

Return Parameter

BLStdControlResult

BLStdData

2.7.5 Device Control - General Control

The SDK provides generic control commands, and the APP organizes the commands and content itself and sends them to the device via the SDK.

public static String dnaControl(String deviceId, String sDeviceId, String dataStr, String cmd, BLConfigParam configParam)

Request Parameter

Return Parameter

cmd and dataStr have more formats, please refer to: [Device Control Command Detail].(https://docs.ibroadlink.com/public/appsdk/sdk_others/dnacontrol/)

2.8 Control Device - Common Timers

Note:

SP series smart plugs and RM series universal remotes are not applicable for this interface. Developers need to use the method in Demo in previous section for configuration.

If the device profile support dev_task command set, you can use this interface to set scheduled timer and period timer. You can add, delete, edit or query timers for devices using SDK.

All device control commands are executed by script. If you want to add/delete a timer, you can follow the same rules of stdData command for device script control to control timers.

Timer type

2.8.1 Common timers / delay timer

Common timer is very similar as delay timer, each supporting max 16 timers. Delay timer is controlled by UI.

you can use the following interface to add or edit timers:

public static BLQueryTaskResult updateTask(String deviceId, String sDeviceId,  int taskType,  
        boolean isNew, BLTimerInfo task, BLStdData stdData, BLConfigParam configParam);

Request Parameter

*BLTimerInfo*：

2.8.2 Repeated timer

The repeated timer performs every week at specified day and time.

public static BLQueryTaskResult updateTask(String deviceId, String sDeviceId, 
        boolean isNew, BLPeriodInfo task, BLStdData stdData, BLConfigParam configParam);

Request Parameter

*BLPeriodInfo*：

2.8.3 Cycled timer / random timer

Cycled timer / random timer is to perform 2 actions alternatively in specified period

Note:

Cycled timer / random timer currently only support max 2 timers. If you want to edit the timer, the index must be 0/1./1

public static BLQueryTaskResult updateTask(String deviceId, String sDeviceId,  int taskType, boolean isNew, BLCycleInfo task, BLStdData stdData1, BLStdData stdData2, BLConfigParam configParam);

Request Parameter

*BLCycleInfo*：

2.8.4 Query timer list - queryTask

public static BLQueryTaskResult queryTask(String deviceId, String sDeviceId, BLConfigParam configParam);

Request Parameter

Return Parameter

BLQueryTaskResult

2.8.5 Delete timer

You need to specify the type and index of the timer of if you want to delete it.

You can get the information by querying timer list.

public static BLQueryTaskResult delTask(String deviceId, String sDeviceId, int taskType, int index, BLConfigParam configParam);

Request Parameter

2.8.6 Query timer - queryTaskData

You need to specify the type and index of the timer of if you want to query it. You can get the actual value of command executed.

public static BLTaskDataResult queryTaskData(String deviceId, String sDeviceId, int taskType, int index, BLConfigParam configParam);

Request Parameter

2.8.7 Timer display time zone setting

Since the time zone used on the device is always in UTC/GMT+08:00, when setting and displaying the timing, it is necessary to convert the corresponding time difference value according to the time zone set by APP, and then send it down to the device side.

​ Ps: If this value is not set, the SDK will automatically convert it based on the difference between the current time of the phone and the time of the device.

Set the parameters in the global variable BLConfigParam on the iOS side.

/// Set APP time zone for setting conversion at timing setting
/// If UTC/GMT+08:00, set to 8. If UTC/GMT-05:00, set to -5 
@property (nonatomic, copy) NSNumber *utcTimeZone;

The following interface is called from the Android side.

/**
 * Set user time zone
 * If UTC/GMT+08:00, set to 8. If UTC/GMT-05:00, set to -5
 */
public static void setUtcTimeZone(int timeZone);

/**
 * Get user time zone
 */
public static int getUserTimeZone();

2.9 Query device state

Query the status of single device

The SDK will automatically query the device state for devices added to SDK (local, remote and offline). It will return “Unknown” if the device is not added to SDK.

If Probe thread is enabled in SDK, when Probe discovers a new device, the state of the device will be set to “local”.

If Probe thread is not enabled or Probe cannot discover new device, the SDK will query the state (online/offline) from cloud.

public static int queryDeviceState(String deviceId);

Bulk query the online status of the device

If a networked device maintains a heartbeat connection with the BroadLink cloud,the device is online

If the heartbeat disappears for a long time, the device is considered offline.

This interface can query the online status of the device in batches. Before using it, you need to confirm whether lid + devinfo.ibroadlink.com has been deployed.

public static BLQueryDeviceStatusResult queryDeviceOnServer(ArrayList<BLDNADevice> listDevice);

Request Parameter

返回值说明

[
    {
        "did":"xxxx",       // Device id
        "status": 0         // Device status (0:offline,1:online)
    }
]

2.10 Query device time

The device firmware does not identify time zones. The time running in device is UTC+8. If the developers want to display or set the device time in App, they need to obtain the device time and convert it to be local time.

public static BLDeviceTimeResult queryDeviceTime(String deviceId);

Request Parameter

2.11 Query uploaded device data

Some devices can upload data to cloud server periodically (e.g. smart plugs with energy meter). You can use this interface to query all data uploaded to server in specific time range.

Note：

•This interface currently only supports smart plugs with energy meter.

public static BLBaseBodyResult queryDeviceData(String deviceId, String familyId, String startTime, String endTime, String type)

Request Parameter

Type parameter description

Return Value Description

The value will be returned in json format strings. You can analyze the strings to get relevant information.

2.12 Update Firmware

To enable firmware update feature, you need to prepare a server for firmware update and pass the firmware URL to specified interface.

public static BLBaseResult updateFirmware(String deviceId, String url, BLConfigParam configParam);

Request Parameter

Return Value Description

Note:

The returned value is the acknowledge of command not result of firmware update.
The user needs to check the status of device and waiting for device reset after firmware update.

2.13 Get the script information of RMAC Ircode

The RMAC script is in Lua format. You need to use this interface to obtain RMAC Ircode script information.

public static BLIRCodeInfoResult queryRMACIRCodeInfomation(String scriptPath)

Request Parameter

Return Parameter

2.14 Get Hex format of Ircode which RMAC sent

The RMAC script is in Lua format. You need to use this interface to obtain Hex format of Ircode which RMAC sent.

public static BLIRCodeDataResult queryRMACIRCodeData(String scriptPath, BLQueryIRCodeParams params)

Request Parameter

Return Parameter

2.15 Calculate sunrise and sunset time

Get the specified date, longitude and latitude, get the sunrise and sunset time of the day

public BLSunriseResult calulateSunriseTime(String date, double longitude, double latitude)

Request Parameter

Return Parameter

2.16 Device connection server query

Get information about the server the device is connected to. This interface requires the device firmware to support the relevant commands to query.

public BLQueryDeviceConnectServerResult queryDeviceConnectServerInfo(String deviceId)

Request Parameter

Return Parameter

ServerBean

2.17 Get a list of devices added to the sdk

Query the list of devices that have been added to the sdk

 public ArrayList<BLDNADevice> queryDeviceAddedList()

Request Parameter

Return Parameter