Last Updated on : 2022-02-17 05:53:24download
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 default settings, query Wi-Fi signal strength, and recycle device resources.
The returned data of devices is sent to receivers in asynchronous messages.
API methods are available to send commands to devices and update the firmware.
The ITuyaDevice
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 ITuyaGateway
class provides operations related to the Zigbee gateway, including the ability to control, query, and monitor the status of sub-devices.
The following table describes the data types of DeviceBean
.
Attribute | Type | Description |
---|---|---|
devId | String | The ID of a device. |
name | String | The name of a device. |
iconUrl | String | The URL of an 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. |
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 | The DPs of a device. key means a DP ID and value means the value of the DP ID. For more information, see Set DPs. |
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 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. |
Note: If the values of
lon
andlat
are required for device control, callsetLatAndLong
to set the longitude and latitude before pairing.TuyaSdk.setLatAndLong(String latitude, String longitude)
Initializes the device control class ITuyaDevice
by device ID.
TuyaOSDevice.newDeviceInstance(String devId);
Parameters
Parameter | Description |
---|---|
devId | The ID of a device. |
Java example
ITuyaDevice mDevice = TuyaOSDevice.newDeviceInstance(deviceBean.getDevId());
ITuyaDevice
listens for device information, including:
void ITuyaDevice.registerDevListener(IDevListener listener);
Parameters
Parameter | Description |
---|---|
listener | The listener of device status. |
IDevListener
API
public interface IDevListener {
/**
* DP data update
*
* @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);
/**
* Callback of device removal
*
* @param devId The ID of the device.
*/
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);
}
Note: For more information about the DPs of the device, see Set DPs.
Java example
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) {
}
});
Note: Do not use the method
void registerDeviceListener(IDeviceListener listener)
. The method only applies to standard devices. It is unavailable to this API.
Cancels a device listener if the listener is not required.
API description
void ITuyaDevice.unRegisterDevListener();
Java example
mDevice.unRegisterDevListener();
Returns a single DP. The response is asynchronously called back by IDevListener.onDpUpdate()
.
Note: This API method applies to DPs that do not initiate data transmission. For example, query countdown information. For regular DP query,
getDps()
inDeviceBean
can be called.
void ITuyaDevice.getDp(String dpId, IResultCallback callback);
Java example
mDevice.getDp(dpId, new IResultCallback() {
@Override
public void onError(String code, String error) {
}
@Override
public void onSuccess() {
}
});
Renames a device. This update can be synchronized to multiple devices.
// Renames a device.
void ITuyaDevice.renameDevice(String name,IResultCallback callback);
Java example
mDevice.renameDevice("Device name", 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.
TuyaOSDevice.getDataInstance().getDeviceBean(String devId);
Removes a device from a list of devices.
void ITuyaDevice.removeDevice(IResultCallback callback);
Java example
mDevice.removeDevice(new IResultCallback() {
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
Restores default settings 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.
void ITuyaDevice.resetFactory(IResultCallback callback);
Java example
mDevice.resetFactory(new IResultCallback() {
@Override
public void onError(String errorCode, String errorMsg) {
}
@Override
public void onSuccess() {
}
});
Returns the Wi-Fi signal strength of a device.
void ITuyaDevice.requestWifiSignal(WifiSignalListener listener);
Java example
mDevice.requestWifiSignal(new WifiSignalListener() {
@Override
public void onSignalValueFind(String signal) {
}
@Override
public void onError(String errorCode, String errorMsg) {
}
});
Recycles device resources when an application or the Activity
field is disabled.
void ITuyaDevice.onDestroy();
Java example
mDevice.onDestroy();
Initializes the gateway device control class ITuyaGateway
by device ID.
TuyaOSDevice.newGatewayInstance(String devId);
Parameters
Parameter | Description |
---|---|
devId | The ID of a device. |
Java example
ITuyaGateway mGateway = TuyaOSDevice.newGatewayInstance(deviceBean.getDevId());
ITuyaGateway
listens for sub-device information, including:
void ITuyaGateway.registerSubDevListener(ISubDevListener listener);
Parameters
Parameter | Description |
---|---|
listener | The listener of device status. |
IDevListener
API
public interface ISubDevListener {
/**
* Updates the DP of sub-devices.
*
* @param devId The ID of a sub-device.
* @param dps The updated DP. It is a JSON string in the following format: {"101": true}.
*/
void onSubDevDpUpdate(String nodeId, String dps);
/**
* The callback of a sub-device removal.
*
* @param devId The sub-device ID.
*/
void onSubDevRemoved(String devId);
/**
* The callback that is executed when a sub-device is added.
*
* @param devId The sub-device ID.
*/
void onSubDevAdded(String devId);
/**
* The callback that is executed when a sub-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 onlineDeviceIds The ID of the online sub-device.
* @param offlineDeviceIds The ID of the offline sub-device.
*/
void onSubDevStatusChanged(List<String> onlineDeviceIds, List<String> offlineDeviceIds);
/**
* The callback of sub-device updates.
*
* @param devId The ID of the sub-device.
*/
void onSubDevInfoUpdate(String devId);
}
Note: For more information about the DPs of the device, see Set DPs.
Java example
mGateway.registerSubDevListener(
new ISubDevListener() {
void onSubDevDpUpdate(String nodeId, String dps) {
}
void onSubDevRemoved(String devId) {
}
void onSubDevAdded(String devId) {
}
void onSubDevInfoUpdate(String devId) {
}
void onSubDevStatusChanged(List<String> onlineDeviceIds, List<String> offlineDeviceIds) {
}
});
Cancels a sub-device listener if the listener is not required.
API description
void ITuyaGateway.unRegisterSubDevListener();
Java example
mGateway.unRegisterSubDevListener();
Returns a list of sub-devices for a specific gateway.
API description
void ITuyaGateway.getSubDevList(ITuyaDataCallback<List<DeviceBean>> callback);
Java example
mGateway.getSubDevList(new ITuyaDataCallback<List<DeviceBean>>() {
@Override
public void onSuccess(List<DeviceBean> result) {
}
@Override
public void onError(String errorCode, String errorMessage) {
}
});
Recycles gateway resources when an application or the Activity
field is disabled.
void ITuyaGateway.onDestroy();
Java example
mGateway.onDestroy();
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback