App SDK device management description

API Overview

Name Description
Configure Device deviceConfig
Configure in AP Mode deviceAPConfig
Discover Device in WLAN startProbe
Add Device addDevice
Pair Device pair
Device Control - Direct Control dnaPassthrough
Query script version queryScriptVersion
Download script downloadScript
Get profile queryProfileByPid
Device Control - Direct Control dnaControl
Control Device - Common Timers General Timer Tasks updateTask
Common timers / delay timer General Timer/delayed Timer
Periodic timer Periodic tasks
Repeated timer Cycle Timer/Anti-theft timer
Query timer list - queryTask queryTask
Delete timer - delTask delTask
Query timer - queryTaskData queryTaskData
Query device state queryDeviceState
Query device time queryDeviceTime
Query uploaded device data queryDeviceData
Update Firmware updateFirmware
Get the script information of RMAC Ircode queryRMACIRCodeInfomation
Get Hex format of Ircode which RMAC sent queryRMACIRCodeData
Calculate sunrise and sunset time calulateSunriseTime
Get a list of devices added to the sdk queryDeviceAddedList

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

Parameter Name Parameter Type Note Is it necessary
deviceConfigParam BLDeviceConfigParam Device configuration parameters as follows Y
timeout int Device configuration timeout period (default 75s) Y

BLDeviceConfigParam

Parameter Name Parameter Type Note Is it necessary
ssid String Wi-Fi SSID Y
password String Wi-Fi Password Y
gatewayaddr String Gateway address N
version int Configuration protocol version (default is 2) Y

Return Parameter

BLDeviceConfigResult

Parameter Name Parameter Type Note
mac String Device MAC address
did String Device DID
devaddr String Device IP address in WLAN

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

Parameter Name Parameter Type Note Is it necessary
timeout int Scan timeout (recommended >5s) Y

Return Parameter

BLGetAPListResult

Parameter Name Parameter Type Note
list List List of APs

BLAPInfo

Parameter Name Parameter Type Note
ssid String AP’s SSID
rssi int AP’s signal strength
type int AP’s encryption method

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

Parameter Name Parameter Type Note Is it necessary
probeInterval int Scanning interval Yes,The default is 3000 ms

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

Parameter Name Parameter Type Note
did String Device ID which is used to identify the unique device
mac String Device MAC address
pid String Device product ID which is used to identify the category of device
name String Device name
type int Device type
lock bool Is the device locked (cannot be discovered if it is set to true)
newconfig bool Is the device newly added
password int Device control passoword for V1 devices
id int Device control ID–You need to manually pair and set it here.
key String Device control key–You need to manually pair and set it here.
state int Device online status
lanaddr String Device IP address in WLAN
freshStateTime int Device refresh time upon last scan
pDid String Parent device ID if it is an accessory (subDevice)
extend String Extension information
ownerId String Device owner, usually familyId
deviceId String Device id, add ownerId information to the original did, if ownerId is not set then it is equivalent to did, read-only property

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device id Y
sDeviceId String If it is subdevice,the subdevice did can be void N
data byte[] Control data Y
configParam BLConfigParam Configuration parameters N

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

Parameter Name Parameter Type Note Is it necessary
pidList List Query device PID list Y

Return Parameter

BLQueryResoureVersionResult

Parameter Name Parameter Type Note
versions List Version list

BLResourceVersion

Parameter Name Parameter Type Note
version String Version
pid String Device PID

2.7.2 Download script

public static BLDownloadScriptResult downloadScript(String pid);

Request Parameter

Parameter Name Parameter Type Note Is it necessary
pid String Product id Y

Return Parameter

BLDownloadScriptResult

Parameter Name Parameter Type Note
savePath String Script saved path

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

Parameter Name Parameter Type Note Is it necessary
pid String Query device PID
profilePath String Profile file path Query default path if it is void.

Return Parameter

BLProfileStringResult

Parameter Name Parameter Type Note
profile String Profile infos

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device id Y
sDeviceId String If it is subdevice,the subdevice deviceId can be void N
stdControlParam BLStdControlParam Control data type Y
configParam BLConfigParam Configuration parameters(can be void) N

Return Parameter

BLStdControlResult

Parameter Name Parameter Type Note
data BLStdData Returned control data

BLStdData

Parameter Name Parameter Type Note
act String set / get operation (default is set)
params ArrayList<String> Control variable list
vals ArrayList<ArrayList<Value>> Control variable value list

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

Parameter Name Parameter Type Note Is it necessary
deviceId String eviceId Y
sDeviceId String If it is subdevice,the subdevice deviceId can be void N
dataStr String Control data type Y
cmd String Control Command Y
configParam BLConfigParam Configuration parameters(can be void) N

Return Parameter

Parameter Name Parameter Type Note
String Returned control data

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

