Device management library

Overview

The device management library defines the data structures that are used in Cumulocity IoT for device management activities such as software management and configuration management.

The data structures are expressed as fragments that can be used inside managed objects, operations and other resources. More information on the fragment concept can be found in the Section “Cumulocity IoT’s domain model”. The same section also contains information on the process of running operations on devices and updating the inventory according to the result of the operation. For the usage of fragments in client libraries, see the developer’s guides for the respective client library.

Metadata

c8y_IsDevice

A device marked in the inventory with a c8y_IsDevice fragment supports device management. Only devices with this fragment appear in the device management user interface.

"c8y_IsDevice": {}

Device in Device Management

c8y_SupportedOperations

c8y_SupportedOperations lists the operations that are available for a particular device, so that applications can trigger the operations. For example, if the supported operations list contains “c8y_Restart” (see below), a restart button will be available under the dropdown menu in the top menu bar.

"c8y_SupportedOperations": [ "c8y_Restart" ]

Device supports restart

Device information

c8y_Hardware

c8y_Hardware contains basic hardware information for a device, such as make and serial number. Often, the hardware serial number is printed on the board of the device or on an asset tag on the device to uniquely identify the device within all devices of the same make.

Name Type Description
model string A text identifier of the device’s hardware model.
revision string A text identifier of the hardware revision.
serialNumber string The hardware serial number of the device.
"c8y_Hardware": {
  "model": "BCM2708",
  "revision": "000e",
  "serialNumber": "00000000e2f5ad4d"
}

Hardware information

c8y_Firmware

c8y_Firmware contains information on a device’s firmware. In the inventory, “c8y_Firmware” represents the currently installed firmware on the device. As part of an operation, “c8y_Firmware” requests the device to install the indicated firmware. To enable firmware installation through the user interface, add “c8y_Firmware” to the list of supported operations as described above.

Name Type Description
name string Name of the firmware.
version string A version identifier of the hardware.
url string A URI linking to the location to download the firmware from.
"c8y_Firmware": {
  "name": "raspberrypi-bootloader",
  "version": "1.20140107-1",
  "url": "31aab9856861b1a587e2094690c2f6e272712cb1"
}

Firmware information

In the example above, the device is requested to install firmware version “1.20140107-1”. The device has a pre-configured software repository location, hence it only needs the relative URL “31aab9856861b1a587e2094690c2f6e272712cb1” to download the requested firmware image.

c8y_SoftwareList

c8y_SoftwareList is a List of software entries that define the name, version and url for the software.

Name Type Description
name string Name of the software.
version string A version identifier of the software.
url string A URI linking to the location to download the software from.

In the inventory, “c8y_SoftwareList” represents the currently installed software components on the device.

As part of an operation, “c8y_SoftwareList” requests the device to ensure that the indicated software components and versions are installed. This means that software not contained in “c8y_SoftwareList” should be removed, software not installed on the device should be installed and software installed in a different version on the device should be upgraded respectively downgraded.

To enable software installation through the user interface, add “c8y_SoftwareList” to the list of supported operations as described above.

"c8y_SoftwareList": [
  {
    "name": "Software A",
    "version": "1.0.1",
    "url": "www.some-external-url.com"
  },
  {
    "name": "Software B",
    "version": "2.1.0",
    "url": "mytenant.cumulocity.com/inventory/binaries/12345"
  }
]

Software information

c8y_Mobile

c8y_Mobile holds basic connectivity-related information, such as the equipment identifier of the modem (IMEI) in the device. This identifier is globally unique and often used to identify a mobile device.

Name Type Description
imei string The equipment identifier (IMEI) of the modem in the device.
cellId string The identifier of the cell in the mobile network that the device is currently connected with.
iccid string The identifier of the SIM card that is currently in the device (often printed on the card).
"c8y_Mobile": {
  "imei": "358901048995390",
  "cellId": "15DFAC",
  "iccid": "89430301901300001342"
}

Other possible values are: c8y_Mobile.imsi c8y_Mobile.currentOperator c8y_Mobile.currentBand c8y_Mobile.connType c8y_Mobile.rssi c8y_Mobile.ecn0 c8y_Mobile.rcsp c8y_Mobile.mnc c8y_Mobile.lac c8y_Mobile.msisdn

Modem information

c8y_CellInfo

c8y_CellInfo provides detailed information about the closest mobile cell towers. When the functionality is activated, the location of the device is determined based on this fragment, in order to track the device whereabouts when GPS tracking is not available.

