House Management

This topic describes the API methods for Android to get house information and manage houses on top of Smart Community PaaS. These API methods can be used to implement a bunch of features. For example, create houses, query a list of houses, listen for house information changes, query house details, query weather details of a house, transfer out of and delete a house, and sort devices and groups of a house.

Functional description

• Classes for house management

  Class name	Description
  ITuyaCommunityHouseManager	Provides the capabilities to add houses, get a list of houses, and listen for house information changes. TuyaCommunitySDK.getHouseManagerInstance() can be used to call the class.
  ITuyaCommunityHouse	Provides the capabilities to get house information and weather details of the house, and sort devices and groups in a house. TuyaCommunitySDK.newHouseInstance(houseId) can be used to call the class.

• Data types of TuyaCommunityHouseBean

  Property	Type	Description
  communityId	String	The community ID.
  communityName	String	The name of a community.
  houseAddress	String	The address of a house.
  houseId	Long	The house ID.
  houseName	String	The name of a house.
  admin	Boolean	Indicates whether a user is granted smart home permissions, including the owner’s or administrator’s permissions.
  auditStatus	Integer	The reviewing status of a house. Valid values of TuyaCommunityHouseAuditStatus: 0: pending review 20: approved 10: rejected 30: transferred out of a house
  guestHouse	Boolean	Specifies whether a house has a guest.
  userTypeName	String	The type of the current user.
  memberNum	Integer	The number of members in a house.
  roomUserId	String	The current user ID.
  roomId	String	The room ID.
  geoName	String	The geographical location of a house.
  longitude	Double	The longitude of the house.
  latitude	Double	The latitude of the house.
  dealStatus	Integer	The status of a member’s request to join a house. Valid values of TuyaCommunityMemberInviteStatus: 1: pending acceptance 2: accepted 3: rejected
  role	Integer	The role of a member. Valid values of TuyaCommunityMemberRole: -1: custom member. 0: house member. 1: administrator. 2: house owner. -999: invalid member. A member will become invalid in specific conditions.
  rooms	List<RoomBean>	A list of all rooms.
  deviceList	List<DeviceBean>	A list of all devices.
  groupList	List<GroupBean>	A list of all groups.
  meshList	List<BlueMeshBean>	A list of gateways.
  sharedDeviceList	List<DeviceBean>	A list of shared devices.
  sharedGroupList	List<GroupBean>	A list of shared groups.

Get a list of communities

Returns a list of communities. A house can be added only after a community is selected.

API description

void getCommunityList(@Nullable String keyword, double latitude, double longitude, ITuyaCommunityResultCallback<ArrayList<TuyaCommunityListBean>> callback);

Parameters

Parameter	Description
keyword	The name of a community. This parameter is optional and used to query a list of communities.
latitude	The latitude. This parameter is optional and used to display the surrounding communities.
longitude	The longitude. This parameter is optional and used to display the surrounding communities.
callback	The callback.

• Data types of TuyaCommunityListBean

  Property	Type	Description
  city	String	The city.
  hasLocation	Boolean	Indicates whether the location is included.
  list	List	A list of communities.

• Data types of TuyaCommunityBean

  Property	Type	Description
  communityName	String	The name of the community.
  communityId	String	The community ID.

Java example

TuyaCommunitySDK.getHouseManagerInstance().getCommunityList(
			keyword, lat, lon, new ITuyaCommunityResultCallback<ArrayList<TuyaCommunityListBean>>() {                    @Override
				public void onSuccess(ArrayList<TuyaCommunityListBean> tuyaCommunityListBeans) {
					// do something
					}
				}

				@Override
				public void onFailure(String s, String s1) {
					// do something
				}
			});

Get a house space tree

Returns a house space tree after a community is selected to add a house. Information about the building, unit, floor, and room ID is displayed by the space tree. The hasMore field in the response indicates whether subordinate spaces are available.

API description

void getCommunityHouseTreeList(String treeId, ITuyaCommunityResultCallback<ArrayList<TuyaCommunityHouseTreeBean>> callback);

Parameters

