Navigation :

App SDK introduction

App SDK Introduction

Overview

AppSDK includes the following libraries:

BLLetCore

It provides interfaces of core functions mainly for device control, device configuration and maintenance related information.

BLLetAccount

It provides account system for sign-in / sign-up of BroadLink accounts and account linking related functions.

BLLetFamily

It provides library for home management of homes, rooms and devices.

BLLetIRCode

It provides interfaces for query, downloading and decoding of IR codes.

The picture shown below describes the relationship of each modules:

Overview

1. Preparations

You need to prepare the following steps before start programming：

1.  Apply License
2.  Configure Project for Android
3.  Configure Project for iOS

Please refer to APPSDK Integrated description

2. SDK Initialization

To prevent SDK from releasing, you can initialize the SDK during application creation for Android and initialize it in AppDelegation for iOS.

Please refer to APPSDK Initialization description

You can configure the following parameters during initialization:

        // Configure parameter class
        BLConfigParam blConfigParam = new BLConfigParam();
        // 1. Set log level. The default value is 4 for printing all
        blConfigParam.put(BLConfigParam.CONTROLLER_LOG_LEVEL, "4");
        // 2. Set bottom layer log printing level. The default value is 4 for printing all 
        blConfigParam.put(BLConfigParam.CONTROLLER_JNI_LOG_LEVEL, "4");
        // 3. Set log saving path. The default path is in ../let/directory
        blConfigParam.put(BLConfigParam.SDK_FILE_PATH, "");
        // 4. Set local control timeout. The default value is 3000ms
        blConfigParam.put(BLConfigParam.CONTROLLER_LOCAL_TIMEOUT, "3000");
        // 5. Set remote control timeout. The default value 5000ms
        blConfigParam.put(BLConfigParam.CONTROLLER_REMOTE_TIMEOUT, "5000");
        // 6. Set control retry times. The default value is 1.
        blConfigParam.put(BLConfigParam.CONTROLLER_SEND_COUNT, "1");
        // 7. Set device control supported network mode. The default value is -1 for supporting all   0 - Local control only, Not 0 - Local/remote control 
        blConfigParam.put(BLConfigParam.CONTROLLER_NETMODE, "-1");
        // 8. Set resource downloading platform for script and UI The default value is 0 for legacy platform  1- New platform 
        blConfigParam.put(BLConfigParam.CONTROLLER_SCRIPT_DOWNLOAD_VERSION, "1");
        // 9. Batch query of minimal device numbers with online state 
        blConfigParam.put(BLConfigParam.CONTROLLER_QUERY_COUNT, "8");
        // 10. Use APPService. This feature is designed for new cluster. If you are using legacy cluster, please set the value as 0.
        blConfigParam.put(BLConfigParam.APP_SERVICE_ENABLE, "1");
        // 11. Set the cloud server access domain name
        blConfigParam.put(BLConfigParam.APP_SERVICE_HOST, "https://Your service host");
        // 12. Set device connection server info
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("tcp", "xxx");
        jsonObject.put("http","xxx");
        blConfigParam.put(BLConfigParam.DEVICE_CONNECTION_SERVER_HOST, jsonObject.toJSONString());

You must initialize BLLetCore library during initialization and get lid and companyId before initialization of other libraries (BLAccount / BLFamily / BLIRCode).

3. Account System

BroadLink provides developers with interfaces for integration of account system. Login to account is required for remote control from external networks.

Please refer to APPSDK account system description

You can integrate account system by one of the following options:

Use BroadLink shared account syste

Choose BroadLink shared account system when you apply for license. This account is shared with ihc App (can be used for login on ihc).
Use BroadLink independent account system

Choose BroadLink independent account system when you apply for license. This account is independent and isolated with other systems.
OAuth to BroadLink account system

If you want to remotely control or access to BroadLink products from your own client’s App, you can invoke a BroadLink OAuth page for account linking. You will get information like accessToken and pass it to SDK for login.
OAuth to Client account system

If you want to use third party account to log in to your App, you can use OAuth 2.0 to link your account to third party account on BroadLink cloud. You will get information like OpenID and AccessToken and pass them to SDK for login.

