Device Service

Last Updated on : 2024-09-13 06:45:57download

This topic describes the device service, allowing you to manage devices using MQTT and Bluetooth tools.

MQTT tool

Subscribe to and publish MQTT messages.

Subscribe to a topic

Parameters

Parameter	Type	Required	Description
topic	String	Yes	The topic to subscribe to.
callback	IMQTTSubscribeCallback	Yes	The subscription callback.

Example

MQTTHelper.subscribe("topic", new IMQTTSubscribeCallback() {
            @Override
            public void onError(String s, String s1) {
                Log.d(TAG, "onError: " + s);

            }

            @Override
            public void onSuccess() {
                Log.d(TAG, "onSuccess: ");

            }
        });

Unsubscribe from a topic

Parameters

Parameter	Type	Required	Description
topic	String	Yes	The topic to unsubscribe from.
callback	IMQTTSubscribeCallback	Yes	The unsubscription callback.

Example

MQTTHelper.unsubscribe("topic", callback);

Publish a message on specified topic

Parameters

Parameter	Type	Required	Description
topic	String	Yes	The topic to publish.
data	String	Yes	The content to publish.
callback	IndustryCallBack	Yes	The publishing callback.

Example

MQTTHelper.publish("topic", data, new IndustryCallBack() {
            @Override
            public void onError(int code, String msg) {
                Log.d(TAG, "onError: " + msg);

            }

            @Override
            public void onSuccess() {
                Log.d(TAG, "onSuccess: ");

            }
        });

Register message listener

Parameters

Parameter	Type	Required	Description
listener	IMQTTListener	Yes	The message listener.

Example

MQTTHelper.registerMessageListener(new IMQTTListener() {
            @Override
            public void onReceiveError(topic: String, code: String, msg: String) {

            }

            @Override
            public void onReceiveSuccess(topic: String, protocol: Int, jsonData: String) {

            }
        });

Remove message listener

Parameters

Parameter	Type	Required	Description
listener	IMQTTListener	Yes	The message listener.

Example

MQTTHelper.registerMessageListener(listener);

Bluetooth tool

Common properties

BleConnectBean object

Property	Type	Required	Description
devId	String	Yes	The device ID.
directConnect	boolean	Yes	Indicates whether a direct connection is used.
level	int	Yes	The level.
scanTimeout	int	Yes	The scan timeout.
autoConnect	boolean	Yes	Indicates whether an automatic connection is used.
extInfo	ExtInfo	Optional	The additional information.

Connect to an offline device

Parameters

Parameter	Type	Required	Description
beans	List	Yes	The list of `BleConnectBean` objects.

Example

List<BleConnectBean> beans = new ArrayList<>();
BleConnectBean bleConnectBean = new BleConnectBean(
        "your_dev_id", // Set devId
        false, // Set directConnect
        0, // Set level
        30000, // Set scanTimeout
        false, // Set autoConnect
        null // (Optional) Set extInfo. Passing in null indicates no extInfo.
);
beans.add(bleConnectBean);
BleToolService.connectBleDevices(beans);

Disconnect a device

Example

List<BleConnectBean> beans = new ArrayList<>();
BleConnectBean bleConnectBean = new BleConnectBean(
        "your_dev_id", // Set devId
        false, // Set directConnect
        0, // Set level
        30000, // Set scanTimeout
        false, // Set autoConnect
        null // (Optional) Set extInfo. Passing in null indicates no extInfo.
);
beans.add(bleConnectBean);
BleToolService.disconnectBleDevices(beans);

Device management

Common properties

IDevice