Parameter	Description
treeId	The space tree ID. To query a space tree for a specific community, communityId is required.
callback	The callback.

Data types of TuyaCommunityHouseTreeBean

Property	Type	Description
spaceTreeName	String	A space tree that includes information subordinate to a community, for example, Building 1 and Unit 1.
spaceTreeId	String	The node ID in a space tree including information subordinate to a community. The value of spaceTreeId for the bottom level is a room ID.
hasMore	Boolean	Indicates whether subordinate levels are included.

Java example

    TuyaCommunitySDK.getHouseManagerInstance().getCommunityHouseTreeList(treeId, new ITuyaCommunityResultCallback<ArrayList<TuyaCommunityHouseTreeBean>>() {
            @Override
            public void onSuccess(ArrayList<TuyaCommunityHouseTreeBean> tuyaCommunityHouseTreeBeans) {
                // do something
            }

            @Override
            public void onFailure(String s, String s1) {
                // do something
            }
        });

Add a house

API description

void addHouse(String name, String communityId, String roomId, String userType, @Nullable String expireTime, ITuyaCommunityResultCallback<TuyaCommunityHouseBean> callback);

Parameters

Parameter	Description
name	The details of a house, including the community, building, unit, floor, and room ID.
roomId	The room ID. This is the value of treeId for the bottom-level space specific to a house.
userType	The type of a user, such as an owner or member. You can call getMemberTypeList() of the class TuyaCommunityMember to get a list of user types.
expireTime	The expiration time. This parameter is optional and specifies the expiration time of a tenant user. Format: yyyyMMdd.
callback	The callback.

Java example

TuyaCommunitySDK.getHouseManagerInstance().addHouse(name, communityId,
                        roomId, userType, "", new ITuyaCommunityResultCallback<TuyaCommunityHouseBean>() {
                            @Override
                            public void onSuccess(TuyaCommunityHouseBean tuyaCommunityHouseBean) {
                                // do something

                            }

                            @Override
                            public void onFailure(String s, String s1) {
                                // do something
                            }
                        });

Get a list of houses

API description

void getHouseList(ITuyaCommunityResultCallback<ArrayList<TuyaCommunityHouseBean>> callback);

Parameters

Parameter	Description
callback	The callback.

Java example

TuyaCommunitySDK.getHouseManagerInstance().getHouseList(new ITuyaCommunityResultCallback<ArrayList<TuyaCommunityHouseBean>>() {
            @Override
            public void onSuccess(ArrayList<TuyaCommunityHouseBean> list) {
                // do something
            }

            @Override
            public void onFailure(String s, String s1) {
                // do something
            }
        });

Listen for changes in house information

Listens for changes in house information in specific events. For example, a house is added or deleted, the reviewing status is changed, and the server is connected.

API description

public interface ITuyaHouseChangeListener {
	/**
	* A house is added.
	* Data is synchronized between multiple devices.
	*
	* @param houseId
	*/
	void onHouseAdded(long houseId);
houseId	/**
	* The reviewing status of a house is changed.
	* @param houseId    The house ID.
	* @param audit  The reviewing status of a house. Valid values:<ul><li>`20`: approved.</li><li>`10`: rejected.</li><li>30`: transferred out of the house.
	*/
    void onHouseAuditStatusUpdate(long houseId, @TuyaCommunityHomeAuditStatus int audit);

	/**
	* The house is deleted.
	* Data is synchronized between multiple devices.
	*
	* @param houseId
	*/
	void onHouseRemoved(long houseId);

	/**
	* The list of shared devices is modified.
	* Data is synchronized between multiple devices.
	*
	* @param sharedDeviceList
	*/
	void onSharedDeviceList(List<DeviceBean> sharedDeviceList);

	/**
	* The list of shared groups is modified.
	* Data is synchronized between multiple groups.
	*
	* @param sharedGroupList
    */
    void onSharedGroupList(List<GroupBean> sharedGroupList);

