Home Information Management

Last Updated on : 2024-11-18 11:33:13download

This topic describes the API methods for Android to query and manage home information. These API methods can be used to implement a bunch of features. For example, create a home, query a list of homes, query home information, modify home information, query home weather information, and set devices and member groups for homes. You can also register listeners to listen for changes in home information, or unregister the listeners.

Functional description

ITuyaHomeManager provides the capabilities to add a home, get a list of homes, and listen for changes in home information. The class TuyaHomeSdk.getHomeManagerInstance() is called to implement these features.

Data types of HomeBean

Property	Type	Description
name	String	The name of a home.
geoName	String	The geographical location of a home.
lon	Double	The longitude of a home.
lat	Double	The latitude of a home.
homeId	Long	The home ID.
admin	Boolean	Indicates the identity of an administrator.
homeStatus	Integer	The status of the request to join a home. Valid values: `1`: pending acceptance `2`: accepted `3`: rejected
role	Integer	The roles of home members. Valid values: `-1`: custom member `0`: home member `1`: administrator `2`: home 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.

Create a home

API description

void createHome(String name, double lon, double lat, String geoName, List<String> rooms, ITuyaHomeResultCallback callback)

Parameters

Parameter	Description
name	The name of a home. Enter up to 25 characters.
lon	The longitude of a home. If the geographical location of the home is not required, set the value to `0`.
lat	The latitude of a home. If the geographical location of the home is not required, set the value to `0`.
geoName	The geographical location of a home.
rooms	The list of rooms.
callback	The callback.

Example for Java

TuyaHomeSdk.getHomeManagerInstance().createHome(name, lon, lat, geoName, rooms, new ITuyaHomeResultCallback() {
		@Override
		public void onSuccess(HomeBean bean) {
			// do something
		}
		@Override
		public void onError(String errorCode, String errorMsg) {
			// do something
		}
	});

Query a list of homes

API description

void queryHomeList(ITuyaGetHomeListCallback callback)

Parameters

Parameter	Description
callback	The callback.

Example for Java

TuyaHomeSdk.getHomeManagerInstance().queryHomeList(new ITuyaGetHomeListCallback() {
		@Override
		public void onSuccess(List<HomeBean> homeBeans) {
			// do something
		}
		@Override
		public void onError(String errorCode, String error) {
			// do something
		}
	});

Listen for changes in home information

Listens for changes in home information in specific events. For example, a home is added, modified, or deleted, a user is invited to the home, the resource sharing list is modified, and the server is connected.

API description

public interface ITuyaHomeChangeListener {
	/**
	* A home is added.
	* Data is synchronized between multiple devices.
	*
	* @param homeId
	*/
	void onHomeAdded(long homeId);

	/**
	* A user is invited to the home.
	* @param homeId    The ID of the home.
	* @param homeName  The name of the home.
	*/
	void onHomeInvite(long homeId,String homeName);

	/**
	* The home is deleted.
	* Data is synchronized between multiple devices.
	*
	* @param homeId
	*/
	void onHomeRemoved(long homeId);

	/**
	* Home information is modified.
	* Data is synchronized between multiple devices.
	*
	* @param homeId
	*/
	void onHomeInfoChanged(long homeId);

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

	/**
	*
	* 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 home to initialize data.
	*/
	void onServerConnectSuccess();
}

Add a home listener

API description

void registerTuyaHomeChangeListener(ITuyaHomeChangeListener listener)

Parameters

Parameter	Description
listener	The listener.

Example for Java

// Defines the listener.
ITuyaHomeChangeListener listener = new ITuyaHomeChangeListener() {
		@Override
		public void onHomeInvite(long homeId, String homeName) {
			// do something
		}
		@Override
		public void onHomeRemoved(long homeId) {
			// do something
		}
		@Override
		public void onHomeInfoChanged(long homeId) {
			// 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
		}
		@Override
		public void onHomeAdded(long homeId) {
			// do something
		}
	};
// Registers a listener.
TuyaHomeSdk.getHomeManagerInstance().registerTuyaHomeChangeListener(listener);

Delete a home listener

API description

