Navigation :

APPSDK 家庭管理系统说明

API概览

名称	描述
查询账户下家庭ID列表	queryLoginUserFamilyIdList
获取指定家庭全部信息	queryAllFamilyInfos
创建默认家庭	createDefaultFamily
修改家庭信息	modifyFamilyInfo
修改家庭Icon	modifyFamilyIcon
删除家庭	delFamily
房间相关接口	manageFamilyRooms
添加模块	addModuleToFamily
删除模块	delModuleFromFamily
修改模块信息	modifyModuleFromFamily
模块移动所在房间	moveModuleRoomFromFamily
修改模块信息，且移动所在房间	modifyAndMoveModuleFromFamily

1. 概述

BroadLink提供了一套完整的家庭管理系统。通过该系统，开发者可以很好的将 *用户*，*设备*，模块，*房间*，家庭的概念结合起来，构造出一套完整的智能硬件控制系统。

用户

要使用该家庭管理系统必须接入使用BroadLink的账户系统，只有在用户成功登录之后，才能对家庭管理系统进行操作。单个用户可以创建多个家庭，同时也可以加入到其它用户创建的家庭，或者邀请其它用户加入自己创建的家庭。

家庭

本管理系统除了提供家庭的增、删、改、查的功能，还提供了家庭的邀请和退出的功能。家庭信息的每一次更新，都会产生新的家庭版本，在后续的部分接口中，需要指定该家庭版本。

房间

家庭下面可以创建不用的多个房间，例如客厅、卧室等。

模块

要使家庭能够管理符合BroadLink协议的设备，则需要使用模块的概念。模块内包含有所在家庭的ID，所在房间的ID，自身的ID和类型，模块下挂载的设备列表信息等。模块支持对模块的创建、删除，模块基本信息的修改，模块房间的移动。

2. API 接口介绍

家庭管理系统相关接口将会在 BLLetCore 库的 BLLet 类初始化之后，就会以单例的方式实例化。

iOS 系统可以调用 BLLet 类中的 family 属性和相应的实例方法。 Android 系统可以调用 BLLet 类中的 Family 静态类方法。

2.1 家庭相关接口

通过获取指定家庭的详细信息，可以得到一个家庭的全部信息 BLFamilyAllInfo ，这些信息包含有：

家庭自身的基本信息 BLFamilyInfo
家庭下房间信息列表 BLRoomInfo
家庭下模块信息列表 BLModuleInfo
家庭下设备信息列表 BLFamilyDeviceInfo
家庭下子设备信息列表 BLFamilyDeviceInfo

2.1.1 家庭自身基本信息 BLFamilyInfo

家庭自身的基本信息 BLFamilyInfo 包含有以下属性：

public class BLFamilyInfo {
    private String familyId;            //家庭ID
    private String familyVersion;       //家庭版本信息
    private String familyIconPath;      //家庭Icon路径
    private String familyName;          //家庭名称
    private String familyDescription;   //家庭描述
    private String familyPostcode;      //家庭的邮编
    private String familyMailaddress;   //家庭的邮寄地址
    private String familyCountry;       //家庭所在国家
    private String familyProvince;      //家庭所在省份
    private String familyCity;          //家庭所在城市
    private String familyArea;          //家庭所在城区
    private int familyLimit;            //家庭的访问权限
    private int familyLongitude;        //家庭所在维度
    private int familyLatitude;         //家庭所在经度
    private int familyOrder;            //家庭序号
}

注意：

家庭在云端创建之后，云端会分配一个该账户下的唯一家庭ID —— familyId
家庭信息在云端的每一次修改之后，云端都会给该家庭一个新的版本号 ——familyVersion
如果家庭创建的时候上传了家庭头像，云端则会给该家庭头像创建相应的头像路径—— familyIconPath
其它信息开发者可以在创建家庭的时候上报到云端，或者后续通过对应的修改接口进行修改。

2.1.2 查询账户下家庭ID列表

同一个账户下的用户可以创建多个家庭，也可以加入到多个家庭中，所以使用家庭功能时，需要查询该账户下所有家庭的 familyId 列表，根据需要选择家庭进行后续操作。