	/**
	* Register a callback of the successful connection to the MQTT server
	* A notification is received to indicate that the mobile phone is connected to the Tuya Cloud.
	* On-premises data might be different from the data on the server, or the device might not be controlled.
	* In this case, you can call `getHomeDetail` for the house to initialize data.
	*/
	void onServerConnectSuccess();
}

Add a house listener

API description

void registerTuyaHouseChangeListener(ITuyaHouseChangeListener listener)

Parameters

Parameter	Description
listener	The listener.

Delete a house listener

API description

void unRegisterTuyaHouseChangeListener(ITuyaHouseChangeListener listener)

Parameters

Parameter	Description
listener	The listener.

Java example

// Defines the listener.
ITuyaHouseChangeListener listener = new ITuyaHouseChangeListener() {
		@Override
		public void onHouseAdded(long houseId) {
			// do something
		}
		@Override
		public void onHouseAuditStatusUpdate(long houseId, int audit) {
			// do something
		}
		@Override
		public void onHouseRemoved(long houseId) {
			// do something
		}
		@Override
		public void onSharedDeviceList(List<DeviceBean> sharedDeviceList) {
			// do something
		}
		@Override
		public void onSharedGroupList(List<GroupBean> sharedGroupList) {
			// do something
		}
		@Override
		public void onServerConnectSuccess() {
			// do something
		}
	};
// Registers a listener.
TuyaCommunitySDK.getHouseManagerInstance().registerTuyaHouseChangeListener(listener);
// ...
// Cancels a listener.
TuyaCommunitySDK.getHouseManagerInstance().unRegisterTuyaHouseChangeListener(listener);

Query house details

Returns the details of a house, such as the devices, groups, and rooms for the house.

API description

void getHouseDetail(ITuyaCommunityResultCallback<TuyaCommunityHouseBean> callback)

Parameters

Parameter	Description
callback	The callback.

Java example

TuyaCommunitySDK.newHouseInstance(houseId).getHouseDetail(new ITuyaCommunityResultCallback<TuyaCommunityHouseBean>() {
		@Override
		public void onSuccess(TuyaCommunityHouseBeanonFailure bean) {
			// do something
		}
		@Override
		public void onFailure(String errorCode, String errorMsg) {
			// do something
		}
	});

Query offline house details

Returns the details of an offline house, such as the devices, groups, and rooms for the house.

API description

void getHouseLocalCache(ITuyaHouseResultCallback callback)

Parameters

Parameter	Description
callback	The callback.

Java example

TuyaCommunitySDK.newHouseInstance(houseId).getHouseLocalCache(new ITuyaHouseResultCallback() {
		@Override
		public void onSuccess(HouseBean bean) {
			// do something
		}
		@Override
		public void onFailure(String errorCode, String errorMsg) {
			//sdk cache error do not deal
		}
	});

Query cached data of a house

TuyaCommunityHouseDataManager provides the capability to access cached data. The API method TuyaCommunitySDK.getDataInstance() is called to implement the feature.

Query basic information about a house

Returns basic information about a house, including the house name, location, reviewing status, and room information. Other details such as devices and groups are not returned.

API description

void getHouseInfo(long houseId, ITuyaCommunityResultCallback<TuyaCommunityHouseBean> callback);

Parameters

Parameter	Description
houseId	The house ID.
callback	The callback.

Example

    TuyaCommunitySDK.getHouseManagerInstance().getHouseInfo(houseId, new ITuyaCommunityResultCallback<TuyaCommunityHouseBean>() {
            @Override
            public void onSuccess(TuyaCommunityHouseBean houseBean) {
		// do something
            }

            @Override
            public void onFailure(String s, String s1) {
		// do something
            }
        });

Query the result of reviewing a house

Returns the reviewing status of a house.

API description

void getHouseAuditResult(String communityId, String roomUserId, ITuyaCommunityResultCallback<TuyaCommunityAuditHouseBean> callback);

Parameters

Parameter	Description
communityId	The community ID.
roomUserId	The ID of the mapping between a house and a user.
callback	The callback.

