Device Management

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 a bunch of features. For example, initialize devices, listen for devices, control devices, query device information, modify device names, remove devices, restore factory defaults, query Wi-Fi signal strength, and recycle device resources.

Functional description

• The returned data of devices is sent to receivers in asynchronous messages.

• API methods are available to send commands and update the firmware.

• The IThingDevice class enables notifications of device status. You can register callbacks to get notifications in specific conditions. For example, devices receive data, devices are removed, or get online or offline, or the mobile phone’s network changes.

• The following table describes the data types of DeviceBean.

  Property	Type	Description
  devId	String	The device ID.
  name	String	The name of a device.
  iconUrl	String	The URL of a device icon.
  schema	String	The type of data point (DP).
  productId	String	The product ID (PID). The devices of the same PID are assigned the same value of schema.
  timezoneId	String	The ID of the time zone in which a device is located.
  category	String	The type of device (deprecated). To get the device type, you need to use the category field of ProductBean.
  pv	String	The version of a gateway protocol.
  bv	String	The generic firmware version of a gateway.
  time	Long	The time when a device is activated.
  schemaMap	Map	The cached data of schema.
  dps	Map	Current data of a device. key means a DP ID and value means the value of the DP ID. For more information, see Data points.
  getIsOnline	Boolean	Indicates whether a device is online on a local area network (LAN) or in the cloud.
  isLocalOnline	Boolean	Indicates the device status on a LAN.
  supportGroup	Boolean	Indicates whether a device supports groups. If not, go to the Tuya IoT Development Platform to enable this feature.
  isShare	Boolean	Indicates whether a device is a shared device.
  virtual	Boolean	Indicates whether a device is a virtual device.
  isZigBeeWifi	Boolean	Indicates whether a device is a Zigbee gateway device.
  hasZigBee	Boolean	Indicates whether a Zigbee device exists.
  nodeId	String	Applies to a gateway and its sub-devices. It is an attribute of a sub-device that indicates its short URL ID. Each sub-device of the same gateway is assigned a unique value of nodeId.
  meshId	String	Applies to a gateway and its sub-devices. It is an attribute of a sub-device that indicates the ID of its gateway.
  lon	String	The longitude of a device.
  lat	String	The latitude of a device.
  productBean	ProductBean	The product information.
  accessType	NSInteger	0: Tuya Device, 1: Matter Device, 2: TuyaLink Device
  thingModel	ThingSmartThingModel	This is required when accessType == 2 in the Thing model. Before using it, retrieve it through -getThingModelWithProductId:(String pid,IThingDataCallback<ThingSmartThingModel> callback) or getThingModelWithProductId(String pid, String productVersion,IThingDataCallback<ThingSmartThingModel> callback);.

  If the values of lon and lat are required for device control, call setLatAndLong to set the longitude and latitude before pairing.

  ThingSdk.setLatAndLong(String latitude, String longitude)
  

• Properties of ProductBean

  Property	Type	Description
  category	String	The abbreviation of a device type. It indicates the device type of a product. For example, kg represents a switch and cz represents a socket. For more information, see Standard Instruction Set.
  capability	int	The networking capability. Valid values: 0: Wi-Fi 1: wired 2: General Packet Radio Service (GPRS) 3: Narrowband Internet of Things (NB-IoT) 10: Bluetooth 11: Bluetooth mesh 12: Zigbee 13: infrared 14: pairing over Zigbee
  resptime	long	The time consumed to load the data from the server side.
  supportSGroup	Boolean	Indicates whether standard groups are supported.

Initialize a device

Initialize home data

• Initializes data before device control. You can call the API method in the following code block to get device information from a home.

• Initialization is required only once during the period in which your app is alive.

• Initialization is also required after users switch between homes.

  ThingHomeSdk.newHomeInstance(homeId).getHomeDetail(new IThingHomeResultCallback() {
  	@Override
  	public void onSuccess(HomeBean homeBean) {
  
  	}
  
  	@Override
  	public void onError(String errorCode, String errorMsg) {
  
  	}
  });
  

• HomeBean is returned by the onSuccess method.

• Call getDeviceList of HomeBean to get a list of devices.

  List<DeviceBean> deviceList = homeBean.getDeviceList();
  

Initialize the device control class

Initializes the device control class IThingDevice by device ID.

API description

ThingHomeSdk.newDeviceInstance(String devId);

Parameters

Example for Java

IThingDevice mDevice = ThingHomeSdk.newDeviceInstance(deviceBean.getDevId());

Listen for devices

