Home Information Management

Last Updated on : 2024-08-30 03:27:57download

This topic describes how to implement the features of home management using APIs. These APIs allow you to create, modify, and delete a home, manage devices in a home, sort groups, and register listeners for receiving home-based event callbacks.

Feature description

FamilyManagerCoreKit.getFamilyUseCase() is used for home management to implement operations on a home.

Home information is described with FamilyBean. The properties used by FamilyBean are described below:

Property	Type	Description
homeId	Long	The home ID.
familyName	String	The name of a home.
address	String	The geographical location of a home.
lon	Double	The longitude.
lat	Double	The latitude.
locationCity	String	The location of the city where the home is located.
familyStatus	Integer	The status of the invitation to join a home. Valid values: `1`: Pending acceptance (`HomeStatus.WAITING`) `2`: Accepted (`HomeStatus.ACCEPT`) `3`: Declined (`HomeStatus.REJECT`)
rooms	List	A list of all rooms.

The properties used by TRoomBean are described below:

Property	Type	Description
roomId	long	The room ID.
name	String	The name of the room.
ids	List	The list of devices in a room.

The properties used by DeviceInRoomBean are described below:

Property	Type	Description
id	String	The device ID.
type	Integer	Device type `BizParentTypeEnum`: `5`: Group (`BizParentTypeEnum.GROUP`) `6`: Device (`BizParentTypeEnum.DEVICE`)
name	String	The name of the device.
roomName	String	The name of the room that a device belongs to.
iconUrl	String	The URL of the device icon.
displayOrder	Integer	The sort ID of the room that a device belongs to.

API list

Create a default home

Create a default home with only a home ID and name, without location and room details.

API description