Method	Description
getDeviceId(): String	The device ID.
getUUID(): String	The UUID of the device.
getName(): String	The name of the device.
getIcon(): String	The device icon.
getProductId(): String	The product ID.
getCategory(): String	The abbreviation of the product category. For example, `kg` for a switch and `cz` for a socket. For more information, see Standard Instruction Set.
getCapability(): Int	The networking capability. Valid values: `0`: Wi-Fi `1`: Wired `2`: GPRS `3`: NB-IoT `10`: Bluetooth `11`: Bluetooth mesh `12`: Zigbee `13`: Infrared `14`: Zigbee
getProtocolAttribute(): Long	The protocol support.
getTimezoneId(): String	The time zone of the device.
isCloudOnline(): Boolean	The connection status of the device on the internet.
isLocalOnline(): Boolean	The connection status of the device on the LAN.
isOnline(): Boolean	Indicates whether the device is online on the LAN or internet.
getLatitude(): String	The latitude of the device.
getLongitude(): String	The longitude of the device.
getDps(): Map<String, Any>	Get the data point (DP) of the device.
publishDps(dps: DpCommand, callback: IndustryCallBack)	Control a DP.
getSchemas(): Map<String, DpSchema>	Get the DP schema.
addDeviceListener(listener: IDeviceListener)	Set a device listener.
removeDeviceListener(listener: IDeviceListener)	Remove a device listener.
getWifiSignalStrength(callback: IndustryValueCallBack)	Get the Wi-Fi signal strength.
getDevAttribute(): Long	Device capability flags: Bit0: Pairing-free Bit1: DP 31 protocol query Bit2: Local linkage Bit3: Wi-Fi network scan Bit4: Google Local Home Bit5: Pegasus pairing Bit6: Device control over Bluetooth Bit7: Security alarm Bit8: Shared device Bit9: Sunrise/sunset-based schedule Bit10: Failover Bit11: OTA capability Bit12: Alternative Wi-Fi network Bit14: Tuya standard protocol Bit15: Custom protocol Bit16: Industry capability Bit17: OCPP protocol Bit18: EV charging industry protocol Bit19: Things data model
newOtaManager(): IDeviceOtaManager	Get the device OTA management instance.
newBackupManager(): IDeviceWifiBackupManager	The alternative Wi-Fi network. To check if this feature is supported, review the bit12 value returned by `getDevAttribute()`.
getMeta(): Map<String, Any>?	Call `getMeta()?.get("wifiEnable")` to check whether a device is activated in the cloud. This parameter applies to Bluetooth and Wi-Fi combo devices.

DpCommand object

Property	Type	Required	Description
publishMode	DpsPublishMode	Yes	The data transfer type.
dps	List	Yes	The DP data set.

Get device details

Load the device object by device ID.

Parameters

Parameter	Type	Required	Description
deviceId	String	Yes	The device ID.

Example

// Method 1:
DeviceService.load("deviceId", new IndustryValueCallBack<IDevice>() {
            @Override
            public void onSuccess(IDevice iDevice) {
                Log.d(TAG, "onSuccess: ");

            }

            @Override
            public void onError(int i, String s) {
                Log.d(TAG, "onError: " + s);

            }
        });

// Method 2:
IDevice device = DeviceService.device("deviceId")
if (device != null) {

}

Rename device

Parameters

Parameter	Type	Required	Description
deviceId	String	Yes	The ID of the target device.
newName	String	Yes	The new name of the device.
callback	IndustryCallBack	Yes	The callback for renaming a device.

Example

DeviceService.rename("deviceId", "newName", new IndustryCallBack() {
            @Override
            public void onSuccess() {
                Log.d(TAG, "onSuccess: ");
            }

            @Override
            public void onError(int i, String s) {
                Log.d(TAG, "onError: " + s);

            }
        });

Remove device

Parameters

Parameter	Type	Required	Description
deviceId	String	Yes	The ID of the target device.
callback	IndustryCallBack	Yes	The callback for removing a device.

Example

DeviceService.remove("deviceId", new IndustryCallBack() {
            @Override
            public void onSuccess() {
                Log.d(TAG, "onSuccess: ");
            }

            @Override
            public void onError(int i, String s) {
                Log.d(TAG, "onError: " + s);

            }
        });

Factory reset

Parameters

Parameter	Type	Required	Description
deviceId	String	Yes	The device ID.
callback	IndustryCallBack	Yes	The callback.

Example

DeviceService.resetFactory("deviceId", new IndustryCallBack() {
            @Override
            public void onSuccess() {
                Log.d(TAG, "onSuccess: ");
            }

            @Override
            public void onError(int i, String s) {
                Log.d(TAG, "onError: " + s);

            }
        });

Register device listener

IDevice listens for device information, including but not limited to:

The DP data.
The name of the device.
The online status of the device.

Parameters

Parameter	Description
listener	The listener for device status.

Example

iDevice.addDeviceListener(new IDeviceListener() {
    @Override
    public void onDpUpdate(String s, String s1) {
        Log.d(TAG, "onDpUpdate: ");
    }

    @Override
    public void onRemoved(String s) {
        Log.d(TAG, "onRemoved: ");
    }

    @Override
    public void onStatusChanged(String s, boolean b) {
        Log.d(TAG, "onStatusChanged: ");
    }

    @Override
    public void onNetworkStatusChanged(String s, boolean b) {
        Log.d(TAG, "onNetworkStatusChanged: ");
    }

    @Override
    public void onDevInfoUpdate(String s) {

    }
});

Remove device listener

Parameters

Parameter	Description
listener	Remove a listener for device status.

Example

iDevice.removeDeviceListener(listener);

Control device

Parameters

Parameter	Type	Required	Description
dpCommand	DpCommand	Yes	The DP command.
callback	IndustryCallBack	Yes	The success callback.

Example of creating dpCommand

DpCommand dpCommand = new DpCommand.Builder()
    .addDp("key","value")
    .publishMode(DpsPublishMode.AUTO)
    .build();