Register a device listener

IThingDevice listens for device information, including:

• DP data
• Device name
• Status when a device gets online or removed

API description

IThingDevice.registerDevListener(IDevListener listener)

Parameters

IDevListener API

public interface IDevListener {

	/**
	* Updates the DP.
	*
	* @param devId The ID of the device.
	* @param dpStr The updated DP. It is a JSON string in the following format: {"101": true}.
	*/
	void onDpUpdate(String devId, String dpStr);

	/**
	* The callback of device removal.
	*
	* @param devId The device iD.
	*/
	void onRemoved(String devId);

	/**
	* The callback that is executed when the device gets online or offline. If the sub-device is powered off or disconnected from the network, the server executes the callback three minutes after the event occurs.
	*
	* @param devId The ID of the device.
	* @param online Indicates whether the device is online. A value of `true` indicates that the device is online.
	*/
	void onStatusChanged(String devId, boolean online);

	/**
	* The callback that is executed when the network status changes.
	*
	* @param devId The ID of the device.
	*  @param status Indicates whether the network is available. A value of `true` indicates that the network is available.
	*/
	void onNetworkStatusChanged(String devId, boolean status);

	/**
	* The callback of device updates.
	*
	* @param devId The ID of the device.
	*/
	void onDevInfoUpdate(String devId);

}

Example for Java

mDevice.registerDevListener(new IDevListener() {
	@Override
	public void onDpUpdate(String devId, String dpStr) {

	}
	@Override
	public void onRemoved(String devId) {

	}
	@Override
	public void onStatusChanged(String devId, boolean online) {

	}
	@Override
	public void onNetworkStatusChanged(String devId, boolean status) {

	}
	@Override
	public void onDevInfoUpdate(String devId) {

	}
});

Unregister a device listener

Unregisters a device listener if the listener is not required.

API description

IThingDevice.unRegisterDevListener()

Example for Java

mDevice.unRegisterDevListener();

void getOfflineReminderSupportStatus(String hdId, IThingResultCallback<IsSupportOffLineBean> callback);

 mDevice.getOfflineReminderSupportStatus(deviceId, new IThingResultCallback<IsSupportOffLineBean>() {
            @Override
            public void onSuccess(IsSupportOffLineBean result) {

            }

            @Override
            public void onError(String errorCode, String errorMessage) {

            }
        });
    }

Query device information

Returns a single DP. The response is asynchronously returned by IDevListener.onDpUpdate().

API description

mDevice.getDp(String dpId, IResultCallback callback);

Example for Java

mDevice.getDp(dpId, new IResultCallback() {
	@Override
	public void onError(String code, String error) {

	}

	@Override
	public void onSuccess() {

	}
});

Rename a device

Renames a device. This update can be synchronized to multiple devices.

API description

// Renames a device.
mDevice.renameDevice(String name,IResultCallback callback);

Example for Java

mDevice.renameDevice("The name of the device", new IResultCallback() {
	@Override
	public void onError(String code, String error) {
		// Failed to rename the device.
	}
	@Override
	public void onSuccess() {
		// The device is renamed successfully.
	}
});

Next steps

After the device is renamed, IDevListener.onDevInfoUpdate() receives a notification. Call the following method to get the latest data and refresh the device information.

ThingHomeSdk.getDataInstance().getDeviceBean(String devId);

Remove a device

Removes a device from a list of devices.

API description

void removeDevice(IResultCallback callback);

Example for Java

mDevice.removeDevice(new IResultCallback() {
	@Override
	public void onError(String errorCode, String errorMsg) {
	}

	@Override
	public void onSuccess() {
	}
});

Restore factory defaults

Restores factory defaults of a device. Then, the device data is cleared. The device enters the mode pending pairing again. A Wi-Fi device enters the Wi-Fi Easy Connect (EZ) mode by default.

API description

void resetFactory(IResultCallback callback);

Example for Java

mDevice.resetFactory(new IResultCallback() {
	@Override
	public void onError(String errorCode, String errorMsg) {
	}

	@Override
	public void onSuccess() {
	}
});

Query the Wi-Fi signal strength

Returns the Wi-Fi signal strength of a device.

API description

void requestWifiSignal(WifiSignalListener listener);

Example for Java

mDevice.requestWifiSignal(new WifiSignalListener() {

	@Override
	public void onSignalValueFind(String signal) {

	}

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

	}
});;

Recycle device resources

Recycles device resources when an application or the Activity field is disabled.

API description

void onDestroy()

Example for Java

mDevice.onDestroy();