Home Information Management

Last Updated on : 2024-06-24 08:24:59download

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