void createDefaultFamily(String defaultName,
                         IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

Parameter description

Property	Type	Description
defaultName	String	The name of a home, with up to 25 characters. The value cannot be empty.
callback	FamilyDataCallback<BizResponseData>	Callback for the result of the query.

Example

FamilyManagerCoreKit.getFamilyUseCase().createDefaultFamily("My Home",object :
        IFamilyDataCallback<BizResponseData<FamilyBean>>{
        override fun onSuccess(result: BizResponseData<FamilyBean>?) {
            // return result on success.
            val familybean = result?.data
        }

        override fun onError(errcode: String?, errMsg: String?) {

        }
    })

Create a home

The user creates a home with the necessary information, including home name, room, and location.

API description

void createFamily(CreateFamilyRequestBean requestBean,
       IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

Parameter description

Parameters	Type	Description
requestBean	CreateFamilyRequestBean	The request model to create a home.
callback	IFamilyDataCallback<BizResponseData>	Callback for the result of the query.

CreateFamilyRequestBean parameter description

Parameters	Type	Description
familyName	String	The name of a home, with up to 25 characters. The value cannot be empty.
lon	Double	The longitude of a home. If the geographical location of the home is not required, set the value to 0.
lat	Double	The latitude of a home. If the geographical location of the home is not required, set the value to 0.
address	String	The geographical location of a home, defaulting to null.
rooms	List	The list of rooms, defaulting to null.

Example

val family = CreateFamilyRequestBean("My home...", 0d,0d,"",arrayListOf("Living room"," bedroom"))
FamilyManagerCoreKit.getFamilyUseCase().createFamily(family,object :
            IFamilyDataCallback<BizResponseData<FamilyBean>>{
            override fun onSuccess(result: BizResponseData<FamilyBean>?) {
                    val familybean = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Join a home

Join a home with an invitation code.

API description

void joinFamily(String inviteCode,
                IFamilyDataCallback<Boolean> callback);

Parameter description

Parameters	Type	Description
inviteCode	String	The invitation code, only letters and numbers allowed, with no spaces.
callback	IFamilyDataCallback	Callback for the result of the query.

Example

FamilyManagerCoreKit.getFamilyUseCase().joinFamily("HJFGHSH",object :IFamilyDataCallback<BizResponseData<Any>>{
            override fun onSuccess(p0: BizResponseData<Any>?) {
               //successful
            }

            override fun onError(p0: String?, p1: String?) {

            }
        })

Query home information

API description

void getFamilyDetail(long homeId,
                     IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

Parameter description

Parameters	Type	Description
homeId	long	The home ID.
callback	IFamilyDataCallback<BizResponseData>	Callback for the result of the query.

Example

//simulate a homeId: 7812934L
FamilyManagerCoreKit.getFamilyUseCase().getFamilyDetail(7812934L,object :
            IFamilyDataCallback<BizResponseData<FamilyBean>>{
            override fun onSuccess(result: BizResponseData<FamilyBean>?) {
                            //return result on success.
                         val familybean = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Get the current home

Get the current default home. If no current home is set, the first home in the list of homes is taken as the current home. If a current home has been set, the information about the last set home is returned.

For more information about setting the current home, see shiftCurrentFamily.

API description

void getCurrentDefaultFamilyDetail(IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

Parameter description

Parameters	Type	Description
callback	IFamilyDataCallback<BizResponseData>	Callback for the result of the query. If the home data has been cached on the local device and this home exists under the account, the cached data model is returned. If there’s no cache, the first home in the list of homes is returned. If an error occurs, the cached data is returned. With no cache, `onError()` is called back.

Example

FamilyManagerCoreKit.getFamilyUseCase().getCurrentDefaultFamilyDetail(object :
            IFamilyDataCallback<BizResponseData<FamilyBean>>{
            override fun onSuccess(result: BizResponseData<FamilyBean>?) {
                  // return result on success
                val familybean = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Set the current home

Set the current home and cache the home data on the local device. The next time the app is opened, the cache will be loaded.

API description

void shiftCurrentFamily(long homeId,IFamilyDataCallback<Boolean> callback);

Parameter description

Parameters	Type	Description
homeId	long	The ID of the current home.
callback	IFamilyDataCallback	Callback for the result of the query.

Example

// Only used to set the cache for the current home ID. Error is returned for an invalid home ID.
FamilyManagerCoreKit.getFamilyUseCase().shiftCurrentFamily(homeId, object :IFamilyDataCallback<Boolean>{
            override fun onSuccess(success: Boolean?) {
                //success: Is the setting successful?
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Query the cached home data

API description

FamilyBean getDefaultFamilyBean(long homeId);

Parameter description

Parameters	Type	Description
homeId	long	The home ID.
return	FamilyBean	The result of the query.

Example

val cacheFamilyBean = FamilyManagerCoreKit.getFamilyUseCase().getDefaultFamilyBean(homeId)

Query weather information

Query the weather overview of the city where the home is located. The weather data includes weather conditions, such as sunny, cloudy, or rainy, and weather icons.

API description

void getHomeWeather(double lon, double lat,
                     IFamilyDataCallback<WeatherBean> callback);

Parameter description

Parameters	Type	Description
lon	Double	The longitude.
lat	Double	The latitude.
callback	IFamilyDataCallback	Callback for the result of the query.

Example

FamilyManagerCoreKit.getFamilyUseCase().getHomeWeather(120.0,120.0,object:IFamilyDataCallback<WeatherBean>{
            override fun onSuccess(city: WeatherBean?) {

            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Query the city of home

API description

void getCityByLatLon(double lon, double lat,
                      IFamilyDataCallback<LocationCityBean\> listener);

Parameter description

Parameters	Type	Description
lon	Double	The longitude.
lat	Double	The latitude.
callback	IFamilyDataCallback	Callback for the result of the query.

Example

FamilyManagerCoreKit.getFamilyUseCase().getCityByLatLon(120.0,120.0,object:IFamilyDataCallback<LocationCityBean>{
            override fun onSuccess(city: LocationCityBean?) {

            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Query the list of homes

Query the list of all homes under the current account.

API description

void getFamilyList(IFamilyDataCallback<BizResponseData<List<FamilyBean>>> callback);

Parameter description

Parameters	Type	Description
callback	IFamilyDataCallback<BizResponseData<List>>	Callback for the result of the query.

Example

  FamilyManagerCoreKit.getFamilyUseCase().getFamilyList(object :
            IFamilyDataCallback<BizResponseData<List<FamilyBean>>>{
            override fun onSuccess(result: BizResponseData<List<FamilyBean>>?) {
                val familyList = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Update home information

Complete or modify the home information, such as home name and location.

API description

void updateFamily(long homeId, CreateFamilyRequestBean requestBean,
                  IFamilyDataCallback<BizResponseData<FamilyBean>> callback);

Parameter description

Parameters	Type	Description
homeId	long	The home ID.
family	CreateFamilyRequestBean	The request model to create a home.
callback	IFamilyDataCallback<BizResponseData>	Callback for the result of the query.

Example

val family = CreateFamilyRequestBean("my home", 0d, 0d, "",arrayListOf("room1", "room2"))
FamilyManagerCoreKit.getFamilyUseCase().updateFamily(homeId, family, object :
            IFamilyDataCallback<BizResponseData<FamilyBean>>{
            override fun onSuccess(result: BizResponseData<FamilyBean>?) {
                   //return result on success.
                    val familybean = result?.data
            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Sort devices and groups in a home

Sort the devices and groups in a home.

API description

void sortDeviceAndGroupInHome(String homeId, List<DeviceAndGroupInHomeBean> list,
                              IFamilyDataCallback<Boolean> callback);

Parameter description

Parameters	Type	Description
homeId	long	The home ID.
devList	List	The list of sorted devices and groups.
callback	IFamilyDataCallback	Callback for the result of the query.

The properties used by DeviceAndGroupInHomeBean are described below:

Parameters	Type	Description
bizId	String	The ID of the device or group.
bizType	Integer	Device type `BizParentTypeEnum`: `5`: Group (`BizParentTypeEnum.GROUP`) `6`: Device (`BizParentTypeEnum.DEVICE`)

Example

val devList = arrayListOf<DeviceAndGroupInHomeBean>()
        devList.add(DeviceAndGroupInHomeBean().apply {
            bizId = "xxxxxxxxx01"
            bizType = BizParentTypeEnum.GROUP.type
        })
        devList.add(DeviceAndGroupInHomeBean().apply {
            bizId = "xxxxxxxxx02"
            bizType = BizParentTypeEnum.DEVICE.type
        })
//The default sorting for the settings is according to the devList order.

FamilyManagerCoreKit.getFamilyUseCase().sortDeviceAndGroupInHome(homeId,devList,object :
            IFamilyDataCallback<Boolean>{
            override fun onSuccess(result: Boolean) {

            }

            override fun onError(errcode: String?, errMsg: String?) {

            }
        })

Delete a home

A home owner can delete a home that has no member.
However, a home cannot be deleted if it has a member.

API description

void dismissFamily(long homeId, IFamilyDataCallback<Boolean> callback);

Parameter description

Parameters	Type	Description
homeId	long	The home ID.
callback	IFamilyDataCallback	Callback for the result of the query.

Example

   FamilyManagerCoreKit.getFamilyUseCase().dismissFamily(homeId,object :IFamilyDataCallback<BizResponseData<Any>>{
            override fun onSuccess(p0: BizResponseData<Any>?) {
               //successful
            }

            override fun onError(p0: String?, p1: String?) {

            }
        })

Leave a home

A home owner or common member can leave a home. A home owner should transfer their role before leaving a home.

API description

void leaveFamily(long homeId, long memberId,
                  IFamilyDataCallback<Boolean> callback);

Parameter description

Parameters	Type	Description
homeId	long	The home ID.
memberId	long	The ID of a home member. For more information about getting the value, see Home Member Management.
callback	IFamilyDataCallback	Callback for the result of the query.

Example

FamilyManagerCoreKit.getFamilyUseCase().leaveFamily(homeId,memberId,object :IFamilyDataCallback<BizResponseData<Any>>{
            override fun onSuccess(p0: BizResponseData<Any>?) {
                 //successful
            }

            override fun onError(p0: String?, p1: String?) {

            }
        })

Hide a device

Access the method in the Home SDK through PluginManager.service(IThingHomePlugin::class.java).newHomeInstance(homeId). Here are the properties of DeviceAndGroupInHomeBean for hiding devices.

Property	Type	Description
bizId	String	The home ID.
bizType	int	Type Device: `BizParentTypeEnum.DEVICE` Group: `BizParentTypeEnum.GROUP`

Get the list of hidden devices

Get the list of all hidden devices in a home.

API description

 void queryHidedDeviceGroupList(IThingResultCallback<ArrayList<DeviceAndGroupInHomeBean>> callback);

Parameters

Parameter	Type	Description
callback	IResponse<ArrayList>	The callback.

Example

 val homePlugin  =   PluginManager.service(IThingHomePlugin::class.java)
 homePlugin.newHomeInstance(homeId).queryHidedDeviceGroupList(object: IThingResultCallback<java.util.ArrayList<DeviceAndGroupInHomeBean>>{
        override fun onSuccess(result: java.util.ArrayList<DeviceAndGroupInHomeBean>?) {
        }

        override fun onError(errorCode: String?, errorMessage: String?) {

        }
    })

Hide a device list

Hide a list of devices.

API description

 void hideDeviceGroup(List<DeviceAndGroupInHomeBean> devIds, IThingResultCallback<Boolean> callback);

Parameters

Parameter	Type	Description
devIds	List	The list of devices to be hidden.
callback	IResponse	The callback.

Example

 val homePlugin  =   PluginManager.service(IThingHomePlugin::class.java)
 homePlugin.newHomeInstance(homeId).hideDeviceGroup(listof("devid1","devid2"))(object: IThingResultCallback<Boolean>{
        override fun onSuccess(result: Boolean) {
        }

        override fun onError(errorCode: String?, errorMessage: String?) {

        }
    })

Show a hidden device list

Show a list of hidden devices.

API description

  void showDeviceGroup(List<DeviceAndGroupInHomeBean> devIds, IThingResultCallback<Boolean> callback);

Parameters

Parameter	Type	Description
devIds	List	The list of hidden devices to be shown.
callback	IResponse	The callback.

Example

val homePlugin  =   PluginManager.service(IThingHomePlugin::class.java)
 homePlugin.newHomeInstance(homeId).showDeviceGroup(listof("devid1"))(object: IThingResultCallback<Boolean>{
        override fun onSuccess(result: Boolean) {
        }

        override fun onError(errorCode: String?, errorMessage: String?) {

        }
    })

Event callback

Listen for changes to a home

API description

Register FamilyChangeListener to get notified when the user adds or deletes a home, receives an invitation to join a home, updates home information, switches between homes, adds or deletes a shared device, adds or deletes a shared group, and the MQTT service succeeds.

public interface FamilyChangeListener {
/**
     * Family added successfully.
     * <p>Used for multi-device data synchronization.</p>
     *
     * @param homeId The ID of the family which added.
     */
    void onFamilyAdded(long homeId);

    /**
     * Family invitation.
     *
     * @param homeId   The ID of the family that you are invited to.
     * @param homeName The name of the family that you are invited to.
     */
    void onFamilyInvite(long homeId, String homeName);

    /**
     * Family deleted successfully.
     * <p>Used for multi-device data synchronization.</p>
     *
     * @param homeId The ID of the family which removed.
     * @param isBySelfRemoved is removed family by self
     */
    void onFamilyRemoved(long homeId, boolean isBySelfRemoved);

    /**
     * Family information changed.
     * <p>Used for multi-device data synchronization.</p>
     *
     * @param homeId The ID of the family which information that changed.
     */
    void onFamilyInfoChanged(long homeId);

    /**
     * Current family ID, family name. If familyId is NONE_FAMILY_ID, it means there is no family and you need to jump to the page to create a family.
     *
     * @param familyId
     * @param familyName
     */
    void onFamilyShift(long familyId, String familyName);

    /**
     * Shared device list changes.
     * Used for multi-device data synchronization.
     * @param sharedDeviceList The list of shared devices.
     */
    void onSharedDeviceList(List<DeviceBean> sharedDeviceList);

    /**
     * Shared group list changes.
     * Used for multi-group data synchronization.
     * @param sharedGroupList The list of groups shared.
     */
    void onSharedGroupList(List<GroupBean> sharedGroupList);

    /**
     * The mobile phone successfully connects to the Thing Cloud server and receives this notification.
     * Local data and server data may be inconsistent or the device cannot be controlled,
     * You can call the getHomeDetail interface under Home to reinitialize the data.
     */
    void onServerConnectSuccess();
}

Example

val listener = object :FamilyChangeListener{
            override fun onFamilyAdded(homeId: Long) {

            }

            override fun onFamilyInvite(homeId: Long, homeName: String?) {

            }

            override fun onFamilyRemoved(homeId: Long, isBySelfRemoved: Boolean) {

            }

            override fun onFamilyInfoChanged(homeId: Long) {

            }

            override fun onFamilyShift(familyId: Long, familyName: String?) {

            }

            override fun onSharedDeviceList(sharedDeviceList: MutableList<DeviceBean>?) {

            }

            override fun onSharedGroupList(sharedGroupList: MutableList<GroupBean>?) {

            }

            override fun onServerConnectSuccess() {

            }
        }
//Register FamilyChange listener
FamilyManagerCoreKit.registerFamilyChangeListener(listener)

//Unregister FamilyChange listener
FamilyManagerCoreKit.unregisterFamilyChangeListener(listener)

Listen for changes to a device

API description

Register IThingHomeStatusListener to get notified when the user adds or removes a device, and adds or dismisses a group.

public interface IThingHomeStatusListener {

    /**
     * Device add successfully.
     *
     * @param devId The ID of the device which added.
     */
    void onDeviceAdded(String devId);

    /**
     * Device deleted successfully.
     *
     * @param devId The ID of the device which removed.
     */
    void onDeviceRemoved(String devId);

    /**
     * Group added successfully.
     *
     * @param groupId The ID of the group added.
     */
    void onGroupAdded(long groupId);

    /**
     * Group deleted successfully.
     *
     * @param groupId The ID of the group removed.
     */
    void onGroupRemoved(long groupId);

    /**
     * Blue mesh added successfully.
     *
     * @param meshId The ID of the mesh added.
     */
    void onMeshAdded(String meshId);
}

Example

val listener = object :IThingHomeStatusListener{
            override fun onDeviceAdded(devId: String?) {

            }

            override fun onDeviceRemoved(devId: String?) {

            }

            override fun onGroupAdded(groupId: Long) {

            }

            override fun onGroupRemoved(groupId: Long) {

            }

            override fun onMeshAdded(meshId: String?) {

            }
        }
//Register HomeStatus listener
FamilyManagerCoreKit.registerHomeStatusListener(0,listener)
//unregister HomeStatus listener
FamilyManagerCoreKit.unregisterHomeStatusListener(0,listener)

Prev DocHome Management

Next DocHome Member Management