App SDK introduction
App SDK Introduction
AppSDK includes the following libraries:
It provides interfaces of core functions mainly for device control, device configuration and maintenance related information.
It provides account system for sign-in / sign-up of BroadLink accounts and account linking related functions.
It provides library for home management of homes, rooms and devices.
It provides interfaces for query, downloading and decoding of IR codes.
The picture shown below describes the relationship of each modules:
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");
You must initialize
BLLetCore library during initialization and get
companyId before initialization of other libraries (
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.
The SDK will return the following information after login:
|PARAMETER NAME||PARAMETER TYPE||NOTE|
|fname||String||User first name|
|lname||String||User last name|
|phone||String||User phone number|
|countrycode||String||Country code for phone number, for example: 00852|
|loginip||String||IP address logged in|
|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
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.
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.
You can create different rooms in a home, for example, living room and bedroom.
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
- Rooms in this home
- Modules in this home
- Devices in this home
- Accessories in this home
- After the home is created on cloud, the cloud server will assign a unique home ID for this account ——
- After each time the home information is changed on cloud, the cloud server will assign a new home version ——
- If the user uploaded avatar during creating home, the cloud server will create a path for the avatar——
- 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
**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.
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
The SDK sends commands to devices by UDP packets to control devices. The device information contains device IP address in WLAN
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
The device can be controlled by direct control and script control.
The SDK directly sends binary data to device and device returns with binary data. The App needs to resolve the binary data.
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
startProbeand return to the developer result by callback.
- Device Pairing，Use
pairto set obtained
- Add Device ， Use
addDeviceto 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