开发者中心

设备管理库

概述

概述

设备管理库定义在QuarkIoE中用于设备管理活动(如软件管理和配置管理)的数据结构。

数据结构表示为可以在管理对象, 操作和其他资源内使用的片段。 关于片段概念的更多信息可以在"QuarkIoE领域模型"中找到。 同一部分还包含有关在设备上运行操作和根据操作结果更新托管对象过程的信息。 有关客户端库中片段的使用, 请参阅相应客户端库的开发人员指南。

元数据

c8y_IsDevice

在托管对象中用c8y_IsDevice片段标记的设备支持设备管理。 只有具有此片段的设备才会显示在设备管理用户界面中。

"c8y_IsDevice": {}
            

设备管理中的设备

c8y_SupportedOperations

c8y_SupportedOperations列出可用于特定设备的操作,以便应用程序可以触发操作。 例如,如果支持的操作列表包含"c8y_Restart"(见下文)), 则设备管理用户界面中的齿轮下方将提供重新启动按钮。

"c8y_SupportedOperations": [ "c8y_Restart" ]
            

设备支持重新启动

设备信息

c8y_Hardware

c8y_Hardware包含设备的基本硬件信息, 例如制造商和序列号。 通常, 硬件序列号印刷在设备的板上或设备上的资产标签上, 以在同一制造商的所有设备内唯一标识设备。

名称 类型 描述
model String 设备硬件型号的文本标识符。
revision String 硬件修订版本的文本标识符。
serialNumber String 设备的硬件序列号。
"c8y_Hardware": {
              "model": "BCM2708",
              "revision": "000e",
              "serialNumber": "00000000e2f5ad4d"
            }
          
硬件信息
c8y_Firmware

c8y_Firmware包含有关设备固件的信息。 在托管对象中, "c8y_Firmware"表示设备上当前安装的固件。 作为操作的一部分, "c8y_Firmware"请求设备安装指示的固件。 要通过用户界面启用固件安装, 请将"c8y_Firmware"添加到上述支持的操作列表中。

名称 类型 描述
name String 固件名称。
version String 硬件的版本标识符。
url URI 从中下载固件的位置。
"c8y_Firmware": {
            "name": "raspberrypi-bootloader",
            "version": "1.20140107-1",
            "url": "31aab9856861b1a587e2094690c2f6e272712cb1"
          }
        

固件信息

在上面的示例中,请求设备安装固件版本"1.20140107-1"。 该设备具有预先配置的软件库位置, 因此它只需要相对URL"31aab9856861b1a587e2094690c2f6e272712cb1"来下载所请求的固件映像。

c8y_SoftwareList

c8y_SoftwareList包含软件组件到其对应版本的映射。 在托管对象中, "c8y_SoftwareList"表示设备上当前安装的软件组件。

作为操作的一部分, "c8y_SoftwareList"请求设备确保安装所指示的软件组件和版本。 这意味着应该删除未包含在"c8y_SoftwareList"中的软件, 应该安装未安装在设备上的软件, 在设备上以不同的版本安装软件应该分别升级。 根据设备的安装机制, 版本实际上可能是指向特定下载位置的URL或URI。

要通过用户界面启用软件安装,请将"c8y_SoftwareList"添加到上述支持的操作列表中。

"c8y_SoftwareList": {
         "jetty-io": "jetty-io-7.6.8.v20121106.jar",
         "rest-representation": "rest-representation-4.6.0.jar",
         ...
       }
     
软件信息
c8y_Configuration

c8y_Configuration允许设备基于文本的配置。 大多数设备支持可以使用此机制显示和编辑的文本配置文件。 在托管对象中, "c8y_Configuration"表示设备上当前活动的配置。 作为操作的一部分, "c8y_Configuration"请求设备使所发送的配置成为当前活动的。 要通过用户界面启用配置, 请如上所述将"c8y_Configuration"添加到支持的操作列表。

名称 类型 描述
config String 以设备特定格式的文本, 表示设备的配置。
"c8y_Configuration": {
      "config": "#Tue Jul 02 16:10:36 UTC 2013\nc8y.log.alarmLevel=ERROR\nc8y.modem.signalPolling=10000\nc8y.log.eventLevel=INFO"
    }
  
设备配置
c8y_Mobile

c8y_Mobile包含基本的连接性相关信息, 例如设备中调制解调器(IMEI)的设备标识符。 此标识符是全局唯一的, 通常用于标识移动设备。

名称 类型 描述
imei String 调制解调器在设备中的设备标识符(IMEI)。
cellId String 设备当前连接的移动网络中的蜂窝标识符。
iccid String 当前在设备中的SIM卡的标识符(通常打印在卡上)。
"c8y_Mobile": {
    "imei": "358901048995390",
    "cellId": "15DFAC",
    "iccid": "89430301901300001342"
  }

其他可能值: 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

调制解调器信息

c8y_CellInfo

c8y_CellInfo提供有关最近基站详细信息。 当功能被激活时, 基于该片段确定设备的位置, 以便当GPS跟踪不可用时跟踪设备的行踪。

