Cloud Services API ReferenceIoT CoreDevice Management

Device Management

Last Updated on : 2023-11-23 03:17:55download

Device management helps you centrally manage and monitor IoT devices, and handle devices more efficiently and reliably. You can view device information, freeze or unfreeze devices, get device freezing status, delete devices, restore factory settings, modify device properties, transfer devices, view device logs, and perform over-the-air (OTA) updates.

Concepts

Term	Description
Property	Refers to the basic properties of a device, including the device name, icon, and latitude and longitude information. The data format of latitude and longitude is `lon:lat`.
Freeze	After a device is frozen, you cannot tap to enter the device panel of the device list on the mobile app homepage. A frozen icon appears on the device. You cannot control the frozen device in the cloud, but the data reporting to the cloud or control over LAN will not be affected.
Unfreeze	The specified device resumes service, and a frozen icon and prompt disappear. After you refresh the panel on the mobile app, the device works properly.
Frozen status	Query whether a device is frozen. A frozen device cannot be controlled in the cloud, and shows a frozen icon on the app.
Delete a device	Delete the specified device based on the device ID. Users cannot query or control a deleted device. However, if the device ID remains unchanged after the device is reactivated, the configured linkage rules, timer, and other rules will take effect again.
Restore to factory defaults	The specified device is deleted and local data is cleared. You cannot query or control the device that has been restored to factory settings. Meanwhile, the configured linkage rules, timer, and other rules will be cleared.
Transfer a device	A user transfers an authorized device from the current space to another authorized space. If other users have permissions of the target space, they can view and operate this device.
Device logs^{Note 1}	The type of logs: Online: A device goes online. Offline: A device goes offline. Activation: A device is activated. Reset: A device is reset. Instruction sending: Send an instruction to a device. For example, operate the device by using the mobile app. Firmware update: The device firmware is updated. Data point reporting: For example, a device proactively reports its state, such as the energy consumption of an electricity meter. Semaphore: Signal strength, remaining memory, and more. Restart: A device is restarted. Timer: A timer set by users.
Data reporting logs^{Note 1}	Queries and shows the logs of reporting the specified data points. For example, the energy consumption of the electric meter is reported regularly. You can query the historical data reported by the device based on a data point.
Get available firmware updates	Check all channels ^{Note 2} of the device for available updates. When an update is available, the value of `upgradeStatus` is `1` in the returned result. You can invoke the device update API to start the process.
Trigger device firmware to update	Trigger the device to start the firmware update, and an update notification will be sent to the device asynchronously. After receiving the update notification, the device starts to update the firmware.
Get the progress of a device firmware update	When the update is in progress, you can get the current update progress. The maximum value of progress is `100`.

^{Note 1} The log storage period is seven days by default. If you want to store your logs for a long time, you can subscribe to the log storage service to customize the storage period and the stored device log type.
^{Note 2} A device might have multiple hardware modules, such as Wi-Fi module and MCU. Channels are used to distinguish specific hardware modules. You can only update specific modules as you want.

API list

API name	API endpoint
Get Status Reporting Log	GET:/v2.0/cloud/thing/{device_id}/report-logs
Get Update Progress	GET:/v2.0/cloud/thing/{device_id}/firmware/{channel}/progress
Query Device Details in Bulk	GET:/v2.0/cloud/thing/batch
Delete Device	DELETE:/v2.0/cloud/thing/{device_id}
Get Update Information	GET:/v2.0/cloud/thing/{device_id}/firmware
Query Device Details	GET:/v2.0/cloud/thing/{device_id}
Confirm Start of Update	POST:/v2.0/cloud/thing/{device_id}/firmware/{channel}
Get Device State	GET:/v2.0/cloud/thing/{device_id}/state
Get Operation Log	GET:/v2.0/cloud/thing/{device_id}/logs
Modify Basic Properties	POST:/v2.0/cloud/thing/{device_id}/attribute
Freeze/Unfreeze Device	POST:/v2.0/cloud/thing/{device_id}/freeze
Transfer Device	POST:/v2.0/cloud/thing/{device_id}/transfer
Restore Factory Defaults	POST:/v2.0/cloud/thing/{device_id}/reset

Limits

Item	Limits
The maximum number of devices that can be queried at one time by calling the API of querying device details in bulk	20
The maximum number of entries returned per page	100

Example

Photovoltaic (PV) energy storage systems are becoming more and more popular for home use. After this system is purchased and installed, home users can use solar energy to generate and store electricity for use at night or in bad weather.

The system is large in size and requires professional installation. The dealer sends field engineers to the user’s home to install the devices and set up a network. Also, the dealer can coordinate tasks and follow up the status by using an industry mobile app for sellers. Field engineers can log in to the app to view work order tasks and their status.

The device needs to be paired with the industry mobile app for sellers, and then delivered to the user’s home, so as to better know the device operation and after-sales services. The user can operate the device by using the mobile app for users. Therefore, the device cannot be directly paired with the user’s home.

Best practice

For more information, see IoT Core Device Management.

Prev DocQuery Parent-Child Relationship

Next DocQuery Devices in Project