Example

iDevice.publishDps(dpCommand, new IndustryCallBack() {
                    @Override
                    public void onSuccess() {
                        Log.d(TAG, "onSuccess: ");
                    }

                    @Override
                    public void onError(int i, String s) {
                        Log.d(TAG, "onError: ");

                    }
                });

Exit page and destroy listener

API description

iDevice.newBackupManager().onDestroy();

Device firmware updates

Common properties

FirmwareUpgradeInfo object

Property	Type	Description
desc	String	The description of the update.
upgradeStatus	Int	The update status. `0`: No update available `1`: An update available `2`: Updating `5`: Wait for the device to wake up
version	String	The new version of the firmware.
currentVersion	String	The current version of the firmware.
timeout	Int	The timeout period.
upgradeType	Int	Types of updates `0`: Update notification `2`: Forced update `3`: Check for update
type	Int	Types of firmware update channel `0`: Main network module, Wi-Fi module, and Bluetooth module. `1`: Bluetooth module `2`: GPRS module `3`: Zigbee module `5`: 433 MHz module `6`: NB-IoT module `9`: MCU module `10` to `19`: Extended modules
typeDesc	String	The description of the firmware update channel.
lastUpgradeTime	Long	The last update time.
firmwareDeployTime	Long	The firmware deployment time.
fileSize	Long	The size of the firmware update. Unit: bytes.
controlType	Int	Indicates whether device control is allowed during the update. `YES`: The device can be used during the update. `NO`: The device cannot be used during the update.
upgradingDesc	String	The description shown when the firmware is being updated.
downloadingDesc	String	The description shown when the update is being downloaded.
remind	String	The description shown when the update verification fails.
canUpgrade	Boolean?	Indicates whether the update verification succeeds. `null`: No verification is required to start an update. `false`: The update verification fails, with the update being denied. You can show `remind` to inform the user about the failure. `true`: The update verification succeeds, with the update being accepted.
devType	Int	The type of the device. `0`: Ordinary device `1`: Low power device
waitingDesc	String	The description for waiting for the device to wake up.
upgradeMode	Int	The type of firmware update, available starting from v3.35.5. `0`: Generic firmware update `1`: PID-specific firmware update

DeviceUpgradeStatusBean object

Property	Type	Description
devId	String	The device ID.
firmwareType	int	The type of firmware.
statusText	String	The description of the status.
statusTitle	String	The title of the status.
progress	int	The progress. In certain conditions, the value might be less than `0`. If any, ignore this type of value.
status	DevUpgradeStatusEnum	The update status. `2`: Updating `3`: Update succeeded `4`: Update failed `5`: Wait for the device to wake up `6`: The update has been downloaded `7`: Update timeout `100`: The app is preparing, for example, connecting to a Bluetooth device, or downloading the update.
upgradeMode	Int	Firmware update modes `0`: Generic firmware update `1`: PID-specific firmware update, available starting from v3.35.5
errorMsg	String	The error message.
errorCode	Int	The error code returned on failure.

Get the update information

iDevice.newOtaManager().fetchFirmwareUpgradeInfo(new IndustryDataCallBack<List<FirmwareUpgradeInfo>>() {
    @Override
    public void onSuccess(List<FirmwareUpgradeInfo> firmwareUpgradeInfos) {
        Log.d(TAG, "onSuccess: ");
    }

    @Override
    public void onFailure(String s, String s1) {
        Log.d(TAG, "onFailure: ");
    }
});

Start update

Parameters

Parameter	Type	Description
upgradeInfoList	List	The update information.

Example

iDevice.newOtaManager().startOTA(upgradeInfoList);

Continue with update

Parameters

Parameter	Type	Description
isContinue	Boolean	Indicates whether to continue the update task.

Example

iDevice.newOtaManager().continueOTA(isContinue)

Cancel update

Parameters

Parameter	Type	Description
firmwareType	Int	The type of firmware.
callback	IndustryNormalCallback	The callback.

Example

iDevice.newOtaManager().cancelOTA(0, new IndustryNormalCallback() {
    @Override
    public void onSuccess() {
        Log.d(TAG, "onSuccess: ");
    }

    @Override
    public void onFailure(String s, String s1) {
        Log.d(TAG, "onFailure: ");
    }
});

Get update status

Example

iDevice.newOtaManager().fetchUpgradingInfo(new IndustryDataCallBack<DeviceUpgradeStatusBean>() {
    @Override
    public void onSuccess(DeviceUpgradeStatusBean deviceUpgradeStatusBean) {
        Log.d(TAG, "onSuccess: ");
    }

    @Override
    public void onFailure(String s, String s1) {
        Log.d(TAG, "onFailure: ");
    }
});

Listen for callback

Example

