IoT App SDKCommercial Lighting App SDKAndroid PlatformDevice Management

Device Management (Android)

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.

Functional description

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 and lat are required for device control, call setLatAndLong to set the longitude and latitude before pairing.
TuyaSdk.setLatAndLong(String latitude, String longitude)

Initialize a device

Initialize the device control class

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

Listen for devices

Register a device listener

ITuyaDevice listens for device information, including:

DP data.
The name of a device.
Status when a device gets online or removed.

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.

Cancel a device listener

Cancels a device listener if the listener is not required.

API description

void ITuyaDevice.unRegisterDevListener();

Java example

mDevice.unRegisterDevListener();

Query device information

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() in DeviceBean 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() {

    }
});

Rename a device

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

Remove a device

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

Restore factory defaults

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

Query the Wi-Fi signal strength

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

    }
});

Recycle device resources

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

void ITuyaDevice.onDestroy();

Java example

mDevice.onDestroy();

Initialize a gateway device

Initialize the gateway device control class

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

Listen for sub-device

Register a sub-device listener

ITuyaGateway listens for sub-device information, including:

DP data.
The name of a sub-device.
Status when a sub-device gets online or removed.

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

            }
        });

Cancel a sub-device listener

Cancels a sub-device listener if the listener is not required.

API description

void ITuyaGateway.unRegisterSubDevListener();

Java example

mGateway.unRegisterSubDevListener();

Query a list of sub-devices for a gateway

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

    }
});

Recycle gateway resources

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

void ITuyaGateway.onDestroy();

Java example

mGateway.onDestroy();

Prev DocBluetooth Series

Next DocFirmware upgrade