House Management

Last Updated on : 2024-06-24 08:44:26download

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.

To get the cached data of a house, you must first call the initialization API method TuyaCommunitySDK.newHouseInstance("houseId").getHouseDetail() or TuyaCommunitySDK.newHouseInstance("houseId").getHouseLocalCache() and then call the API method TuyaCommunitySDK.getHouseDataInstance().

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);