Navigation :

APPSDK 家庭管理系统说明 V2

API概览

整体框图

名称	描述
家庭查询ID列表	Family.getList
家庭获取信息	Family.getInfo
家庭添加	Family.add
家庭修改	Family.update
家庭修改图标	Family.updadteIcon
家庭删除	Family.delete
家庭获得QR码	Family.getQrCode
家庭根据QR码获得基本信息	Family.getInfoByQrCode
家庭通过QR码加入家庭	Family.joinByQrCode
房间获得列表	Room.getList
房间管理	Room.manage
成员获得列表	Member.getList
管理员移除成员	Member.delete
成员主动退出家庭	Member.quit
转让管理员角色	Member.transferAdmin
销毁账号下所有家庭	Member.destroyAllFamily
终端获得列表	Endpoint.getList
终端获得用户下终端列表	Endpoint.getListByUser
终端添加	Endpoint.add
终端删除	Endpoint.delete
终端修改参数	Endpoint.update
终端修改属性	Endpoint.updateAttrs
场景获得列表	Scene.getList
场景添加	Scene.add
场景删除	Scene.delete
场景修改参数	Scene.update
场景修改属性	Scene.updateAttrs
联动获得列表	Linkage.getList
联动添加	Linkage.add
联动删除	Linkage.delete
联动修改	Linkage.update

1. 概述

BroadLink提供了一套完整的家庭管理系统。通过该系统，开发者可以很好的将 *家庭*，房间，*成员*，终端, 场景, *联动*的概念结合起来，构造出一套完整的智能硬件控制系统。

云端文档

家庭

*家庭*支持增删改查，以及成员的邀请和退出。家庭信息的每一次更新，都会产生新的家庭版本，在后续的部分接口中，需要指定该家庭版本。

房间

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

成员

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

终端

终端是对设备的包装，内包含所在房间的ID，自身的ID和类型等。终端支持增删改查，及属性的修改。

场景

*场景*用于组合多个终端按照先后顺序控制它们，例如起床的场景，先打开窗帘，再开灯，打开电视播放新闻等。场景支持增删改查，及属性的修改。

联动

*联动*用于当达到某个条件时触发某些场景或者操作某些终端。联动支持增删改查。

2. API 接口介绍

库集成，在项目的build.gradle中添加：

implementation 'com.ibroadlink:BLSFamilyAndroid:1.0.+'

初始化，在Application中BLLet.init()获得lid后，初始化BLSFamily，注册用户登录回调。

  // BLLet初始化
  BLLet.init(this, license, "", blConfigParam);
  
  // 初始化之后，获取lid
  String lid = BLLet.getLicenseId();
  
  // 初始化家庭管理接口, 如果使用集群服务，domain填null即可
  BLSFamily.init(lid, domain);
  
  // 添加登录成功回调函数
  BLAccount.addLoginListener(BLSFamily.getLoginListener());

初始化方法

    /**
     * 初始化
     * 
     * @param licenseId 证书
     * @param domain    域名（可传空，默认使用appservice）
     * @param httpTimeout http请求超时时间，默认10秒
     * @return 实例
     */
    public BLSFamilyImpl init(String licenseId, String domain, int httpTimeout)
        
     /**
     * 初始化
     * 
     * @param licenseId 证书
     * @param domain    域名（可传空，默认使用appservice）
     * @return 实例
     */
    public BLSFamilyImpl init(String licenseId, String domain)

2.1 家庭相关接口

2.1.1 家庭信息 BLFamilyInfo

public class BLSFamilyInfo {
    private String familyId;          //家庭ID
    private String name;          	  //家庭名称
    private String version;           //家庭版本信息
    private String iconpath;          //家庭Icon路径
    private String description;   	  //家庭描述
    private String countryCode;       //家庭所在国家
    private String provinceCode;      //家庭所在省份
    private String cityCode;          //家庭所在城市
    private String createUser;   	  //家庭创建者
    private String master;            //家庭管理员
}

