デバイスマネジメントライブラリ

概要

デバイスマネジメントライブラリは、ソフトウェアマネジメントや構成設定マネジメントなど、Things Cloudにおけるデバイスマネジメント活動に使用されるデータ構造を定義します。

データ構造はフラグメントとして表わされ、これらをマネージドオブジェクト、オペレーションおよび他のリソースの範囲内で使用することができます。フラグメントの概念について詳しくは、「Things Cloudのドメインモデル」をご覧ください。このセクションにはデバイス上でのオペレーションの実行プロセスや、オペレーション結果に応じたインベントリの更新に関する情報も記載されています。クライアントライブラリにおけるフラグメントの用法については、各クライアントライブラリ向けの開発者ガイドをご覧ください。

メタデータ

c8y_IsDevice

インベントリ内で「c8y_IsDevice」フラグメントが付与されているデバイスは、デバイスマネジメントに対応します。このフラグメントを有するデバイスのみ、デバイスマネジメント用ユーザーインターフェースに表示されます。

"c8y_IsDevice": {}

Device in Device Management

c8y_SupportedOperations

「c8y_SupportedOperations」は、特定のデバイス向けに利用可能なオペレーションをリストアップし、アプリケーションがこれらのオペレーションをトリガーできるようにします。例えば、サポート対象オペレーションリストに「c8y_Restart」が含まれる場合(下記参照)、デバイスマネジメント用ユーザーインターフェースの歯車アイコンの下に再起動ボタンが用意されます。

"c8y_SupportedOperations": [ "c8y_Restart" ]

Device supports restart

デバイスインフォメーション

c8y_Hardware

「c8y_Hardware」は、デバイスの基本ハードウェア情報、例えばメーカー名や製造番号などを格納します。多くの場合、ハードウェア製造番号はデバイスのボード表面またはデバイスのアセットタグに印刷されており、同一メーカーのすべてのデバイスの範囲内でデバイスを一意に識別できる状態になっています。

名称 種別 説明
model String デバイスのハードウェア型式のテキスト識別子
revision String ハードウェア改訂のテキスト識別子
serialNumber String デバイスのハードウェア製造番号
"c8y_Hardware": {
  "model": "BCM2708",
  "revision": "000e",
  "serialNumber": "00000000e2f5ad4d"
}

Hardware information

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

Firmware information

上記の例では、デバイスがバージョン「1.20140107-1」のファームウェアをインストールするようリクエストされています。デバイスは予めソフトウェアリポジトリの場所を設定済みですので、リクエストされたファームウェアイメージをダウンロードするには相対URL「31aab9856861b1a587e2094690c2f6e272712cb1」さえあれば大丈夫です。

c8y_SoftwareList

「c8y_SoftwareList」は、ソフトウェアの名称、バージョンおよびURLを定義するソフトウェアエントリのリストです。

名称 種別 説明
name String ソフトウェア名
version String ソフトウェアのバージョン識別子
url URI ソフトウェアをダウンロードする際の取得場所

インベントリにおいて、「c8y_SoftwareList」はデバイスに現在インストールされているソフトウェアコンポーネントを表わします。

オペレーションの要素として、「c8y_SoftwareList」はデバイスに対し、指示されたソフトウェアコンポーネントおよびバージョンがインストールされている状態を確保するようリクエストします。これは、「c8y_SoftwareList」に記載されていないソフトウェアを削除し、デバイスにまだインストールされていないソフトウェアをインストールし、異なるバージョンでインストールされているソフトウェアをアップグレードまたはダウングレードすべきであることを意味します。

ユーザーインターフェース経由でのソフトウェアインストールを可能にするには、「c8y_SoftwareList」を前述のサポート対象オペレーションリストに追加します。

"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」は、デバイスの内蔵モデムの機器識別情報(IMEI)など、基本的な接続性関連情報を保持します。この識別子はグローバルに一意であり、モバイルデバイスの識別に使用されることが多いです。

名称 種別 説明
imei String デバイス内蔵モデムの機器識別情報(IMEI)。
cellId String デバイスの現在の接続先であるモバイルネットワーク内でのセルの識別子。
iccid String 現在デバイスに装着されているSIMカードの識別情報(大抵、カードに印刷されています)。
"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

c8y_CellInfo

「c8y_CellInfo」は、最寄りの携帯電話基地局に関する詳細な情報を提供します。機能が有効化されている状態の場合、デバイスの位置がこのフラグメントに基づいて判定されることにより、GPS追跡を利用可能でない状況でのデバイスの消息を追跡することができます。

名称 種別 説明
radioType String この基地局の無線種別(任意)。
cellTowers Array 近隣の基地局に関する詳細情報。
cellTowers.radioType String この基地局の無線種別。すべてのcellTowersが同じradioTypeである場合、ルートJSON要素に直接加えてもよいです。(任意)
cellTowers.mobileCountryCode Number モバイルカントリーコード(MCC)。
cellTowers.mobileNetworkCode Number GSM、WCDMAおよびLTE向けのモバイルネットワークコード(MNC)。CDMAの場合はシステムID(SID)。
cellTowers.locationAreaCode Number GSM、WCDMAおよびLTE向けのロケーションエリアコード(LAC)。CDMAの場合はネットワークID。
cellTowers.cellId Number GSM、WCDMAおよびLTE向けのセルID(CID)。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_Configuration: デバイスのパラメータおよび初期設定を構成を可能とするテキスト構成フラグメントです。詳細については、ユーザーガイドのデバイスマネジメント下にあるデバイス詳細の設定 をご参照ください。
  • c8y_ConfigurationDump: 大容量アーカイブの構成設定。詳細についてはユーザーガイドのデバイスマネジメント下にあるデバイスデータ目メネジメントの設定スナップショット をご参照ください。
  • c8y_UploadConfigFile: 大容量構成設定ファイルのアップロード。詳細についてはユーザーガイドのデバイスマネジメント下にあるデバイスデータマネジメントの設定スナップショットに記載の「デバイスに設定スナップショットを適用する方法」をご覧ください。
  • c8y_DownloadConfigFile: 大容量構成設定ファイルのダウンロード。 詳細についてはユーザーガイドのデバイスマネジメント下にあるデバイスデータマネジメントの設定スナップショットに記載の「デバイススナップショットを取得する方法」をご覧ください。

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

