The Device Mirror is a virtual representation of the device in ARTIK cloud services. It stores three types of properties for the device type: Server Properties, System Properties, and Device Properties. When you view properties in the Developer Dashboard or make API calls to get properties, you are viewing the current values of the properties in the Device Mirror.
Server Properties and System Properties exist only on the Device Mirror (in the cloud). Device Properties exist on both the physical device and the Device Mirror. It is possible to access Device Properties directly on the device by performing a device management task.
Accessing device management
To access device management features, a user must belong to the organization that owns the device type.
|Device management feature||Example actions||Required role|
|Manage configuration options||Define Device Management Manifest, enable Device Properties||Administrator, developer|
|Properties||Set Server Property values, Query all properties||Administrator|
|Tasks||Create and view tasks||Administrator|
|Firmware images||Upload images, execute OTA updates||Administrator, developer|
Managing your organization describes how to change user roles.
Three types of properties
In the Developer Dashboard, device management options are listed under the name of the device type.
ARTIK cloud services recognize three types of properties.
- Server Properties are properties defined by the device type owner, such as serial number, model, description, and firmware version.
- System Properties are read-only properties provided by ARTIK cloud services that provide additional information to the device manufacturer.
- Device Properties use LWM2M to read, write, and execute property values to and from the device.
A device's properties are different from its fields. Device fields are described in the Manifest and refer to data produced by an end user's interaction, like turning on a light or capturing a heart rate.
Server properties are properties that are defined by the device manufacturer. In the Developer Dashboard, an administrator can define up to 40 Server Properties in a Device Management Manifest by navigating to Device Management for a device type. If no properties have been defined, you will see the following:
Click the "Add Server Properties" button. Here a property name, data type, and unit of measurement (if applicable) must be entered. You may pick from a list of standard properties or create custom properties. A description of the property is optional but recommended.
The Developer Dashboard also allows organization administrators to read, write, and query properties stored on the Device Mirror. This is done on a device type's corresponding Device Management page. Each device card displays the properties alongside their values. By clicking the edit button on the upper-right, you can edit the values of the properties.
The search bar can be used to filter the list with three types of properties. In the below image, we are filtering the list by
serialNumber, a Server Property we have defined.
Once the Device Management Manifest is defined, devices can call the REST API to set their Server Property values in ARTIK cloud services. To authenticate the device, use either the device token or an OAuth token with the device's owner logged into an application owned by the same organization as the device type.
System Properties are read-only properties assigned by ARTIK cloud services to a device that provide additional information to the device manufacturer. They include:
- Device ID
- Creation date of the device on ARTIK cloud services
- Device presence parameters
Device Properties use LWM2M to read, write, and execute property values to and from the device. These are discussed in Manage devices using LWM2M.
After a device type owner creates a device type in ARTIK cloud services, they can create Server Properties and enable Device Properties for devices of that device type. After that, there are two ways to manage devices:
- Write, read, delete, and query properties using the Developer Dashboard or API calls. These are performed on the Device Mirror.
- Run tasks on a device to manage Device Properties.
The remainder of this article discusses the first type of device management, which is on the Device Mirror. Manage devices using LWM2M discusses Device Properties and tasks in depth.
A connection status is reported for devices that have made a connection to ARTIK cloud services using a supported protocol. It can be viewed in a device type's Device Management page, which lists the devices that you have added to your account.
The Cards view displays each device as follows:
The device card shows the connection status of the device and the timestamp the device was last connected.
Connection status can be Active, Inactive, or Never Connected.
A device has Active connection status when it is connected to ARTIK cloud services using one of the following protocols.
An Inactive status indicates that the device has previously connected with the protocol. Never Connected status indicates that the device has not been connected to ARTIK cloud services.
A REST connection will never display as Active, because it is not persistent.
Device Management API reference
Use the Device Management APIs to manage properties programmatically. The APIs operate on the Device Mirror. They are documented in the API reference.
To perform operations on a physical device, you need to create device management tasks, which are discussed here.