public static BLFamilyIdListGetResult queryLoginUserFamilyIdList();

返回参数

BLFamilyIdListGetResult 说明

参数名称	参数类型	备注
idInfoList	List	家庭ID信息列表 BLFamilyIdInfo

BLFamilyIdInfo 说明

参数名称	参数类型	备注
shareFlag	int	是否是分享来的家庭
familyId	String	家庭ID
familyVersion	String	家庭版本
familyName	String	家庭名称

2.1.3 获取指定家庭全部信息

public static BLAllFamilyInfoResult queryAllFamilyInfos(String[] ids);

通过该接口获取指定家庭的详细信息，可以得到一个家庭的全部信息 BLFamilyAllInfo ，这些信息包含有：

家庭自身的基本信息 BLFamilyInfo
家庭下房间信息列表 BLRoomInfo
家庭下模块信息列表 BLModuleInfo
家庭下设备信息列表 BLFamilyDeviceInfo
家庭下子设备信息列表 BLFamilyDeviceInfo

2.1.4 创建默认家庭

使用该接口可以给登录用户创建一个默认家庭，包含有家庭的基本信息以及默认创建的房间信息列表。

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

请求参数

参数名称	参数类型	备注
name	String	默认家庭名称，若为空，则采用默认名称
country	String	家庭所在国家，可以为空
province	String	家庭所在省份，可以为空
city	String	家庭所在城市，可以为空

返回参数

BLFamilyInfoResult 说明

参数名称	参数类型	备注
familyInfo	BLFamilyInfo	创建的家庭信息
roomInfos	List	默认创建的房间信息列表

2.1.5 修改家庭信息

使用该接口可以修改家庭信息，除 familyId，familyVersion 外。

public static BLFamilyInfoResult modifyFamilyInfo(BLFamilyInfo familyInfo);

请求参数

参数名称	参数类型	备注
familyInfo	BLFamilyInfo	需要修改的家庭信息

返回参数

见 BLFamilyInfoResult 说明

2.1.6 修改家庭Icon

使用该接口可以修改家庭的ICON，上传图片到家庭后台。

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

请求参数

参数名称	参数类型	备注
familyInfo	BLFamilyInfo	当前的家庭信息
icon	File	需要修改的家庭ICON文件

返回参数

见 BLFamilyInfoResult 说明

2.1.7 删除家庭

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

请求参数

参数名称	参数类型	备注
familyId	String	需要删除的家庭ID
familyVersion	String	家庭当前版本

2.2 房间相关接口

2.2.1 房间基本 BLRoomInfo

房间基本信息 BLRoomInfo 包含有以下属性：

public class BLFamilyRoomInfo {
    private String familyId;        //房间所在家庭的ID
    private String roomId;          //房间自身ID
    private String name;            //房间名称
    private int type;               //房间类型
    private int order;              //房间序号

    private String action;          //房间执行操作 add,modify,del
}

家庭下面可以创建多个房间，同时也可以对房间进行修改、删除等操作。

2.2.2 房间基本操作接口

房间在创建的时候，指定了对应的家庭ID —— familyId 房间在创建之后，云端会分配给房间相应的唯一ID —— roomId 房间管理接口支持在同一时间对不同的房间进行增、删、改的操作，主要根据房间信息 BLRoomInfo 的相关属性 action 来进行不同的操作。

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

请求参数

参数名称	参数类型	备注
familyId	String	当前的家庭ID
familyVersion	String	当前的家庭版本
roomInfos	List	需要操作的房间列表，支持对多个房间一起操作

返回参数

BLManageRoomResult 说明

参数名称	参数类型	备注
familyId	String	当前的家庭ID
familyVersion	String	当前的家庭版本

2.3 家庭模块相关接口

家庭模块是家庭控制的基本单元，通过对模块的操作，可以实现在家庭环境下控制单个设备、多个设备、场景以及自定义模版的实现。

2.3.1 模块基本 BLModuleInfo