void unRegisterTuyaHomeChangeListener(ITuyaHomeChangeListener listener)

Parameters

Parameter	Description
listener	The listener.

Example for Java

// Defines the listener.
ITuyaHomeChangeListener listener = new ITuyaHomeChangeListener() {
		@Override
		public void onHomeInvite(long homeId, String homeName) {
			// do something
		}
		@Override
		public void onHomeRemoved(long homeId) {
			// do something
		}
		@Override
		public void onHomeInfoChanged(long homeId) {
			// 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
		}
		@Override
		public void onHomeAdded(long homeId) {
			// do something
		}
	};
// Registers a listener.
TuyaHomeSdk.getHomeManagerInstance().registerTuyaHomeChangeListener(listener);
// ...
// Unregisters a listener.
TuyaHomeSdk.getHomeManagerInstance().unRegisterTuyaHomeChangeListener(listener);

Connect to an MQTT server

API description

void onServerConnectSuccess()

Example for Java

// Defines the listener.
ITuyaHomeChangeListener listener = new ITuyaHomeChangeListener() {
		@Override
		public void onHomeInvite(long homeId, String homeName) {
			// do something
		}
		@Override
		public void onHomeRemoved(long homeId) {
			// do something
		}
		@Override
		public void onHomeInfoChanged(long homeId) {
			// 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
		}
		@Override
		public void onHomeAdded(long homeId) {
			// do something
		}
	};
// Registers a listener.
TuyaHomeSdk.getHomeManagerInstance().registerTuyaHomeChangeListener(listener);
// ...
// Unregisters a listener.
TuyaHomeSdk.getHomeManagerInstance().unRegisterTuyaHomeChangeListener(listener);

Query home details

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

API description

void getHomeDetail(ITuyaHomeResultCallback callback)

Parameters

Parameter	Description
callback	The callback.

Example for Java

TuyaHomeSdk.newHomeInstance(10000).getHomeDetail(new ITuyaHomeResultCallback() {
		@Override
		public void onSuccess(HomeBean bean) {
			// do something
		}
		@Override
		public void onError(String errorCode, String errorMsg) {
			// do something
		}
	});

Query offline home details

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

API description

void getHomeLocalCache(ITuyaHomeResultCallback callback)

Parameters

Parameter	Description
callback	The callback.

Example for Java

TuyaHomeSdk.newHomeInstance(10000).getHomeLocalCache(new ITuyaHomeResultCallback() {
		@Override
		public void onSuccess(HomeBean bean) {
			// do something
		}
		@Override
		public void onError(String errorCode, String errorMsg) {
			//sdk cache error do not deal
		}
	});

Query cached data

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

To get the cached data of a home, you must first call the initialization API method TuyaHomeSdk.newHomeInstance("homeId").getHomeDetail() or TuyaHomeSdk.newHomeInstance("homeId").getHomeLocalCache() and then call the API method TuyaHomeSdk.getDataInstance().

Modify home information

Latest version

API description

void updateHome(String name, double lon, double lat, String geoName, List<String> rooms, IResultCallback callback)

Parameters

Parameter	Description
name	The name of a home. Enter up to 25 characters.
lon	The longitude of the home.
lat	The latitude of the home.
geoName	The geographical location of the home.
rooms	The rooms of the home.
callback	The callback.

Example for Java

TuyaHomeSdk.newHomeInstance(10000).updateHome(name, lon, lat, geoName, rooms, new IResultCallback() {
		@Override
		public void onError(String code, String error) {
			// do something
		}
		@Override
		public void onSuccess() {
			// do something
		}
	});

Legacy version

API description

void updateHome(String name, double lon, double lat, String geoName, IResultCallback callback)

Parameters

Parameter	Description
name	The name of a home.
lon	The longitude of the home.
lat	The latitude of the home.
geoName	The geographical location of the home.
callback	The callback.

Example for Java

TuyaHomeSdk.newHomeInstance(10000).updateHome(name, lon, lat, geoName, new IResultCallback() {
		@Override
		public void onSuccess() {
			// do something
		}
		@Override
		public void onError(String code, String error) {
			// do something
		}
	});

Query home weather information

Local weather overview