Account process

The SDK will return the following information after login:

PARAMETER NAME	PARAMETER TYPE	NOTE
userid	String	User ID
loginsession	String	Login session
nickname	String	User nickname
iconpath	String	Avatar URL
sex	String	User sex
birthday	String	User birthday
fname	String	User first name
lname	String	User last name
email	String	Email address
phone	String	User phone number
countrycode	String	Country code for phone number, for example: 00852
loginip	String	IP address logged in
logintime	String	Login time
pwdflag	int	If user password is set

4. Home Management

BroadLink provides a complete home management system for developers. With this system, you can combine concepts of user, device, module, room and home to build a complete control system for smart home products.

Please refer to APPSDK Home management description

User

A valid user in BroadLink account system is required for home management. Operations to home are only available when the user successfully logged in to the system. An user can create more than one home, join in other homes created by other users or invite other users join in the owner home.

Home

The users can add, delete, edit or search homes as well as inviting and quiting homes. Each change of home information will generate a new version of home. You need to specify the version of home for interfaces to be used later.

Room

You can create different rooms in a home, for example, living room and bedroom.

Module

To manage devices compliant with BroadLink protocol in a home, you need to use the concept of module. A module contains its home ID, room ID, module ID, module type and device list. You can create or delete a module, edit its basic information and move it to another room.

家庭流程

You can get all information of a home BLFamilyAllInfo by getting the detailed information of the specified home, including:

Home basic information BLFamilyInfo
Rooms in this home BLRoomInfo
Modules in this home BLModuleInfo
Devices in this home BLFamilyDeviceInfo
Accessories in this home BLFamilyDeviceInfo

Note：

After the home is created on cloud, the cloud server will assign a unique home ID for this account —— familyId
After each time the home information is changed on cloud, the cloud server will assign a new home version ——familyVersion
If the user uploaded avatar during creating home, the cloud server will create a path for the avatar—— familyIconPath
The developers can upload other information to cloud during creating home by user or change them using relevant interfaces later.

5. Device Management

BroadLink device control system provides device configuration, discovery, pairing and unified device control functions.

Please refer to APPSDK device management description

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.
The ID and key are necessary parameters for device remote control. They are generated by the device and will be only changed after the device is reset. You need to re-pair the device after it is reset.

**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. The function is only available when the account login has been finished with BLLetAccount.

The device can be controlled by 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.

The process of remote control works as below:

控制流程

Account Login ，You need to log in before remote control.
Device Configuration ，The process of sending SSID and password to router and configuring device connecting to router.，The device cannot be configured? Click here?
Device discovery ，Automatic discovery of devices in WLAN using startProbe and return to the developer result by callback.
Device Pairing，Use pair to set obtained id and key to device
Add Device ， Use addDevice to add device information to SDK for management.
Download Script ，The device profile contains device configuration and standard control commands.
Device Control ，APPSDK can automatically detect your network environment (mainly from your IP address) to determine using local control or remote control.

Download UI pack

You can download the available product UI pack provided by BroadLink by the following interface:

  /**
   * Download device control ui.
   *
   * @param pid Product pid
   * @return Download result
   */
  public static BLDownloadUIResult downloadUI(String pid);

You must include relevant library of Cordova if you wan to use those UIs and develop Cordova Plugin
for the following interface. Please refer to <

>

6. IR Code Service

BroadLink integrated multiple sets of IR code for home appliances. The developers need to apply separately to BroadLink for the permission of using IR code library.
The SDK provides interfaces for querying and downloading IR codes, obtaining basic information and generating control commands

Please refer to APPSDK Ircode management

The process of remote control works as below:

红外码流程

There are several steps for using IR code servic

Obtain IR code script
After the IR code script is downloaded, you can call the API to obtain the product function parameters of the specified product
You can obtain the IR command in binary after the function parameters are obtained in API
You can send the binary command to universal remote via API to control appliance.

You can use either way to obtain the IR code script: one button match and model selection.

One button match works as follows:

Set universal remote in learning mode
Point the remote to universal remote and press the button (normally ON/OFF)
Send the learnt command to matched API
If the API is matched, the script URL will be returned from cloud