Device Management

Last Updated on : 2023-06-01 06:18:31download

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

Parameter Description
devId The device ID.

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

Parameter Description
listener The listener for device status.

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

}

For more information about the DPs of the device, see Data points.

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

	}
});

Do not use the method void registerDeviceListener(IDeviceListener listener). The method only applies to standard devices. It is unavailable to this API.

Unregister a device listener

Unregisters a device listener if the listener is not required.

API description

IThingDevice.unRegisterDevListener()

Example for Java

mDevice.unRegisterDevListener();

Checks whether a device supports offline reminders.

API description

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

Parameters

Parameter Description
hdId The device ID.
callback The callback of the query result.

Example for Java

 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().

This API method applies to DPs that do not initiate data transmission. For example, query countdown information. To query standard DPs, getDps() in DeviceBean can be called.

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