API description

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

void getHomeWeatherSketch(double lon,double lat,IIGetHomeWetherSketchCallBack callback);

Parameters

Parameter	Description
lon	The longitude of a device.
lat	The latitude of a home.
callback	The callback.

Parameters of WeatherBean

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

Example for Java

TuyaHomeSdk.newHomeInstance(mHomeId).getHomeWeatherSketch(120.075652,30.306265
new IIGetHomeWetherSketchCallBack() {
	@Override
	public void onSuccess(WeatherBean result) {
	}
	@Override
	public void onFailure(String errorCode, String errorMsg) {
	}
});

Local weather details

Returns the weather details for the city where the home is located. Multiple types of weather data are 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 home account is registered in mainland China, the information about the wind speed and air pressure is not returned.

API description

void getHomeWeatherDetail(int limit, Map<String,Object> unit, IGetHomeWetherCallBack callback);

Parameters

Parameter	Description
limit	The maximum number of weather metrics allowed to be returned.
unit	The unit of a weather metric, as described in the following table.
callback	The callback.

Description

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

For example, to get the temperature in Celsius, you can set tempUnit to 1.

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

Example for Java

Map<String,Object> units = new HashMap<>();
units.put("tempUnit",1);   // °C
units.put("pressureUnit",1);  // hPa
units.put("windspeedUnit",2); // m/s

TuyaHomeSdk.newHomeInstance(mHomeId).getHomeWeatherDetail(10, units, new IGetHomeWetherCallBack() {
	@Override
	public void onSuccess(ArrayList<DashBoardBean> result) {

	}

	@Override
	public void onFailure(String errorCode, String errorMsg) {

	}
});

Dismiss a home

API description

void dismissHome(IResultCallback callback)

Parameters

Parameter	Description
callback	The callback.

Example for Java

TuyaHomeSdk.newHomeInstance(10000).dismissHome(new IResultCallback() {
		@Override
		public void onSuccess() {
			// do something
		}
		@Override
		public void onError(String code, String error) {
			// do something
		}
	});

Sort devices and groups in a home

API description

void sortDevInHome(String homeId, List<DeviceAndGroupInHomeBean> list, IResultCallback callback)

Parameters

Parameter	Description
homeId	The home ID.
List	A list of rooms or groups. The element `DeviceAndGroupInHomeBean` 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: location
MESH: mesh network
ROOM: room
GROUP: device group
DEVICE: device

Example for Java

List<DeviceAndGroupInHomeBean> list = new ArrayList<>();
List<DeviceBean> deviceList = homeBean.getDeviceList();
List<GroupBean> groupList = homeBean.getGroupList();
for (GroupBean bean : groupList) {
	DeviceAndGroupInHomeBean deviceInRoomBean = new DeviceAndGroupInHomeBean();
	deviceInRoomBean.setBizId(bean.getDevId());
	deviceInRoomBean.setBizType(BizParentTypeEnum.GROUP.getType());
	list.add(deviceInRoomBean);
}
for (DeviceBean bean : deviceList) {
	DeviceAndGroupInHomeBean deviceInRoomBean = new DeviceAndGroupInHomeBean();
	deviceInRoomBean.setBizId(bean.getDevId());
	deviceInRoomBean.setBizType(BizParentTypeEnum.DEVICE.getType());
	list.add();
}
TuyaHomeSdk.newHomeInstance(10000).sortDevInHome(homeId, list, new IResultCallback() {
		@Override
		public void onSuccess() {
			// do something
		}
		@Override
		public void onError(String code, String error) {
			// do something
		}
	});

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

Register or unregister a listener for changes in home information

API description

void unRegisterHomeStatusListener(ITuyaHomeStatusListener listener)

Parameters

Parameter	Description
listener	The listener.

Example for Java

// Defines the listener.
ITuyaHomeStatusListener listener = new ITuyaHomeStatusListener() {
		@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.
TuyaHomeSdk.newHomeInstance(10000).registerHomeStatusListener(listener);
// ...
// Unregisters a listener.
TuyaHomeSdk.newHomeInstance(10000).unRegisterHomeStatusListener(listener);