App SDK home management description

API Overview

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:

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

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：

• 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.

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

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:

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

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

Return Parameter

BLFamilyInfoResult

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

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

Return Parameter

Please refer to the description of BLFamilyInfoResult

2.1.7 Delete home

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

Request Parameter

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

Return Parameter

BLManageRoomResult

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 home ID is associated when the module is created —— familyId
• An unique module ID will be assigned on cloud after the module is created —— moduleId
• The module is associated with devices/accessories and the information for devices/accessories are stored in moduleDevs
• The module type is assigned when the module is created —— moduleType
• The room for the module is not fixed. You can move the module to any specified room ID —— roomId
• You can specify if you want to move devices with module —— followDev

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

Return Parameter

BLModuleControlResult

2.3.3 Delete module

The first step:Delete device

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

Request Parameter

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

2.3.4 Edit module information

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

Request Parameter

2.3.5 Move module

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

Request Parameter

2.3.6 Edit and move module

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

Request Parameter