App SDK home management description

API Overview

Name Description
Query home ID list under one account- queryLoginUserFamilyIdList queryLoginUserFamilyIdList
Get all information under the specified Home queryAllFamilyInfos
Create default home createDefaultFamily
Edit home information modifyFamilyInfo
Edit home icon modifyFamilyIcon
Delete home delFamily
Interfaces for Room manageFamilyRooms
Add module addModuleToFamily
Delete module delModuleFromFamily
Edit module information modifyModuleFromFamily
Move module moveModuleRoomFromFamily
Edit and move module modifyAndMoveModuleFromFamily

1. Overview

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.

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.

2. API Description

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

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

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

2.1 Interfaces for Home

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

2.1.1 Home information - BLFamilyInfo

Home information BLFamilyInfo contains the following attributes:

public class BLFamilyInfo {
   private String familyId; //Home ID 
   private String familyVersion; //Home version 
   private String familyIconPath; //Home icon path 
   private String familyName; //Home name 
   private String familyDescription; //Home description 
   private String familyPostcode; //Home postcode 
   private String familyMailaddress; //Home address 
   private String familyCountry; //Country 
   private String familyProvince; //State/province 
   private String familyCity; //City 
   private String familyArea; //District 
   private int familyLimit; //Permissions 
   private int familyLongitude; //Position (longitude) 
   private int familyLatitude; //Position (latitude) 
   private int familyOrder; //Home No. 
}

Note:

2.1.2 Query home ID list under one account- queryLoginUserFamilyIdList

A user can create multiple homes or join in multiple homes. You need to query the home ID list under this account when you use the home function and choose a home for other operations.

public static BLFamilyIdListGetResult queryLoginUserFamilyIdList();

Return Parameter

BLFamilyIdListGetResult

PARAMETER NAME PARAMETER TYPE NOTE
idInfoList List Home ID information - BLFamilyIdInfo

BLFamilyIdInfo

PARAMETER NAME       |PARAMETER TYPE   |NOTE

————— |——–| ——————– shareFlag | int | Is shared from other user familyId | String | Home ID familyVersion | String | Home version familyName | String | Home name

2.1.3 Get all information under the specified Home

public static BLAllFamilyInfoResult queryAllFamilyInfos(String[] ids);

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

2.1.4 Create default home

You can use this interface to create a new default home including home information and default room list.

public static BLFamilyInfoResult createDefaultFamily(String name, String country, String province, String city);

Request Parameter

Parameter Name Parameter Type Note
name String Default home name (if it is blank)
country String Country (optional)
province String State/province (optional)
city String City (optional)

Return Parameter

BLFamilyInfoResult

Parameter Name Parameter Type Note
familyInfo BLFamilyInfo Created home information
roomInfos List Default created room information list

2.1.5 Edit home information

You can use this interface to edit home information except familyId and familyVersion.

public static BLFamilyInfoResult modifyFamilyInfo(BLFamilyInfo familyInfo);

Request Parameter

Parameter Name Parameter Type Note
familyInfo BLFamilyInfo Home information to be edited

Return Parameter

Please refer to the description of BLFamilyInfoResult

2.1.6 Edit home icon

You can use this interface to edit home icon and upload it to cloud.

public static BLFamilyInfoResult modifyFamilyIcon(BLFamilyInfo familyInfo, File icon);

Request Parameter

Parameter Name Parameter Type Note
familyInfo BLFamilyInfo Current home information
icon File Home icon to be changed

Return Parameter

Please refer to the description of BLFamilyInfoResult

2.1.7 Delete home

public static BLBaseResult delFamily(String familyId, String familyVersion);

Request Parameter

Parameter Name Parameter Type Note
familyId String Home ID to be deleted
familyVersion String Current home version

2.2 Interfaces for Room

2.2.1 Room information - BLRoomInfo

Room information BLRoomInfo contains the following attributes:

public class BLFamilyRoomInfo {
    private String familyId;        //Home id
    private String roomId;          //Room id
    private String name;            //Room name
    private int type;               //Room type 
    private int order;              //房Room No. 

    private String action;          //Action  add,modify,del
}

You can add multiple rooms in a home, or edit / delete them.

2.2.2 Room operations API

The home ID is associated when the room is created —— familyId An unique room ID will be assigned on cloud after the room is created —— roomId You can add, delete or edit a room according to related attribute action of home information.

public static BLManageRoomResult manageFamilyRooms(String familyId, String familyVersion, List<BLFamilyRoomInfo> roomInfos);

Request Parameter

Parameter Name Parameter Type Note
familyId String Current home ID
familyVersion String Current home version
roomInfos List Room list to be operated. You can operate multiple room at the same time.

Return Parameter

BLManageRoomResult

Parameter Name Parameter Type Note
familyId String Current home ID
familyVersion String Current home version

2.3 Interfaces for Module

Home module is the basic unit for home control. You will be able to control single device, multiple devices, scenes and custom template in a home by actions to the module.

2.3.1 Module information - BLModuleInfo