iDevice.newOtaManager().registerOTAListener(new IDeviceOtaListener() {
    @Override
    public void firmwareUpgradeStatus(DeviceUpgradeStatusBean deviceUpgradeStatusBean) {
        Log.d(TAG, "firmwareUpgradeStatus: ");
    }
});

Alternative network

You can call iDevice.getDevAttribute() & (1 << 12) to check whether a specific device supports the alternative network.

1: Support
0: Not support

Common properties

ConnectWifiInfoBean object

Property	Type	Description
devId	String	The device ID.
tId	String	The message ID.
ssid	String	The SSID of the Wi-Fi network.
signal	Int	The Wi-Fi signal strength.
network	Int	The network status.
version	Int	The protocol version.
hash	String	The hash value of the connected Wi-Fi network.

BackupWifiInfoListBean object

Parameters

Property	Type	Description
devId	String	The device ID.
tId	String	The message ID.
maxNum	String	The maximum number of SSIDs that the device can store.
backupList	MutableList	The list of alternative Wi-Fi networks. The type is `[BackupWifiInfoBean]`.

BackupWifiInfoBean object

Property	Type	Description
ssid	String	The SSID of the Wi-Fi network.
hash	String	The hash value of the Wi-Fi password.
passwd	String	The password of the Wi-Fi network.

BackupWifiResultBean object

Parameters

Property	Type	Description
devId	String	The device ID.
tId	String	The message ID.
ssid	String	The SSID of the Wi-Fi network.
resCode	Int	The response code.
ssidList	MutableList	The list of Wi-Fi SSIDs.

Query current Wi-Fi information

Parameters

Parameter	Type	Required	Description
callback	IndustryDataCallBack	Yes	The callback.

Example

iDevice.newBackupManager().fetchConnectWifiInfo(new IndustryDataCallBack<ConnectWifiInfoBean>() {
    @Override
    public void onSuccess(ConnectWifiInfoBean connectWifiInfoBean) {
        Log.d(TAG, "onSuccess: ");
    }

    @Override
    public void onFailure(String s, String s1) {
        Log.d(TAG, "onFailure: ");
    }
});

Query alternative Wi-Fi networks

Example

iDevice.newBackupManager().fetchBackupWifiInfoList(new IndustryDataCallBack<BackupWifiInfoListBean>() {
    @Override
    public void onSuccess(BackupWifiInfoListBean backupWifiInfoListBean) {
        Log.d(TAG, "onSuccess: ");

    }

    @Override
    public void onFailure(String s, String s1) {
        Log.d(TAG, "onFailure: ");

    }
});

Set the list of alternative Wi-Fi networks

Parameters

Parameter	Description
backupWifiList	The bean of the alternative Wi-Fi network.
callback	The callback.

Example

ArrayList<BackupWifiInfoBean> backupWifiList = new ArrayList<>();
                // Set the password of the added Wi-Fi network.
                BackupWifiInfoBean backupWifiBean = new BackupWifiInfoBean();
                backupWifiBean.setSsid("test1");
                backupWifiBean.setPasswd("12345678");
                backupWifiList.add(backupWifiBean);

                iDevice.newBackupManager().setBackupWifiInfoList(backupWifiList, new IndustryDataCallBack<BackupWifiResultBean>() {
                    @Override
                    public void onSuccess(BackupWifiResultBean backupWifiResultBean) {
                        Log.d(TAG, "onSuccess: ");
                    }

                    @Override
                    public void onFailure(String s, String s1) {
                        Log.d(TAG, "onFailure: ");
                    }
                });

Switch to a new Wi-Fi network

Parameters

Parameter	Type	Description
ssid	String	The name of the Wi-Fi network.
password	String	The password of the Wi-Fi network.
callback	IndustryDataCallBack	The callback.

Example

iDevice.newBackupManager().switchToTargetWifi("ssid", "password", new IndustryDataCallBack<SwitchWifiResultBean>() {
    @Override
    public void onSuccess(SwitchWifiResultBean switchWifiResultBean) {
        Log.d(TAG, "onSuccess: ");
    }

    @Override
    public void onFailure(String s, String s1) {
        Log.d(TAG, "onFailure: ");

    }
});

Switch to an alternative Wi-Fi network

Parameters

Parameter	Type	Description
hash	String	The hash value of the Wi-Fi password.
callback	IndustryDataCallBack	The callback.

Example

iDevice.newBackupManager().switchToBackupWifi("hash", new IndustryDataCallBack<SwitchWifiResultBean>() {
    @Override
    public void onSuccess(SwitchWifiResultBean switchWifiResultBean) {
        Log.d(TAG, "onSuccess: ");
    }

    @Override
    public void onFailure(String s, String s1) {
        Log.d(TAG, "onFailure: ");
    }
});

Prev DocSpace Service

Next DocChangelog