デバイス管理ライブラリ

概要

デバイス管理ライブラリは、ソフトウェア管理や構成設定マネジメントなど、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"
}

他の可能な値は: 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」は、最寄りの携帯電話基地局に関する詳細な情報を提供します。機能が有効化されている状態の場合、デバイスの位置がこのフラグメントに基づいて判定されることにより、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_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にスナップショット情報を表示させるには、このオブジェクトをThings Cloudデバイス上で設定する必要があります。

c8y_SendConfiguration

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

ネットワークの管理

c8y_Network

デバイス管理アプリケーションのネットワークタブは、c8y\_Networkフラグメントからデータを受け取ります。 さらに、c8y\_Networkフラグメントには、c8y\_LANc8y\_WANc8y\_DHCPなどの追加のネストされたフラグメントが含まれます。 使用できるフラグメントに制限はありません。

以下はc8y\_Network フラグメントを使用したコード例です。

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

備考: 上記のコード例が要件を満たしていない場合は、カスタムフラグメントを追加できます。

デバイスレポート

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

Signal strength report

デバイスの可用性

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

以下のメッセージでは、デバイスの最後のメッセージタイムスタンプを更新します。

モニタリング対象デバイスは、以下のいずれかの状態に該当します:

名称 説明
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": {
    "minor": 1,
    "major": 3
}

Alarm status

その他

c8y_Restart

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

"c8y_Restart": {}

Restart button

c8y_CommunicationMode

コマンドをテキストメッセージとしてデバイスに送信するには、デバイスをSMSモードにする必要があります。 SMSモードをサポートするには、デバイスに「c8y_CommunicationMode」というフラグメントを「SMS」のモードプロパティへ追加する必要があります。

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

あなたのデバイスタイプに応じたサンプルコマンドを公開したい場合は、サポート にお問い合わせください。

c8y_DeviceTypes

同じデバイスタイプを共有するデバイスのサブセット用のサンプルコマンドを公開するには、「c8y_DeviceTypes」というフラグメントを追加する必要があります。

"c8y_DeviceTypes": ["deviceSubsetType"]

フラグメントが存在する場合、デバイスタイプのサンプルコマンドのリストが、「c8y_DeviceTypes」のサンプルコマンドで拡張されます。 ユーザーインタフェースから作成された新しいサンプルコマンドは、「c8y_DeviceTypes」のコンテキストで作成されます。

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
}

リクエストに含まれるパラメータは以下の通り、送信される前のログに適用されるフィルタリング基準を定義します。

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