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:

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:

Note:

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:

控制流程

  1. Account Login ,You need to log in before remote control.
  2. Device Configuration ,The process of sending SSID and password to router and configuring device connecting to router.,The device cannot be configured? Click here?
  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.

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

  1. Obtain IR code script
  2. After the IR code script is downloaded, you can call the API to obtain the product function parameters of the specified product
  3. You can obtain the IR command in binary after the function parameters are obtained in API
  4. 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:

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