名称 类型 描述
radioType String 此基站的无线电类型。(可选)
cellTowers Array 有关邻近基站的详细信息。
cellTowers.radioType String 此基站的无线电类型。 如果所有基站具有相同的无线电类型, 可以直接放在根JSON元素中。(可选)
cellTowers.mobileCountryCode Number 移动国家代码(MCC).
cellTowers.mobileNetworkCode Number 用于GSM, WCDMA和LTE的移动网络代码(MNC)。 CDMA的SystemID(sid)。
cellTowers.locationAreaCode Number 用于GSM, WCDMA和LTE的位置区域代码(LAC)。 CDMA的网络ID。
cellTowers.timingAdvance Number 可用时此基站的定时提前值。(可选)
cellTowers.signalStrength Number 该信号塔的信号强度, 单位为dBm。(可选)
cellTowers.primaryScramblingCode Number 用于WCDMA的主扰码和用于LTE的物理CellId。(可选)
cellTowers.serving Number 如果蜂窝正在服务, 请使用0/1指定。 如果未指定, 则假定第一个蜂窝正在服务。(可选)
"c8y_CellInfo": {
  "radioType": "gsm",
  "cellTowers": [{
  "mobileCountryCode": 240,
  "mobileNetworkCode": 1,
  "locationAreaCode": 3012,
  "cellId": 11950
}]
}

设备报告

c8y_Battery

c8y_Battery显示当前电池电量。 它用作测量值的一部分。

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

c8y_SignalStrength提供关于调制解调器的GSM接收的信息。 它用作测量值的一部分, 包含两个读数:rssiber。 "rssi"是以dBm表示的接收信号强度, 范围从-113 dBm(最差)到-51 dBm(最佳)。 "ber"是以%为单位的误码率。

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

信号强度报告

设备可用性

c8y_RequiredAvailability

可以通过向设备添加"c8y_RequiredAvailability"片段来监视设备的可用性:

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

在响应时间间隔内未发送任何消息的设备被视为不可用。 这样的设备被标记为不可用(见下文), 并且出现不可用报警。 响应间隔为零分钟的设备被认为处于维护状态。 当设备处于维护状态时, 不会产生报警。 不监视不包含"c8y_RequiredAvailability"的设备。

c8y_Availability

由QuarkIoE计算的可用性信息存储在设备的片段中: "c8y_Availability"和"c8y_Connection"。

"c8y_Availability": { "lastMessage": "2013-05-21...", "status": "AVAILABLE" },
  "c8y_Connection": {"status":"CONNECTED"}
名称 类型 描述
lastMessage Date 设备将最后一条消息发送到QuarkIoE的时间。
status String 当前状态, AVAILABLE, MAINTENANCE, UNAVAILABLE之一。

以下消息更新设备的最后一个消息时间戳:

  • 创建事件, 测量值或报警(给定设备作为源)
  • 更新设备本身(使用给定id)发送空PUT请求或只使用id请求, 如{} 或 {"id":...}

受监控的设备具有以下状态之一:

名称 描述
CONNECTED 建立设备推送连接。
AVAILABLE 设备未通过设备推送连接, 但在所需的响应间隔内发送了一条消息。
MAINTENANCE "responseInterval"设置为0;设备处于维护状态。
UNAVAILABLE "responseInterval"大于0并且设备不是AVAILABLE或CONNECTED。
c8y_UnavailabilityAlarm

当设备不可用时发送报警类型 "c8y_UnavailabilityAlarm":

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

可用性状态的更新可能会延迟。

可用性

要将设备标记为可用, 而不更新任何数据, 可以发送"ping"。 可以通过简单地向设备发送空更新消息(即,对具有空内容的管理对象的PUT请求)来执行"ping"。

c8y_ActiveAlarmsStatus

当前活动和已确认报警的数量存储在片段"c8y_ActiveAlarmsStatus"中。

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

报警状态

杂项

c8y_Restart

要重新启动设备,将发送带有"c8y_Restart"片段的操作。 要在用户界面中启用"重新启动"按钮,请将"c8y_Restart"添加到上述支持的操作列表。

"c8y_Restart": {}

重新启动按钮

c8y_CommunicationMode

为了将命令作为文本消息发送到设备, 设备必须进入SMS模式。 为了指示它支持SMS模式, 设备需要添加具有mode属性"SMS"的片段"c8y_CommunicationMode"。

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

详情请参阅通过SMS控制设备.

c8y_Command

要使用设备执行交互式会话, 请使用"c8y \ _Command"片段。 如果此片段在设备的支持操作列表中, 将显示选项卡"Shell"。 使用"Shell"选项卡,用户可以以任意的设备特定语法向设备发送命令。 该命令被发送到设备的属性"text":

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

要传达特定命令的结果, 设备将添加一个属性 "result":

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

如果您想为您的设备类型发布示例命令, 请联系support@quarkioe.com。

c8y_LogfileRequest

您可以请求设备发送日志文件, 并在QuarkIoE的日志查看器中查看日志文件。 如果设备支持日志查看, 则需要向其支持的操作添加"c8y_LogfileRequest"。 此外,它需要指定设备上可用的日志:

c8y_SupportedLogs: ["syslog", "dmesg"]

日志文件请求结构如下:

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

请求中的参数定义要在发送之前应用于日志的过滤条件:

  • "logFile" 表示要选择的日志文件。
  • "dateFrom" 和 "dateTo" 指定要发送的日志文件中的日志条目的时间范围。
  • "searchText" 提供需要出现在日志条目中的文本。
  • "maximumLines" 给出在过滤后应发送到QuarkIoE的行数的上限。

当设备接收到此类请求时, 它会根据条件过滤日志文件, 并将结果作为文件发送到二进制数据API。 然后将此文件的链接放入日志文件请求:

"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"
}