Timer name Timer type value Timer parameter Description
General timer 0 timerInfo General timers
Delay timers 1 timerInfo Delay timer is a general timer after a specified period, which is controlled by UI.
Repeated timer 2 periodInfo Repeated timers
Cycled timer 3 cycleInfo Cycled timer is to perform 2 actions alternatively in specified period
Random timers 4 cycleInfo Execute 2 different timers randomly

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device ID Y
sDeviceId String If it is subdevice,the subdevice sDeviceId can be void N
taskType int Task type (this interface only support 0/1) Y
isNew bool true - new timer, false - edit timer Y
task BLTimerInfo Please refer to the following table for detailed parameters Y
stdData BLStdData Commands to be executed by the timer Y

*BLTimerInfo*:

Parameter Name Parameter Type Note
index int Timer index. This does not need to be set but must be specified if the timer is changed.
enable bool If the timer is enabled
year month day int The exact date for timer
hour min sec int The exact time for timer

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device ID Y
sDeviceId String If it is subdevice,the subdevice sDeviceId can be void N
isNew bool true - new timer, false - edit timer Y
task BLPeriodInfo Please refer to the following table for detailed parameters Y
stdData BLStdData Commands to be executed by the timer Y

*BLPeriodInfo*:

Parameter Name Parameter Type Note
index int Timer index. This does not need to be set but must be specified if the timer is changed.
enable bool If the timer is enabled
repeat int[] Week days. For example [1, 3, 5] for every Monday, Wednesday and Friday in each week.
hour min sec int The exact time for timer

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device ID Y
sDeviceId String If it is subdevice,the subdevice sDeviceId can be void N
taskType int Task type (this interface only support 34) Y
isNew bool true - new timer, false - edit timer Y
task BLCycleInfo Please refer to the following table for detailed parameters Y
stdData1 BLStdData The first command to be executed by the timer Y
stdData2 BLStdData The second command to be executed by the timer Y

*BLCycleInfo*:

Parameter Name Parameter Type Note
index int Timer index. This does not need to be set but must be specified if the timer is changed.
enable bool If the timer is enabled
repeat int[] Week days. For example [1, 3, 5] for every Monday, Wednesday and Friday in each week.
cmd1duration int Time to execute command 1
cmd2duration int Time to execute command 2
start_hour start_min start_sec int The start time for timer
en_hour end_min end_sec int The end time for timer

2.8.4 Query timer list - queryTask

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

Request Parameter

Parameter Name Parameter Type Note Is it necessary
deviceId String Device id Y
sDeviceId String If it is subdevice,the subdevice sDeviceId can be void N

Return Parameter

BLQueryTaskResult

Parameter Name Parameter Type Note
timer BLTimerInfo[] Common timer list max 16
delay BLTimerInfo[] Delay timer list max 16
period BLPeriodInfo[] Repeated timer list max 16
cycle BLCycleInfo[] Cycled timer list max 2
random BLCycleInfo[] Random timer list max 2

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device id Y
sDeviceId String If it is subdevice,the subdevice sDeviceId can be void N
taskType int Timer type (this interface support 0/1/2/3/4) Y
index int Index of timer in timer list Y

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device id Y
sDeviceId String If it is subdevice,the subdevice sDeviceId can be void N
taskType int Timer type (this interface support 0/1/2/3/4) Y
index int Index of timer in timer list Y

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

Parameter Name Parameter Type Note Is it necessary
listDevice ArrayList Device list Y

返回值说明

[
    {
        "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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device ID Y

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device id Y
familyId String Family id N
startTime String Start time. Format “yyyy-MM-dd_HH:mm:ss” Y
endTime String End time. Format “yyyy-MM-dd_HH:mm:ss” Y
type String Report type of uploaded data Y

Type parameter description

Parameter value Parameter description
fw_currentstate_v1 Device attribute (default report)
fw_energystatus_v1 History data (general electrical)
fw_energystats_v1 Power measurements (general electrical)
fw_spminielec_v1 SP mini power measurement
fw_spminiswitch_v1 SP mini on/off history
fw_s1push_v1 S1 push notifications

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device id Y
url String Firmware URL Y

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

Parameter Name Parameter Type Note Is it necessary
scriptPath String Script path name Y

Return Parameter

Parameter Name Parameter Type Note
infomation String Script information in Json format

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

Parameter Name Parameter Type Note Is it necessary
scriptPath String Script path name Y
params BLQueryIRCodeParams setting params of AC Y

Return Parameter

Parameter Name Parameter Type Note
freq int Ircode transmission frequency
ircode String Hex format of Irdode

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

Parameter Name Parameter Type Note Is it necessary
date String Date format, like “2018-01-01” Y
longitude double longitude
latitude double latitude

Return Parameter

Parameter Name Parameter Type Note
sunrise String sunrise time,like “01:04:11(UTC)”
sunset String sunset time,like “19:01:29(UTC)”

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

Parameter Name Parameter Type Note Is it necessary
deviceId String Device ID Y

Return Parameter

Parameter Name Parameter Type Note
serverlist Array Server Information List

ServerBean

Parameter Name Parameter Type Note
host String Server Domain
ip String Server IP address

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

Parameter Name Parameter Type Note Is it necessary
NA NA NA NA

Return Parameter

Parameter Name Parameter Type Note
NA ArrayList Device Information List