Example

    TuyaCommunitySDK.getHouseManagerInstance().getHouseAuditResult(communityId, roomUserId, new ITuyaCommunityResultCallback<TuyaCommunityAuditHouseBean>() {
            @Override
            public void onSuccess(TuyaCommunityAuditHouseBean tuyaCommunityAuditHouseBean){
                // do something
            }

            @Override
            public void onFailure(String s, String s1) {
		// do something
            }
        });

Change the house location

API description

void updateHouseLocation(double lon, double lat,String geoName, ISuccessFailureCallback callback);

Parameters

Parameter	Description
longitude	The longitude of the house.
latitude	The latitude of the house.
geoName	The geographical location of the house.
callback	The callback.

Example

    TuyaCommunitySDK.newHouseInstance(item.getHouseId()).updateHouseLocation(lon, lat, new ISuccessFailureCallback() {
                    @Override
                    public void onSuccess() {
			// do something
                    }

                    @Override
                    public void onFailure(String s, String s1) {
			// do something                    }
                });

Query house weather information

Query the weather overview for a house

API description

Returns the weather overview for the city where the house is located. The weather data includes weather conditions, such as sunny, cloudy, or rainy, and weather icons.

void getHouseWeatherSketch(double lon, double lat, ITuyaCommunityResultCallback<TuyaCommunityWeatherSketchBean> callback);

Parameters

Parameter	Description
lon	The longitude of the house.
lat	The latitude of the house.
callback	The callback.

Parameters of TuyaCommunityWeatherSketchBean

Parameter	Description
condition	The weather conditions, such as sunny, cloudy, and rainy.
temp	The temperature.
iconUrl	The URL of a weather icon.
inIconUrl	The URL of a weather details icon.

Java example

TuyaCommunitySDK.newHouseInstance(mHouseId).getHouseWeatherSketch(lon, lat, new ITuyaCommunityResultCallback<TuyaCommunityWeatherSketchBean>() {
	@Override
	public void onSuccess(TuyaCommunityWeatherSketchBean result) {
		// do something
	}
	@Override
	public void onFailure(String errorCode, String errorMsg) {
		// do something
	}
});

Query the weather details for a house

• Returns the weather details for the city where the house is located. Multiple weather data is returned, such as the temperature, humidity, ultraviolet (UV) index, and air quality.

• The weather service and returned weather details might be different depending on the served region.

• If the current house account is registered in China, the information about the wind speed and air pressure is not returned.

API description

void getHouseWeatherDetail(int limit, Map<String, Object> unit, ITuyaCommunityResultCallback<List<TuyaCommunityWeatherBean>> callback);

Parameters

Parameter	Description
limit	The returned data.
unit	The unit.
callback	The callback.

Description of unit

Key	Description	Value
tempUnit	The temperature unit.	Valid values: 1: °C 2`: °F
pressureUnit	The air pressure unit.	Valid values: 1: hPa 2: inHg 3: mmHg 4: mb
windspeedUnit	The wind speed unit.	Valid values: 1: mph 2: m/s 3: kph 4: km/h

For example, to get the temperature in °C, you can set tempUnit to 1. Example:

Map<String,Object> units = new HashMap<>();
units.put("tempUnit",1);

Java example

Map<String, Object> units = new HashMap<>();
        units.put("tempUnit", 1);   // °C
        units.put("pressureUnit", 1);  // hPa
        units.put("windspeedUnit", 2); // m/s
        TuyaCommunitySDK.newHouseInstance(Utils.getHouseId()).getHouseWeatherDetail(10, units, new ITuyaCommunityResultCallback<List<TuyaCommunityWeatherBean>>() {
            @Override
            public void onSuccess(List<TuyaCommunityWeatherBean> tuyaCommunityWeatherSketchBean) {
		// do something

            }

            @Override
            public void onFailure(String s, String s1) {
		// do something
            }
        });

Transfer out of a house

Transfers a user out of a house if the user’s property ownership is changed, a lease expires, or due to other reasons.

API description

void moveOutHouse(String communityId, String roomUserId, ISuccessFailureCallback callback);

Parameters

Parameter	Description
communityId	The community ID.
roomUserId	The ID of the mapping between a house and a user.
callback	The callback.

Example

    TuyaCommunitySDK.getHouseManagerInstance().moveOutHouse(communityId, roomUserId, new ISuccessFailureCallback() {
            @Override
            public void onSuccess() {
		// do something
            }

            @Override
            public void onFailure(String s, String s1) {
		// do something
            }
        });

Delete a house

Deletes a house if the house is pending reviewing, the house user is transferred out of the house, or failed to pass the reviewing.

API description

void deleteHouse(String communityId, long houseId, ISuccessFailureCallback callback);

Parameters

Parameter	Description
communityId	The community ID.
houseId	The house ID.
callback	The callback.

Example

TuyaCommunitySDK.getHouseManagerInstance().deleteHouse(communityId, houseId, new ISuccessFailureCallback() {
		@Override
		public void onSuccess() {
	// do something
		}

		@Override
		public void onFailure(String s, String s1) {
	// do something
		}
	});

Sort devices and groups in a house

API description

void sortDeviceOrGroup(List<CommunityDeviceAndGroupInHouseBean> list, ISuccessFailureCallback callback);

Parameters

Parameter	Description
list	A list of rooms or groups. The element CommunityDeviceAndGroupInHouseBean includes two fields: bizType: the types of sorted objects, such as groups or devices. This is an enumeration of integer objects. For more information, see BizParentTypeEnum. bizId: the ID of a sorted object, such as a group ID or a device ID.
callback	The callback.

Enumerated values of BizParentTypeEnum:

• LOCATION
• MESH
• ROOM
• GROUP
• DEVICE

Java example

List<CommunityDeviceAndGroupInHouseBean> list = new ArrayList<>();
List<DeviceBean> deviceList = houseBean.getDeviceList();
List<GroupBean> groupList = houseBean.getGroupList();
for (GroupBean bean : groupList) {
	CommunityDeviceAndGroupInHouseBean deviceInRoomBean = new CommunityDeviceAndGroupInHouseBean();
	deviceInRoomBean.setBizId(bean.getDevId());
	deviceInRoomBean.setBizType(BizParentTypeEnum.GROUP.getType());
	list.add(deviceInRoomBean);
}
for (DeviceBean bean : deviceList) {
	CommunityDeviceAndGroupInHouseBean deviceInRoomBean = new CommunityDeviceAndGroupInHouseBean();
	deviceInRoomBean.setBizId(bean.getDevId());
	deviceInRoomBean.setBizType(BizParentTypeEnum.DEVICE.getType());
	list.add();
}
TuyaCommunitySDK.newHouseInstance(houseId).sortDevInHouse(houseId, list, new ISuccessFailureCallback() {
		@Override
		public void onSuccess() {
			// do something
		}
		@Override
		public void onFailure(String code, String error) {
			// do something
		}
	});

	// @param allDeviceBeans Contains all devices and groups in current House.
Collections.sort(allDeviceBeans, new Comparator<DeviceBean>() {
				@Override
				public int compare(DeviceBean o1, DeviceBean o2) {
					return o1.getHouseDisplayOrder() - o2.getHouseDisplayOrder();
				}
			});

Register or cancel a listener for changes in house information

API description

void unRegisterHouseStatusListener(ITuyaHouseStatusListener listener)

Parameters

Parameter	Description
listener	The listener.

Java example

// Defines the listener.
ITuyaHouseStatusListener listener = new ITuyaHouseStatusListener() {
		@Override
		public void onDeviceAdded(String devId) {
			// do something
		}
		@Override
		public void onDeviceRemoved(String devId) {
			// do something
		}
		@Override
		public void onGroupAdded(long groupId) {
			// do something
		}
		@Override
		public void onGroupRemoved(long groupId) {
			// do something
		}
		@Override
		public void onMeshAdded(String meshId) {
			// do something
		}
	};
// Registers a listener.
TuyaCommunitySDK.newHouseInstance(houseId).registerHouseStatusListener(listener);
// ...
// Cancels a listener.
TuyaCommunitySDK.newHouseInstance(houseId).unRegisterHouseStatusListener(listener);