Family Information Management

Last Updated on : 2022-02-17 07:20:35download

This topic describes the API methods for Android to get smart device information and manage smart devices. These API methods can be used to implement multiple 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 cancel 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.

The following table describes the data types of DeviceBean:

Attribute	Data 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`: 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	A list of rooms.
callback	The callback to get the result.

Java example

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

Query a list of homes

API description

void queryHomeList(ITuyaGetHomeListCallback callback)

Parameters

Parameter	Description
callback	The callback to get the result.

Java example

TuyaHomeSdk.getHomeManagerInstance().queryHomeList(new ITuyaGetHomeListCallback() {
		@Override
		public void onSuccess(List<HomeBean> homeBeans) {
			// The request is successful.
		}
		@Override
		public void onError(String errorCode, String error) {
			// The request failed.
		}
	});

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 IoT 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.

Java example

// Defines the listener.
ITuyaHomeChangeListener listener = new ITuyaHomeChangeListener() {
		@Override
		public void onHomeInvite(long homeId, String homeName) {
			// A home invitation is sent.
		}
		@Override
		public void onHomeRemoved(long homeId) {
			// A home is removed.
		}
		@Override
		public void onHomeInfoChanged(long homeId) {
			// Home information is modified.
		}
		@Override
		public void onSharedDeviceList(List<DeviceBean> sharedDeviceList) {
			// Listens for a list of shared devices.
		}
		@Override
		public void onSharedGroupList(List<GroupBean> sharedGroupList) {
			// Listens for a list of shared groups.
		}
		@Override
		public void onServerConnectSuccess() {
			// The server is connected.
		}
		@Override
		public void onHomeAdded(long homeId) {
			// A home is added.
		}
	};
// Registers a listener.
TuyaHomeSdk.getHomeManagerInstance().registerTuyaHomeChangeListener(listener);

Delete a home listener

API description

void unRegisterTuyaHomeChangeListener(ITuyaHomeChangeListener listener)

Parameters

Parameter	Description
listener	The listener.

Java example

// Defines the listener.
ITuyaHomeChangeListener listener = new ITuyaHomeChangeListener() {
		@Override
		public void onHomeInvite(long homeId, String homeName) {
			// A home invitation is sent.
		}
		@Override
		public void onHomeRemoved(long homeId) {
			// The home is removed.
		}
		@Override
		public void onHomeInfoChanged(long homeId) {
			// Home information is modified.
		}
		@Override
		public void onSharedDeviceList(List<DeviceBean> sharedDeviceList) {
			// Listens for the list of shared devices.
		}
		@Override
		public void onSharedGroupList(List<GroupBean> sharedGroupList) {
			// Listens for the list of shared groups.
		}
		@Override
		public void onServerConnectSuccess() {
			// The server is connected.
		}
		@Override
		public void onHomeAdded(long homeId) {
			// A home is added.
		}
	};
// Registers a listener.
TuyaHomeSdk.getHomeManagerInstance().registerTuyaHomeChangeListener(listener);
// ...
// Cancels a listener.
TuyaHomeSdk.getHomeManagerInstance().unRegisterTuyaHomeChangeListener(listener);

Register a callback of the successful connection to the MQTT server

API description

void onServerConnectSuccess()

Java example

// Defines the listener.
ITuyaHomeChangeListener listener = new ITuyaHomeChangeListener() {
		@Override
		public void onHomeInvite(long homeId, String homeName) {
			// A home invitation is sent.
		}
		@Override
		public void onHomeRemoved(long homeId) {
			// The home is removed.
		}
		@Override
		public void onHomeInfoChanged(long homeId) {
			// Home information is modified.
		}
		@Override
		public void onSharedDeviceList(List<DeviceBean> sharedDeviceList) {
			// Listens for the list of shared devices.
		}
		@Override
		public void onSharedGroupList(List<GroupBean> sharedGroupList) {
			// Listens for the list of shared groups.
		}
		@Override
		public void onServerConnectSuccess() {
			// The server is connected.
		}
		@Override
		public void onHomeAdded(long homeId) {
			// A home is added.
		}
	};
// Registers a listener.
TuyaHomeSdk.getHomeManagerInstance().registerTuyaHomeChangeListener(listener);
// ...
// Cancels 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 to get the result.

Java example

TuyaHomeSdk.newHomeInstance(10000).getHomeDetail(new ITuyaHomeResultCallback() {
		@Override
		public void onSuccess(HomeBean bean) {
			// The request is successful.
		}
		@Override
		public void onError(String errorCode, String errorMsg) {
			// The request failed.
		}
	});

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 to get the result.

Java example

TuyaHomeSdk.newHomeInstance(10000).getHomeLocalCache(new ITuyaHomeResultCallback() {
		@Override
		public void onSuccess(HomeBean bean) {
			// The request is successful.
		}
		@Override
		public void onError(String errorCode, String errorMsg) {
			// The request failed.
		}
	});

Query cached data

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

Note: 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

New 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 to get the result.

Java example

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

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 to get the result.

Java example

TuyaHomeSdk.newHomeInstance(10000).updateHome(name, lon, lat, geoName, new IResultCallback() {
		@Override
		public void onSuccess() {
			// The request is successful.
		}
		@Override
		public void onError(String code, String error) {
			// The request failed.
		}
	});

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 the home.
lat	The latitude of the home.
callback	The callback to get the result.

WeatherBean description

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

Java example

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 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 area.
If the current home account is registered in 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 returned data.
unit	The unit of the data.
callback	The callback to get the result.

Unit description

key	description	value
tempUnit	temperature unit	°C：1 °F：2
pressureUnit	pressure unit	hPa：1 inHg：2 mmHg：3 mb：4
windspeedUnit	windspeed unit	mph：1 m/s：2 kph：3 km/h：4

For example, to get temperature in Celsius, 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

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

	}

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

	}
});

Cancel a home

API description

void dismissHome(IResultCallback callback)

Parameters

Parameter	Description
callback	The callback to get the result.

Java example

TuyaHomeSdk.newHomeInstance(10000).dismissHome(new IResultCallback() {
		@Override
		public void onSuccess() {
			// The request is successful.
		}
		@Override
		public void onError(String code, String error) {
			// The request failed.
		}
	});

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 to get the result.

Enumerated values of BizParentTypeEnum:

LOCATION
MESH
ROOM
GROUP
DEVICE

Java example

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() {
			// The request is successful.
		}
		@Override
		public void onError(String code, String error) {
			// The request failed.
		}
	});

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

Register or cancel a listener for changes in home information

API description

void unRegisterHomeStatusListener(ITuyaHomeStatusListener listener)

Parameters

Parameter	Description
listener	The listener.

Java example

// Defines the listener.
ITuyaHomeStatusListener listener = new ITuyaHomeStatusListener() {
		@Override
		public void onDeviceAdded(String devId) {
			// A device is added.
		}
		@Override
		public void onDeviceRemoved(String devId) {
			// A device is removed.
		}
		@Override
		public void onGroupAdded(long groupId) {
			// A group is added.
		}
		@Override
		public void onGroupRemoved(long groupId) {
			// A group is removed.
		}
		@Override
		public void onMeshAdded(String meshId) {
			// A gateway is added.
		}
	};
// Registers a listener.
TuyaHomeSdk.newHomeInstance(10000).registerHomeStatusListener(listener);
// ...
// Cancels a listener.
TuyaHomeSdk.newHomeInstance(10000).unRegisterHomeStatusListener(listener);