Name Type Description
radioType string The radio type of this cell tower. (Optional)
cellTowers array Detailed information about the neighbouring cell towers.
cellTowers.radioType string The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType. (Optional)
cellTowers.mobileCountryCode Number The Mobile Country Code (MCC).
cellTowers.mobileNetworkCode Number The Mobile Noetwork Code (MNC) for GSM, WCDMA and LTE. The SystemID (sid) for CDMA.
cellTowers.locationAreaCode Number The Location Area Code (LAC) for GSM, WCDMA and LTE. The Network ID for CDMA.
cellTowers.cellId Number The Cell ID (CID) for GSM, WCDMA and LTE. The Basestation ID for CDMA.
cellTowers.timingAdvance Number The timing advance value for this cell tower when available. (Optional)
cellTowers.signalStrength Number The signal strength for this cell tower in dBm. (Optional)
cellTowers.primaryScramblingCode Number The primary scrambling code for WCDMA and physical CellId for LTE. (Optional)
cellTowers.serving Number Specify with 0/1 if the cell is serving or not. If not specified, the first cell is assumed to be serving. (Optional)
"c8y_CellInfo": {
  "radioType": "gsm",
  "cellTowers": [{
    "mobileCountryCode": 240,
    "mobileNetworkCode": 1,
    "locationAreaCode": 3012,
    "cellId": 11950
  }]
}

Configuration management

In this section, fragments related to configuration management are listed.

The following fragments can be observed:

c8y_Configuration

c8y_Configuration permits a text-based configuration of the device. Most devices support a text-based system configuration file that can be presented and edited using this procedure. In the inventory, “c8y_Configuration” represents the currently active configuration on the device. As part of an operation, “c8y_Configuration” requests the device to switch the transmitted configuration to the currently active one. To enable configuration through the user interface, add “c8y_Configuration” to the list of supported operations as described above.

Name Type Description
config String A text in a device-specific format, representing the configuration of the device.
"c8y_Configuration": {
  "config": "#Tue Jul 02 16:10:36 UTC 2013\nc8y.log.alarmLevel=ERROR\nc8y.modem.signalPolling=10000\nc8y.log.eventLevel=INFO"
}

Device configuration

c8y_ConfigurationDump

c8y_ConfigurationDump is an operation that permits to manage binary configuration files of the device. The configuration dump, or configuration snapshot, is a managed object that has the type “c8y_ConfigurationDump”.

Here is an example of a managed object representing a configuration snapshot:

"id" : "650041722",
"name" : "Device Name",
"type" : "c8y_ConfigurationDump",
"description" : "Upload by 165711155000082 at 05/04/16 08:14:07",
"url" : "https://yourtenant.cumulocity.com/inventory/binaries/binaryId"

An operation example of applying a configuration from a snapshot:

"deviceId":"678101855",
"id":"680189603",
"c8y_DownloadConfigFile":{
  "c8y_ConfigurationDump":{
    "id":"651201036"
  },
  "url":"https://yourtenant.cumulocity.com/inventory/binaries/651201031"
},
"description":"Apply configuration snapshot"

c8y_UploadConfigFile

c8y_UploadConfigFile is an operation that permits to upload configuration files as binaries. It is used when the device is uploading a configuration file. Binary API is used in order to attach the managed object to the binary file.

  "c8y_UploadConfigFile":{}

c8y_DownloadConfigFile

c8y_DownloadConfigFile is an operation that permits to download configuration files as binaries. The binary file is attached to the managed object using binary API.

An operation example of downloading a configuration file:

  "c8y_DownloadConfigFile":{
    "url":"<download url>"
}

Info: The “c8y_DownloadConfigFile” operation delivers a “c8y_ConfigurationDump” object. This object must be configured on the Cumulocity IoT device in order to make the UI display the snapshot information.

c8y_SendConfiguration

To enable reloading configuration through the user interface, add “c8y_SendConfiguration” to the list of supported operations as described above.

Network management

c8y_Network

The Network* tab in the Device Management application receives its data from the c8y\_Network fragment. Furthermore, the c8y\_Network fragment contains additional nested fragments such as c8y\_LAN, c8y\_WAN and c8y\_DHCP . There is no limit to the fragments that you may use.

Below is an example code with the c8y\_Network fragment:

{
"c8y_Network":{
  "c8y_LAN:{
  	"netmask":"255.255.255.0",
	"ip":"192.168.128.1",
	"name:"br0",
	"enabled":1,
	"mac":"00:60:64:dd:a5:c3"
  },
  "c8y_WAN":{
 	"password":"user-password",
	"simStatus":"SIM OK",
	"authType":"chap",
	"apn":"example.apn.com",
	"username":"test"
  },
  "c8y_DHCP"":{  
	"dns2":"null",
	"dns1":"null",
	"domainName":"null",
	"addressRange":{
	  "start":"192.168.128.100", "end":"192.168.128.199"},
	"enabled":1
	}
  }
}

Info: If the code example above does not meet your requirements, you can add custom fragments.

Device reports

c8y_Battery

c8y_Battery shows the current battery fill level. It is used as part of a measurement.

"c8y_Battery": {
  "level": { "value": 23, "unit": "%" }
}

c8y_SignalStrength

c8y_SignalStrength provides information on the GSM reception of the modem. It is used as part of a measurement and contains two readings: rssi and ber. “rssi” is the received signal strength in dBm, ranging from -113 dBm (worst) to -51 dBm (best). “ber” is the bit error rate in %.

"c8y_SignalStrength": {
  "rssi": { "value": -53, "unit": "dBm" },
  "ber": { "value": 0.14, "unit": "%" }
}

Signal strength report

Device availability

c8y_RequiredAvailability