家庭属性 BLSFamilyAddOrUpdateParams

 public class BLSFamilyAddOrUpdateParams implements Parcelable {

    private String name;          	  //家庭名称
    private String description;   	  //家庭描述
    private String countryCode;       //家庭所在国家
    private String provinceCode;      //家庭所在省份
    private String cityCode;          //家庭所在城市
    private int familylimit = 1;	  //权限，默认管理员
｝

注意：

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

2.1.2 家庭查询ID列表

一个账户下的用户可以创建多个家庭，也可以加入到多个家庭中，所以使用家庭功能时，需要查询该账户下所有家庭的 familyId 列表，根据需要选择家庭进行后续操作。开发者可以根据返回回来的 familyId 和 version，与自身存储的家庭信息比较，是否存在更新，是否需要获取家庭全部信息。

/**
  * @return 家庭列表
  */
public static BLSBaseDataResult<BLSFamilyListData> Family.getList()

2.1.3 家庭获取信息

   /**
   * 查询家庭信息
   * 
   * @param familyId: 家庭ID 
   * @return 家庭信息
   */
public static BLSBaseDataResult<BLSFamilyInfoData> Family.getInfo(String familyId)

返回参数

参数名称	参数类型	备注
familyInfo	BLSFamilyInfo	家庭信息

2.1.4 家庭添加

  /**
  * 添加家庭
  *
  * @param addParam  家庭信息
  * @return 家庭信息
  */
 public static BLSBaseDataResult<BLSFamilyAddData> Family.add(BLSFamilyAddOrUpdateParams addParam)

请求参数

参数名称	参数类型	备注
addParam	BLSFamilyAddOrUpdateParams	家庭参数

返回参数

 public class BLSFamilyAddData implements Parcelable {
    
    private String familyid;			//家庭ID
    private String name;				//家庭名称
    private String iconpath;			//图标
    private List<BLSRoomInfo> roominfo;  //房间列表
｝

2.1.5 家庭更新

    /**
    * 更新家庭信息
    *
    * @param updateParam 家庭信息
    * @return 家庭信息
    */
    public static BLSBaseDataResult Family.update(String familyId, BLSFamilyAddOrUpdateParams updateParam)

参数名称	参数类型	备注
addParam	BLSFamilyAddOrUpdateParams	家庭参数

2.1.6 家庭更新图标

    /**
    * 修改家庭图标
    *
    * @param familyId: 家庭ID
    * @param fileIcon 图标
    */
    public static BLSBaseDataResult<BLSFamilyIconData> Family.updadteIcon(String familyId, File fileIcon)

2.1.7 家庭删除

  /**
  * 删除家庭
  * 
  * @param familyId: 家庭ID
  */
 public static BLBaseResult Family.delete(String familyId)

2.1.8 家庭获得QR码

    /**
    * 生成QR码
    *
    * @param familyId: 家庭ID
    * @return QR码
    */
    public static BLSBaseDataResult<BLSFamilyQrData> Family.getQrCode(String familyId)

2.1.9 家庭通过QR码获得基本信息

    /**
    * 根据QR码获得家庭基本信息
    *
    * @param qrCode 二维码值
    * @return 家庭基本信息
    */
    public static BLSBaseDataResult<BLSFamilyInfo>  Family.getInfoByQrCode(String qrCode)

2.1.10 家庭通过QR码加入

    /**
    * 使用QR码加入家庭
    *
    * @param qrCode 二维码值
    * @return 家庭基本信息
    */
    public static BLSBaseDataResult<BLSFamilyJoinByQrData> Family.joinByQrCode(String qrCode)

2.2 房间相关接口

2.2.1 房间信息 BLSRoomInfo

   public class BLSRoomInfo implements Parcelable {

    private String action;    	//动作
    private String roomid;	  	//房间ID
    private String name;		//房间名称
    private int order;			//排列顺序
    private int type;			//房间类型
    }

2.2.2 房间查询列表

    /**
    * 查询房间列表
    *
    * @return 家庭房间列表
    */
    public static BLSBaseDataResult<BLSRoomListData> Room.getList(String familyId)

2.2.3 房间查询列表

    /**
    * 管理房间列表
    *
    * @param roomInfos 房间列表
    * @return 房间列表
    */
    public static BLSBaseDataResult<BLSRoomManageData> Room.manage(String familyId, List<BLSRoomInfo> roomInfos)

参数名称	参数类型	备注
roomInfos	List	房间信息

2.3 成员相关接口

2.3.1 成员信息 BLSMemberInfo

   public class BLSMemberInfo implements Parcelable {

    private String userid;   	//用户ID
    private int type;	  		//用户类型   0-管理员 1-普通用户
    }

2.3.2 成员查询列表

    /**
    * 查询成员列表
    */
    public static BLSBaseDataResult<BLSMemberListData> Member.getList(String familyId)

返回参数

参数名称	参数类型	备注
familymember	List	成员信息

2.3.3 管理员移除成员

    /**
    * 移除成员
    *
    * @param familyMemberParam 成员列表
    */
    public static BLBaseResult delete(String familyId, BLSMemberDelParam familyMemberParam)

2.3.4 非管理员成员主动退出家庭

    /**
    * 退出家庭
    */
    public static BLBaseResult quit(String familyId)

2.3.5 转让管理员角色

     /**
     * 转让管理员
     *
     * @param newAdminUserId 新管理员的userid
     */
     public static BLBaseResult transferAdmin(String familyId, String newAdminUserId)

2.3.6 销毁账号下所有家庭

    /**
    * 销毁账号下所有家庭
    *
    */
    public static BLBaseResult destroyAllFamily(BLSVerifyCodeInfo param)

2.4 终端相关接口

2.4.1 终端信息 BLSEndpointInfo

  public class BLSEndpointInfo implements Parcelable {

    private String endpointId;		//设备ID
    private String friendlyName;	//名称
    private String mac;			    //mac地址
    private String gatewayId;		//网管ID
    private String productId;		//产品PID
    private String icon;			//图标
    private String roomId;			//房间ID
    private int order;				//排序ID
    private String userId;			//用户ID
    private String cookie;			//cookie
    private String irData;			//红码
    private String vGroup;			//分组
    private String extend;			//扩展字段
   }

2.4.2 终端查询列表

    /**
    * 查询家庭下的设备列表
    *
    */
    public static BLSBaseDataResult<BLSEndpointListData> Endpoint.getList(String familyId)

2.4.3 终端查询用户所有终端

      /**
      * 获取用户下设备列表
      *
      * @param queryShareFamily
      * @param queryPage 从第几个开始查询，与queryStep同时为0表示查询所有
      * @param queryStep 每次查几个，与queryPage同时为0表示查询所有
      */
      public static BLSBaseDataResult<BLSEndpointListPageData> getListByUser(boolean  queryShareFamily, int queryPage, int queryStep)

2.4.4 终端添加

    /**
    * 添加设备
    *
    * @param endPointList 设备列表
    */
    public static BLBaseResult Endpoint.add(String familyId, List<BLSEndpointInfo> endPointList)

*请求参数

参数名称	参数类型	备注
endPointList	List	终端信息

2.4.5 终端删除

    /**
    * 移除设备
    *
    * @param endpointId 设备ID
    */
    public static BLBaseResult Endpoint.delete(String familyId, String endpointId)

2.4.6 终端更新参数

    /**
    * 修改设备信息
    *
    * @param endpoint 设备
    */
    public static BLBaseResult Endpoint.update(String familyId, BLSEndpointInfo endpoint)

2.4.7 终端更新属性

    /**
    * 修改设备属性
    *
    * @param endpoints 包含待修改属性的设备列表
    */
    public static BLBaseResult Endpoint.updateAttrs(String familyId, List<BLSEndpointUpdateAttrParam> endpoints)

2.5 场景相关接口

2.5.1 场景信息 BLSSceneInfo

 public class BLSSceneInfo implements Parcelable {

    private String sceneId;				//场景ID
    private String friendlyName;		//名称
    private String icon;				//图标	
    private int order;					//排序ID
    private String familyId;			//家庭ID
    private String roomId;				//房间ID	
    private String extend;				//扩展字段
    private List<BLSSceneDevItemInfo> scenedev; //参数场景的设备信息
   }

参数场景的设备信息 BLSSceneDevItemInfo

 public class BLSSceneDevItemInfo implements Parcelable {
			
    private String sceneId;				//场景ID
    private String endpointId;			//设备ID
    private String gatewayId;			//网关ID
    private int order;					//排序ID	
    private String content;				//设备指令，JsonString
   }

设备指令 BLSSceneContentInfo

 public class BLSSceneContentInfo implements Parcelable {
  
    private String name;				//指令名称
    private int delay;					//延迟
    private String extend;				//扩展字段
    private List<BLStdData> cmdParamList; 	//指令内容
   }

2.5.2 场景查询

    /**
    * 查询家庭下的场景列表
    */
    public static BLSBaseDataResult<BLSSceneListData> Scene.getList(String familyId)

2.5.3 场景添加

    /**
    * 添加场景
    * @param addOrUpdateParam 场景内容
    */
    public static BLSBaseDataResult<BLSSceneIdData> Scene.add(String familyId, BLSSceneAddOrUpdateParam addOrUpdateParam)

2.5.4 场景删除

 
     /**
     * 删除场景
     * @param deleteParam 场景ID列表
     */
     public static BLSBaseDataResult Scene.delete(String familyId, BLSSceneDeleteParam deleteParam)

2.5.5 场景更新参数

 
     /**
     * 更新场景
     * @param addOrUpdateParam 场景内容
     */
     public static BLSBaseDataResult Scene.update(String familyId, BLSSceneAddOrUpdateParam addOrUpdateParam)

2.5.6 场景更新属性

 
     /**
     * 更新场景属性
     * @param attrUpdateParam 场景属性列表
     */
     public static BLSBaseDataResult Scene.updateAttrs(String familyId, BLSSceneAttrUpdateParam attrUpdateParam)

2.6 联动相关接口

2.5.1 联动信息 BLSSceneInfo

云端文档

 public class BLSLinkageInfo implements Parcelable {
    private String familyid;					//家庭ID
    private String rulename;					//联动名称
    private int ruletype = 		BLSFamilyConstants.LINKAGE_RULE_TYPE.RULE_TYPE_CHARACTERISTIC; //联动类型
    private String ruleid;						//联动ID
    private String teamid;						//teamid
    private int enable = 1;						//使能
    private int delay = 0;						//延迟
    private String characteristicinfo;			 //联动信息,触发源,JsonString,app透传
    private String locationinfo;				//位置信息,暂时填空
    private String source = BLSFamilyConstants.LINKAGE_SOURCE_TYPE.SOURCE_APP;  //触发类型
    private BLSLinkageDevListInfo linkagedevices;	 //参与联动的设备
    private List<String> sceneIds;					//参与联动的场景,如无场景联动，则填空列表[]
    private List<BLSLinkageSubscribeInfo> subscribe;  //订阅
   }

BLSLinkageSubscribeInfo

public class BLSLinkageSubscribeInfo implements Parcelable {
    private String ruleid;				//联动ID
    private String endpointId;			//设备ID
    private int didtype;				
   }

BLSLinkageDevListInfo

public class BLSLinkageDevListInfo implements Parcelable {
    private String name;					//名称
    private String extern;					//扩展字段
    private String linkagetype;				//联动类型
    private List<BLSLinkageDevInfo> devs;	//联动设备信息
   }

BLSLinkageDevInfo

public class BLSLinkageDevInfo implements Parcelable {
    rivate String endpointId;			//设备ID
    private String gatewayId;			//网关ID
    private int order;					//排序ID
    private String content;				//指令内容，JSONString
   }

2.6.2 联动查询

    /**
    * 查询联动列表
    */
    public static BLSBaseDataResult<BLSLinkageListData> Linkage.getList(String familyId)

2.6.3 联动添加

    /**
    * 添加联动
    * @param linkageInfo 联动内容
    */
    public static BLBaseResult Linkage.add(String familyId, BLSLinkageInfo linkageInfo)

2.6.4 联动删除

    /**
    * 删除联动
    * @param ruleId 联动id
    */
    public static BLBaseResult Linkage.delete(String familyId, String ruleId)

2.6.5 联动更新

    /**
    * 更新联动
    * @param linkageInfo 联动内容
    */
    public static BLBaseResult Linkage.update(String familyId, BLSLinkageInfo linkageInfo)