public class BLFamilyModuleInfo {
    private String familyId;                            //模块所在家庭ID
    private String roomId;                              //模块所在房间ID
    private String moduleId;                            //模块自身ID
    private String name;                                //模块名称
    private String iconPath;                            //模块icon路径
    private List<ModuleDeviceInfo> moduleDevs;          //模块下挂设备列表
    private int followDev;                              //模块移动时，设备是否跟随 0-NO 1-YES
    private int order;                                  //模块序号
    private int flag;                                   //模块Flag
    private int moduleType;                             //模块类型
    private String scenceType;                          //场景类型
    private String extend;                              //模块扩展信息，由用户自定义
}

注意：

模块在创建的时候，指定了对应的家庭ID —— familyId
模块在创建之后，云端会分配给模块相应的唯一ID —— moduleId
模块在创建的时候，指定了对应的设备／子设备，相关的设备信息存储在 moduleDevs
模块在创建的时候，指定了对应模块的类型 —— moduleType
模块所在的房间是不固定的，模块可以移动到指定的房间ID —— roomId
模块移动之后，可以指定设备是否跟随一起移动 —— followDev

模块下设备列表 ModuleDeviceInfo 包含以下内容：

public static class ModuleDeviceInfo{
    private String did;                     //设备Did
    private String sdid;                    //若为子设备，则包含该子设备did
    private int order;                      //序号
    private String content;                 //设备相关扩展内容，由用户自定义
}

模块类型 moduleType 定义如下：

public class BLModuleType {
    public static final int Scene = 0;
    public static final int Sp = 1;                     //SP插座系列
    public static final int PowerConsumption = 2;       //能耗统计
    public static final int Common = 3;                 //通用模块（除了其他几种外的模块类型，主要用于识别从dnakit系统绑定的设备）
    public static final int ControlCenter = 4;
    public static final int Customize_Scene = 5;        //自定义场景
    public static final int HK_SP = 6;                  //homekitSP系列

    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 模块，不包含频道信息
    public static final int RM_TOPBOX = 12;             //RM 机顶盒 模块，不包含频道信息
    public static final int RM_NETWORK_BOX = 13;        //RM 网络盒子 模块
    public static final int RM_TOPBOX_CHANNEL = 14;     //RM topbox 频道模块
    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 新电视模块 包含频道信息
    public static final int RM_NEW_TOPBOX = 25;         // RM 新机顶盒模块 包含频道信息

    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 添加模块

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

请求参数

参数名称	参数类型	备注
moduleInfo	BLFamilyModuleInfo	需要添加的模块信息
familyInfo	BLFamilyInfo	添加到的家庭基本信息
deviceInfo	BLFamilyDeviceInfo	如果模块 ModuleDeviceInfo 对应的设备都详细信息
subDeviceInfo	BLFamilyDeviceInfo	同 deviceInfo

返回参数

BLModuleControlResult 说明

参数名称	参数类型	备注
moduleId	String	模块的ID
version	String	当前的家庭版本

2.3.3 删除模块

第一步：删除设备

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

请求参数

参数名称	参数类型	备注
did	String	设备唯一ID
familyId	String	当前的家庭ID
familyVersion	String	当前的家庭版本

第二步：删除模块信息

注意：
如果该模块只包含设备信息，则在第一步中会自动删除该模块，无须再调用此步骤。

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

请求参数

参数名称	参数类型	备注
moduleId	String	模块的ID
familyId	String	当前的家庭ID
familyVersion	String	当前的家庭版本

2.3.4 修改模块信息

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

请求参数

参数名称	参数类型	备注
moduleInfo	BLFamilyModuleInfo	需要修改的模块信息
familyId	String	当前的家庭ID
familyVersion	String	当前的家庭版本

2.3.5 模块移动所在房间

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

请求参数

参数名称	参数类型	备注
moduleId	String	模块的ID
roomId	String	移动到的房间ID
familyId	String	当前的家庭ID
familyVersion	String	当前的家庭版本

2.3.6 修改模块信息，且移动所在房间

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

请求参数

参数名称	参数类型	备注
moduleInfo	BLFamilyModuleInfo	需要修改的模块信息
roomId	String	移动到的房间ID
familyId	String	当前的家庭ID
familyVersion	String	当前的家庭版本