Device Management

This topic describes the API methods for Android to get device information and manage devices. For example, initialize devices, listen for changes, control devices, get device information, rename devices, remove devices, restore factory defaults, get Wi-Fi signal strength, and recycle device resources.

Features

• The response from the device is delivered to the receiver asynchronously.

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

• The IThingDevice class allows you to get notified of changes in device status. You can register callbacks to receive notifications when the device receives data, is removed, goes online or offline, or when the mobile phone’s network changes.

• The IThingGateway class provides operations related to the Zigbee gateway, including the capability to control, query, and monitor the status of sub-devices.

• Data types of DeviceBean:

  Property	Type	Description
  devId	String	The device ID.
  name	String	The name of the device.
  iconUrl	String	The URL of the 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 time zone of the device.
  category	String	The type of device.
  pv	String	The version of the gateway protocol.
  bv	String	The version of the generic gateway firmware.
  time	Long	The time when the device is activated.
  schemaMap	Map	The schema cache.
  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 Data Points.
  getIsOnline	Boolean	Indicates whether the device is online on a local area network (LAN) or in the cloud.
  isLocalOnline	Boolean	Indicates whether the device is connected to a LAN.
  supportGroup	Boolean	Indicates whether the device supports groups. If not, go to the Tuya Developer Platform to enable this feature.
  isShare	Boolean	Indicates whether the device is a shared device.
  virtual	Boolean	Indicates whether the device is a virtual device.
  isZigBeeWifi	Boolean	Indicates whether the device is a Zigbee gateway.
  hasZigBee	Boolean	Indicates whether a Zigbee device exists.
  nodeId	String	Applies to the gateway and its sub-devices. It is a property of the sub-device to indicate its short URL ID. Each sub-device of the same gateway is assigned a unique nodeId.
  meshId	String	Applies to the gateway and its sub-devices. It is a property of the sub-device to indicate the ID of the associated gateway.
  lon	String	The longitude of the device.
  lat	String	The latitude of the device.

  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)
  

Initialize device

Initialize device control class

Initializes the device control class IThingDevice by device ID.

ThingOSDevice.newDeviceInstance(String devId);

Parameter description

Parameter	Description
devId	The device ID.

Example in Java

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

Listen for devices

Register device listener

IThingDevice listens for device information, including:

• DP data
• Device name
• Device online status and removal

void IThingDevice.registerDevListener(IDevListener listener);

Parameter description

Parameter	Description
listener	The listener for device status.

IDevListener

public interface IDevListener {

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

    /**
     * The callback for device removal.
     *
     * @param devId Device ID
     */
    void onRemoved(String devId);

    /**
     * The callback invoked when the device gets online or offline. If the device is powered off or disconnected, the server invokes this callback three minutes after the event occurs.
     *
     * @param devId  Device ID
     * @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 invoked when the network status changes.
     *
     * @param devId  Device ID
     * @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 for device information updates.
     *
     * @param devId Device ID
     */
    void onDevInfoUpdate(String devId);
}

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

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

    }
});

Remove device listener

Remove a device listener when it is no longer needed.

API description

void IThingDevice.unRegisterDevListener();

Example in Java

mDevice.unRegisterDevListener();

Get device information

Request the data of a single DP. The response is asynchronously returned by IDevListener.onDpUpdate().

void IThingDevice.getDp(String dpId, IResultCallback callback);

Example in Java

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

    }

    @Override
    public void onSuccess() {

    }
});

Rename device

Rename a device. This update can be synchronized across devices.

// Rename device.
void IThingDevice.renameDevice(String name,IResultCallback callback);

Example in Java

mDevice.renameDevice("Device name", new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        // Rename failed.
    }

    @Override
    public void onSuccess() {
        // Rename succeeded.
    }
});

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.

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

Remove device

Remove a device from the list of devices.

void IThingDevice.removeDevice(IResultCallback callback);

Example in Java

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

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

Factory reset

After a factory reset, the device’s data is cleared and it enters pairing mode. A Wi-Fi device enters the Wi-Fi Easy Connect (EZ) mode by default.

void IThingDevice.resetFactory(IResultCallback callback);

Example in Java

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

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

Get Wi-Fi signal strength

Request the Wi-Fi signal strength of the device.

void IThingDevice.requestWifiSignal(WifiSignalListener listener);

Example in Java

mDevice.requestWifiSignal(new WifiSignalListener() {
    @Override
    public void onSignalValueFind(String signal) {

    }

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

    }
});

Recycle device resources

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

void IThingDevice.onDestroy();

Example in Java

mDevice.onDestroy();

Initialize gateway

Initialize gateway control class

Initialize the gateway control class IThingGateway by device ID.

ThingOSDevice.newGatewayInstance(String devId);

Parameter description

Parameter	Description
devId	The device ID.

Example in Java

IThingGateway mGateway = ThingOSDevice.newGatewayInstance(deviceBean.getDevId());

Listen for sub-device

Register sub-device listener

IThingGateway listens for sub-device information, including:

• DP data
• Sub-device name
• Sub-device online status and removal

void IThingGateway.registerSubDevListener(ISubDevListener listener);

Parameter description

Parameter	Description
listener	The listener for device status.

IDevListener

public interface ISubDevListener {

    /**
     * Sub-device DP data update
     *
     * @param nodeId Sub-device ID
     * @param dps The updated DP. It is a JSON string in the format: {"101": true}.
     */
    void onSubDevDpUpdate(String nodeId, String dps);

    /**
     * The callback for sub-device removal.
     *
     * @param devId Sub-device ID
     */
    void onSubDevRemoved(String devId);

    /**
     * Callback for adding a sub-device.
     *
     * @param devId Sub-device ID
     */
    void onSubDevAdded(String devId);

    /**
     * The callback invoked when the sub-device gets online or offline. If the device is powered off or disconnected, the server invokes this callback three minutes after the event occurs.
     *
     * @param onlineDeviceIds Online sub-device ID
     * @param offlineDeviceIds Offline sub-device ID
     */
    void onSubDevStatusChanged(List<String> onlineDeviceIds, List<String> offlineDeviceIds);

    /**
     * Callback for sub-device information updates.
     *
     * @param devId Sub-device ID
     */
    void onSubDevInfoUpdate(String devId);
}

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

Example in Java

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

            }
        });

Remove sub-device listener

Remove a sub-device listener when it is no longer needed.

API description

void IThingGateway.unRegisterSubDevListener();

Example in Java

mGateway.unRegisterSubDevListener();

Get sub-device list

Request the list of sub-devices connected to the gateway.

API description

void IThingGateway.getSubDevList(IThingDataCallback<List<DeviceBean>> callback);

Example in Java

mGateway.getSubDevList(new IThingDataCallback<List<DeviceBean>>() {
    @Override
    public void onSuccess(List<DeviceBean> result) {

    }

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

    }
});

Recycle gateway resources

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

void IThingGateway.onDestroy();

Example in Java

mGateway.onDestroy();