Device model

The device model describes the metadata and management characteristics of a device and is stored in the IBM Watson™ IoT Platform service device database, the master source of device information.

Applications and managed devices can send updates, including location changes or the progress of a firmware update to the device database. As soon as these updates are received by the Platform Service, the database is updated and the information is made available to applications.

Note: Except for the device management extension, the entire device model is available for both managed and unmanaged devices. However, an unmanaged device cannot directly update its device model in the database.

Device identification

Every device has a typeId and a deviceId attribute. Typically, the typeId represents the model of your device, whereas the deviceId can represent its serial number. In your Platform Service organization, the combination of typeId and deviceId must be unique for each device.

In addition to these attributes, the Platform Service constructs another identifier for each device. This identifier is called the clientId. The clientId is based on your organizationId and on the typeId and deviceId values of the device. The clientId provides a way to uniquely identify an individual device. The characters that can be used in these identifiers are restricted so that they are compatible with communication protocols and REST APIs.

The following optional device identifiers can also be used:

• deviceInfo.manufacturer
• deviceInfo.serialNumber
• deviceInfo.model
• deviceInfo.deviceClass
• deviceInfo.description

For more information about the identifiers and descriptions of their comparative identifiers in other device management standards, see Attributes.

Identifiers and device types

Every device that is connected to the Platform Service is associated with a device type. Device types are groups of devices that share characteristics or behaviors.

A device type has a set of attributes. When a device is added to the Platform Service, the attributes in its device type are used as a template. If the device has a value, that value is used. If the device does not have a value, the device type value is used. For example, the device type might have a value for the deviceInfo.fwVersion attribute, which reflects the firmware version at the time of manufacture. This value is copied from the device type into the devices when they are added. When a device is added, if the deviceInfo.fwVersion value exists it is not overwritten.

When an attribute of a device type is updated, only new devices that are registered inherit the modifications that are made to the device type template.

Attributes

The following table shows the list of attributes that can apply to devices in the Platform Service. Italicized attributes can also apply to device types.

Key:

• API : Can be updated by using APIs
• DMA : Can be updated by using Device Management Agent
• R: Read-only
• W: Write and read
• A: Append

Extended attributes

In addition to core attributes listed previously in the Attributes section, the following attributes are also treated as extensions to the core device model. Simple queries about the device return information from the core device model, but not the extensions. Information from the extensions must be specifically requested.

Diagnostics extension

The diagnostics attributes are optional and are only present for devices that have error log information. These attributes are intended for diagnosing device problems, not for troubleshooting connectivity to the Platform Service. The amount of information that is stored in diagnostic attributes can be large and must therefore be specifically queried.

Diagnostic log information is stored as an array of entries. Each entry consists of a message, an indication of severity, a timestamp, and an optional byte-array of data. You can append entries by using an API. However, appending entries can cause earlier entries to be lost to keep the size of the diagnostic logs manageable.

Location extension

The location attributes are optional and are only present for devices that have location information. The location information is stored separately to allow the use of storage mechanisms that are better suited to dynamic information which can be important when information is updated frequently, for example for a mobile device.

For solutions that place significant importance on frequent location updates, it is expected that the location is treated as part of the device's event payload, which enables higher update rates, simpler historical storage, and easier data analysis.

Device management extension

The management attributes are only present for managed devices. When a managed device becomes dormant it becomes unmanaged, and the mgmt. attributes are deleted. The mgmt. attributes are set by the Platform Service as a result of processing device management requests. These attributes cannot be directly written by using the API.

Devices have a management lifecycle, which is defined by their status as managed devices. The device management agent on the device is responsible for sending a Manage Device request by using the device management protocol. To deal with defunct devices in large device populations, a managed device can be set to send a Manage Device request regularly. A managed device becomes dormant if this request is not sent to Platform Service for a specified period. To facilitate this functionality, the Manage Device request has an optional lifetime parameter. When the Platform Service receives a Manage Device request that has the lifetime parameter set, it calculates the time before another Manage Device request is required and stores it in the mgmt.dormantDateTime attribute.