public class BLFamilyModuleInfo {
    private String familyId;                            //Home id
    private String roomId;                              //Room id
    private String moduleId;                            //Module id
    private String name;                                //Module name
    private String iconPath;                            //Module icon path
    private List<ModuleDeviceInfo> moduleDevs;          //Device list under this module
    private int followDev;                              //Move devices with module? 0-NO 1-YES 
    private int order;                                  //Module No.
    private int flag;                                   //Module Flag
    private int moduleType;                             //Module type
    private String scenceType;                          //Scene type
    private String extend;                              //Module extension information defined by user 
}

注意:

The device list ModuleDeviceInfo under the module contains the following contents:

public static class ModuleDeviceInfo{
    private String did;                     //Device id
    private String sdid;                    //Subdevice id
    private int order;                      //No.
    private String content;                 //Device extension content defined by user 
}

The module type moduleType is defined as:

public class BLModuleType {
    public static final int Scene = 0;
    public static final int Sp = 1;                     //Smart plugs 
    public static final int PowerConsumption = 2;       //Power consumption statistic
    public static final int Common = 3;                 //Modules for general purpose (Other module types mainly used to identify devices associated on DNAKit)
    public static final int ControlCenter = 4;
    public static final int Customize_Scene = 5;        //User-defined scenes 
    public static final int HK_SP = 6;                  //homekit smart plugs 

    public static final int RM = 9;                     //RM
    public static final int RM_AC = 10;                 //RM AC 
    public static final int RM_TV = 11;                 //RM tv without channel information 
    public static final int RM_TOPBOX = 12;             //RM STB without channel information 
    public static final int RM_NETWORK_BOX = 13;        //RM Network box
    public static final int RM_TOPBOX_CHANNEL = 14;     //RM STB with channel
    public static final int RM_TC_1 = 15;
    public static final int RM_TC_2 = 16;
    public static final int RM_TC_3 = 17;
    public static final int RM_CURTAIN = 18;
    public static final int RM_LAMP = 19;
    public static final int RM_COMMON = 20;
    public static final int RM_LAMP_RADIO = 21;
    public static final int RM_CURTAIN_RADIO = 22;
    public static final int RM_CUSTOM_AC = 23;
    public static final int RM_NEW_TV = 24;             //RM New TV with  channel
    public static final int RM_NEW_TOPBOX = 25;         // RM New STB with channel

    public static final int SENSOR_GAS = 100;
    public static final int SENSOR_SMOKE_DETECTOR = 101;
    public static final int SENSOR_SECURITY = 102;
    public static final int SENSOR_IR = 103;
    public static final int SENSOR_DOOR = 104;
}

2.3.2 Add module

public static BLModuleControlResult addModuleToFamily(BLFamilyModuleInfo moduleInfo, BLFamilyInfo familyInfo,
                                                      BLFamilyDeviceInfo deviceInfo, BLFamilyDeviceInfo subDeviceInfo);

Request Parameter

Parameter Name Parameter Type Note
moduleInfo BLFamilyModuleInfo Module information to be added
familyInfo BLFamilyInfo Home infos
deviceInfo BLFamilyDeviceInfo Device infos
subDeviceInfo BLFamilyDeviceInfo deviceInfo

Return Parameter

BLModuleControlResult

Parameter Name Parameter Type Note
moduleId String Module ID
version String Current home version

2.3.3 Delete module

The first step:Delete device

public BLBaseResult removeDeviceFromFamily(String did, String familyId, String familyVersion)

Request Parameter

Parameter Name Parameter Type Note
did String Device ID
familyId String Current home ID
familyVersion String Current home version

The second step:Delete Module

Note:

If the module only contains device information, the module will be automatically deleted in the first step, no need to call this step.

public static BLModuleControlResult delModuleFromFamily(String moduleId, String familyId, String familyVersion);

Request Parameter

Parameter Name Parameter Type Note
moduleId String Module ID
familyId String Current home ID
familyVersion String Current home version

2.3.4 Edit module information

public static BLModuleControlResult modifyModuleFromFamily(BLFamilyModuleInfo moduleInfo, String familyId, String familyVersion);

Request Parameter

Parameter Name Parameter Type Note
moduleInfo BLFamilyModuleInfo Module information to be edited
familyId String Current home ID
familyVersion String Current home version

2.3.5 Move module

public static BLModuleControlResult moveModuleRoomFromFamily(String moduleId, String roomId, String familyId, String familyVersion);

Request Parameter

Parameter Name Parameter Type Note
moduleId String Module ID
roomId String Room ID
familyId String Current home ID
familyVersion String Current home version

2.3.6 Edit and move module

public static BLModuleControlResult modifyAndMoveModuleFromFamily(BLFamilyModuleInfo moduleInfo, String roomId, String familyId, String familyVersion);

Request Parameter

Parameter Name Parameter Type Note
moduleInfo BLFamilyModuleInfo Module infos
roomId String Id of the room which the module moves to
familyId String Current home ID
familyVersion String Current home version