Device configuration

c8y_ConfigurationDump

「c8y_ConfigurationDump」はデバイスのバイナリ構成ファイルの管理を許可する操作です。設定ダンプ、または設定スナップショットとは"c8y_ConfigurationDump"というタイプのマネージドオブジェクトです。

こちらが設定スナップショットのマネージドオブジェクトになります:

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

スナップショットより設定を適用するオペレーションです:

"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」は設定ファイルをバイナリとしてアップロードできるようにする操作です。設定ファイルをアップロードする時に使用されます。バイナリAPIはバイナリファイルにバイナリオブジェクトを添付するために使用されます。

  "c8y_UploadConfigFile":{}

c8y_DownloadConfigFile

「c8y_DownloadConfigFile」は設定ファイルをバイナリとしてダウンロードできるようにする操作です。バイナリAPIはバイナリファイルにバイナリオブジェクトを添付するために使用されます。

設定ファイルをダウンロードする操作の例:

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

備考: "c8y_DownloadConfigFile"操作は"c8y_ConfigurationDump"オブジェクトを配信します。 UIにスナップショット情報を表示させるには、このオブジェクトをCumulocityデバイス上で設定する必要があります。

c8y_SendConfiguration

ユーザーインターフェース経由での構成設定のリロードを可能にするには、「c8y_SendConfiguration」を前述のサポート対象オペレーションリストに追加します。

デバイスレポート

c8y_Battery

「c8y_Battery」は現在のバッテリー充電レベルを示します。メジャーメントの要素として使用されます。

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

c8y_SignalStrength

「c8y_SignalStrength」は、モデムのGSM受信に関する情報を提供します。これはメジャーメントの要素として使用され、読み取りは「rssi」と「ber」の2種類です。「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>> }

デバイスは、応答間隔内に全くメッセージを送信していない場合、使用不可状態と見なされます。応答間隔には-32768から32767までの値を指定でき、範囲外の値は範囲の境界に合わせて縮小されます。そのようなデバイスは使用不可状態(下記参照)とされ、使用不可状態アラームが発動されます。応答間隔がゼロ分の状態のデバイスは保守中と見なされます。保守中のデバイスについては、アラームは発動されません。「c8y_RequiredAvailability」を格納していないデバイスはモニタリング対象外です。

c8y_Availability

Things Cloudによって計算された可用性情報は、デバイスの「c8y_Availability」と「c8y_Connection」、2通りのフラグメントに保存されます。

"c8y_Availability": { "lastMessage": "2013-05-21...", "status": "AVAILABLE" },
"c8y_Connection": {"status":"CONNECTED"}
名称 種別 説明
lastMessage Date デバイスがThings Cloudへ最後にメッセージを送信した時間。
status String 現在の状態。以下のいずれか:AVAILABLE、MAINTENANCE、UNAVAILABLE。

以下のメッセージは、デバイスの最後のメッセージタイムスタンプを更新することになります。

  • イベント、メジャーメントまたはアラームの作成(任意のデバイスがソースである場合)
  • 空のPUTリクエストまたはIDのみのリクエスト、すなわち{}または{"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>>
    ...
}

使用可能状態への更新は、遅延を伴って発生する可能性があります。

Availability

データが全く更新されない状態でデバイスを使用可能としてフラグ付けしたい場合、「ping」を送信するとよいです。「ping」は、単に空の更新メッセージをデバイスに送信する(すなわち中身が空のリクエストをマネージドオブジェクトにPUTする)だけで行うことができます。

c8y_ActiveAlarmsStatus

現在「有効」および「認知」状態のアラームの件数が、フラグメント「c8y_ActiveAlarmsStatus」に保存されます。

"c8y_ActiveAlarmsStatus": {
    "warning": 1
}

Alarm status

その他

c8y_Restart

デバイスを再起動する場合、「c8y_Restart」フラグメントを伴うオペレーションが送信されます。ユーザーインターフェース内で「restart」ボタンを使えるようにするには、「c8y_Restart」を前述のサポート対象オペレーションリストに追加します。

"c8y_Restart": {}

Restart button

c8y_Command

デバイスと双方向型セッションを行う場合、「c8y_Command」フラグメントを使用します。このフラグメントがデバイスのサポート対象オペレーションリストに含まれていれば、「Shell」タブが表示されます。「Shell」タブを使用すると、コマンドを任意のデバイス特異的構文でデバイスに送信することができます。コマンドは「text」のプロパティでデバイスに送信されます。

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

特定のコマンドの結果を伝達するため、デバイスは「result」プロパティを追加します。

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

c8y_LogfileRequest

ログファイルを送信するようデバイスにリクエストし、そのログファイルをThings Cloudのログビューアーで見ることができます。デバイスがログビューイングに対応している場合、「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」は、フィルタリング後にThings Cloudへ送信されるべき行数の上限を設定します。

デバイスはそうしたリクエストを受信すると、基準に従ってログファイルをフィルタリングし、結果を1つのファイルにまとめてバイナリ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"
}