Devices can be monitored for availability by adding a “c8y_RequiredAvailability” fragment to the device:

"c8y_RequiredAvailability": { "responseInterval": <<time in minutes>> }

Devices that have not sent any message in the response interval are considered unavailable. The response interval can have a value between -32768 and 32767 and any values out of range will be shrink to the range borders. Such devices are marked as unavailable (see below) and an unavailability alarm is raised.

Devices with responseInterval <= 0 are considered to be under maintenance. No alarm is raised while a device is under maintenance.

Devices that do not contain “c8y_RequiredAvailability” are not monitored.

c8y_Availability

The availability information computed by Cumulocity IoT is stored in fragments: “c8y_Availability” and “c8y_Connection” of the device.

"c8y_Availability": { "lastMessage": "2013-05-21...", "status": "AVAILABLE" },
"c8y_Connection": {"status":"CONNECTED"}
Name Type Description
lastMessage Date The time when the device sent the last message to Cumulocity IoT.
status String The current status, one of AVAILABLE, MAINTENANCE, UNAVAILABLE.

The following messages update the last message timestamp of a device:

A monitored device has one of following statuses:

Name Description
CONNECTED A device push connection is established.
MAINTENANCE “responseInterval” is set to 0; the device is under maintenance.
UNAVAILABLE “responseInterval” is larger than 0 and the device is neither AVAILABLE nor CONNECTED.

Info: If a device is not connected via device push, but a message was sent within the required response interval, c8y_Availability can still have the status AVAILABLE, even if c8y_Connection does not have the status CONNECTED.

c8y_UnavailabilityAlarm

The alarm sent when a device becomes unavailable is of type “c8y_UnavailabilityAlarm”:

{
    ...
    "type" : "c8y_UnavailabilityAlarm",
    "text" : "No communication with device since <<last activity time>>",
    "status" : "active",
    "severity" : "major",
    "source" : <<device id>>
    ...
}

Updates to the availability status may occur with a delay.

Availability

To flag a device as available without updating any data, a “ping” can be sent. The “ping” can be carried out by simply sending an empty update message to the device (i.e., a PUT request to the managed object with empty content).

c8y_ActiveAlarmsStatus

The number of currently active and acknowledged alarms is stored in a fragment “c8y_ActiveAlarmsStatus”.

"c8y_ActiveAlarmsStatus": {
    "minor": 1,
    "major": 3
}

Alarm status

Miscellaneous

c8y_Restart

To restart a device, an operation with a “c8y_Restart” fragment is sent. To enable a “restart” button in the user interface, add “c8y_Restart” to the list of supported operations as described above.

"c8y_Restart": {}

Restart button

c8y_CommunicationMode

In order to send commands as text messages to devices, the devices must be put into SMS mode. To indicate that it supports SMS mode, a device needs to add the fragment “c8y_CommunicationMode” with a mode property of “SMS”.

"c8y_CommunicationMode": {
    "mode": "SMS"
}

For more information, please refer to Device control via SMS.

c8y_Command

To carry out interactive sessions with a device, use the “c8y_Command” fragment. If this fragment is in the list of supported operations for a device, a tab “Shell” will be shown. Using the “Shell” tab, the user can send commands in an arbitrary, device-specific syntax to the device. The command is sent to the device in a property “text”:

"c8y_Command": {
    "text": "get uboot.sn"
}

To communicate the results of a particular command, the device adds a property “result”:

"c8y_Command": {
    "text": "get uboot.sn",
    "result": "165711141901401"
}

Please contact support if you would like to publish sample commands for your device type.

c8y_DeviceTypes

To publish sample commands for a subset of devices sharing the same device type, the c8y_DeviceTypes fragment must be added:

"c8y_DeviceTypes": ["deviceSubsetType"]

If the fragment is present, the list of sample commands for a device type will be extended with the sample commands for the c8y_DeviceTypes. New sample commands created from the user interface will be created in the context of the c8y_DeviceTypes.

c8y_LogfileRequest

You can request a device to send a log file and view the log file in Cumulocity IoT’s log viewer. If a device supports log viewing, it needs to add “c8y_LogfileRequest” to its supported operations. In addition, it needs to specify which logs are available on the device:

"c8y_SupportedLogs": ["syslog", "dmesg"]

A log file request has the following structure:

"c8y_LogfileRequest": {
    "logFile": "syslog",
    "dateFrom": "2016-01-27T13:45:24+0100",
    "dateTo": "2016-01-28T13:45:24+0100",
    "searchText": "sms",
    "maximumLines": 1000
}

The parameters in the request define filtering criteria to be applied to the log before sending it:

When the device receives such a request, it filters the log file according to the criteria and sends the result as a file to the Binary API. It then puts a link to this file into the log file request:

"c8y_LogfileRequest": {
    "logFile": "syslog",
    "dateFrom": "2016-01-27T13:45:24+0100",
    "dateTo": "2016-01-28T13:45:24+0100",
    "searchText": "sms",
    "maximumLines": 1000,
    "file": "http://...cumulocity.com/inventory/binaries/30761423"
}