デバイス管理ライブラリ

概要

デバイス管理ライブラリは、ソフトウェア管理や構成設定マネジメントなど、Things Cloudにおけるデバイス管理に使用されるデータ構造を定義します。 データ構造はフラグメントとして表され、これらをマネージドオブジェクト、オペレーションおよび他のリソースの範囲内で使用することができます。フラグメントの概念について詳しくは、「Things Cloudコンセプト」の「Things Cloudのドメインモデル」をご覧ください。

次のセクションでは、デバイスの最も重要な機能、そのマネージドオブジェクト、およびそれらに対応するすべてのフラグメントについて説明します。Things Cloud UI、データベースで管理されているデバイスオブジェクト、およびデバイスとの通信内容との関係について説明します。

REST API を使用して Things Cloud の機能を公開する方法の詳細については、Things Cloud OpenAPI 仕様 をご覧ください。

さらに、SmartREST の詳細と、次のセクションで説明するすべての SmartREST テンプレートの完全なリストについては、SmartREST をご覧ください。

デバイス管理を開始するには、デバイス管理アプリケーションの デバイス メニューの すべてのデバイス タブを開きます。リスト内のデバイスをクリックして、特定デバイスの「デバイスの詳細」を開きます。さまざまなタブとそれぞれに関する特定の情報が表示されます。

このリストは、デバイスフラグメントを介して操作できます。つまり、表示されるタブは、デバイスがサポートする機能によって異なります。これは主に、 c8y_SupportedOperations というフラグメントで操作されます。このフラグメントの配列に格納された内容に基づいて、タブやボタンなどの機能が有効になります。例えば、c8y_SupportedOperations フラグメントに c8y_Firmwareが含まれていれば、デバイスの詳細ページでファームウェアタブが表示され、デバイスはファームウェアオブジェクトを管理することができるようになります。

c8y_SupportedOperations フラグメント

c8y_SupportedOperations フラグメントには、以下のフラグメントを追加することが可能です。

一般的なコンセプト

機能

デバイスは、独自のマネージドオブジェクトの c8y_SupportedOperations フラグメントを使用して、サポートされている機能を通知できます。フラグメント自体は文字列の配列です。このフラグメントは、次のセクションで説明する特定のユース ケースに対する意味を持つ組込み操作、またはカスタム操作が含まれる場合があります。

PUT /inventory/managedObjects/<deviceId>

{
    "c8y_SupportedOperations": [
        "c8y_Restart",
        "c8y_Network"
    ]
}

いくつかの機能は、同様のコンセプトを持つ独自の c8y_Supported<...> フラグメントを導入しています。これらのフラグメントを使用すると、デバイスは特定の種類のログファイルまたは構成を処理する機能を通知することができます。

SmartREST例

114 静的テンプレートは、デバイスがサポートされている操作を通知するために使用できます。

114,c8y_Restart,c8y_Configuration,c8y_SoftwareList

現在のステータスの伝達

デバイスは、現在のステータスを Things Cloud に伝達する役割を担います。ステータスは通常、デバイス自体のマネージドオブジェクトで伝達されます。Things Cloud は、機能ごとに特定のフラグメントを提供します。デバイスは、ローカル状態の変更を検出するたびにこのデータを更新する必要があります。

実際には、デバイスが起動時、ローカル状態の変更を要求された場合、および外部の変更が検出される場合に、サポートされているすべての機能に関するローカル状態を公開する必要があることを意味します。

オペレーション処理

オペレーションは常にステータス PENDING で作成されます。デバイスは、ライフサイクル内のさまざまなステータスにオペレーションを移動する役割を担います。オペレーション処理を開始する前に、デバイスエージェントはそのステータスを EXECUTING に更新する必要があります。処理が完了した後、デバイスは結果に応じてオペレーションのステータスを SUCCESS または FAILED に設定する必要があります。

SmartREST 2.0

Things Cloud は、オペレーション ステータスを操作するための静的テンプレート 501、502、および 503 を提供します。これらのテンプレートは、オペレーションタイプを入力パラメータとして受け取り、常に先行するステータスの中で最も古いオペレーションを更新します。保留中のオペレーションが複数ある場合、特定のオペレーションを更新対象にすることはできません。このため、すべてのオペレーションをデバイスに到着した順に処理することをお勧めします。

オペレーション処理中のエラー処理

オペレーション処理中にエラーが発生した場合、デバイスはオペレーションのステータスを FAILED に設定し、エラーの理由をできるだけ説明する必要があります。これには、オペレーションが完全に期待通りに完了するのを妨げる予期しないエラー状態または予想されるエラー状態が含まれます。複数の異なるステップを持つ操作の 1 つのステップのみが失敗した場合でも、オペレーション全体を FAILED と見なす必要があります。

エラーが発生する前に発生したローカル状態の変更をロールバックする必要があるかどうかは、デバイスとそのユースケース次第です。オペレーションが失敗した後に状態の変更が残っている場合、デバイスはこの変更された状態を Things Cloud に伝える必要があります。

冪等性なケース

デバイスがすでに存在する状態を要求するオペレーションを受け取った場合、そのオペレーションをどのように処理するかはデバイス次第です。例えば、すでに存在するソフトウェアパッケージをインストールするようにデバイスに要求された場合です。通常、デバイスエージェントではこのようなケースを処理する方法として、スキップ、実行、失敗の 3 つがあります。すでにインストールされているソフトウェアパッケージの場合、次のオプションを選択することができます。

1. パッケージがすでにインストールされていると見なし、要求された状態がすでに存在するためインストールをスキップする
2. パッケージの再インストールを含め、通常通り処理を実行する
3. 要求された状態は、コマンドが誤った前提条件の下で作成されたことを示している可能性があるため、操作を失敗させる

理想的なオプションは、ユースケースと具体的なオペレーションによって異なります。どのオプションが選択されているかに関係なく、デバイスはローカル状態と Things Cloud と通信されていることが一貫していることを確認する必要があります。

アラーム

アラーム タブは、常にすべてのデバイスに表示されます。その内容は、デバイスから報告されたアラーム ステータスと、Analyticsやスマート ルールなどの他のソースで埋められています。デバイスはそれらが発生した際に Things Cloud でアラームを発生させます。 アラームの状態が解決されたら、デバイスは作成されたアラームのステータスを CLEARED に更新する必要があります。

アラームの発生

デバイスはいつでもアラームを発生させることができます。通常、アラームはデバイス環境の問題のステータスを通知するために使用されます。

POST /alarm/alarms

{
   "source": {
       "id": "4801"
   },
   "type": "c8y_TemperatureAlarm",
   "text": "CPU temperature too high",
   "severity": "MAJOR",
   "time": "2021-10-07T12:00:00.000Z"
}

上記の必須パラメータに加えて、デバイスはアラーム ステータスに関してより詳細なカスタム フラグメントをアラームに含めることもできます。

SmartREST 例

Things Cloud には、デバイスの基本的なアラーム管理のための静的 SmartREST テンプレートがいくつか用意されています。異なる重要度のために 301 から 304 までのメッセージID が設定されています。

302,c8y_TemperatureAlarm,"CPU temperature too high"

アラームのクリア

デバイスは、ローカル アラーム ステータスが解決されたことを検出すると、アラームをクリアする必要があります。これは、アラームステータスをCLEAREDに更新することによって実行されます。

PUT /alarm/alarms/<alarmId>

{
   "status": "CLEARED"
}

SmartREST例

306 静的テンプレートは、指定されたタイプのアクティブアラームをクリアするために用意されています。

306,c8y_TemperatureAlarm

クリティカルアラーム

デバイスが重大度クリティカルのアラームを発生させると、このアラームがアクティブである間、デバイスは使用不可と見なされます。稼働率 タブの集計された稼働率の概要には、この時間がオフラインとして反映されます。

デバイスは、ユースケースを遂行するデバイスの能力に影響を与えるアラームステータスに限り、重要度「クリティカルアラーム」を使用する必要があります。

子デバイス

子デバイス タブには、すべての子デバイスのリストが表示されます。デバイスに子デバイスが割り当てられている場合にのみ使用できます。

子デバイスを親デバイスに割り当てる

デバイスを紐づけるには、親デバイスは、子デバイスの ID を含む次のリクエストをインベントリ API にPOSTする必要があります。

POST /inventory/managedObjects/<deviceId>/childDevices

{
   "managedObject": {
      "id": "28067400"
   }
}

SmartREST例

既存のデバイスに子デバイスを追加するには、接続されたデバイスを接続し、子デバイス作成テンプレートを呼び出す必要があります。

101,uniqueChildId,myChildDevice,myChildType

子デバイスのゲートウェイ操作

エージェントマーカーフラグメント com_cumulocity_model_Agent を子デバイスではなく親デバイスで使用することで、デバイスを子デバイスの接続ゲートウェイとして効果的に宣言します。子デバイスは Things Cloud に直接接続されていませんが、デバイスとその統合を通してデータを送受信します。

この場合、子デバイスのオペレーションは、接続された親デバイスに配信されます。親デバイスは、含まれているデバイス ID またはその他の情報に基づいて、アドレス指定された子デバイスを判断する必要があります。そして、コマンドを正しい子デバイスに転送する必要があります。

Things Cloud の組み込みの静的 SmartREST 応答テンプレートには、対象となる子デバイスを決定するための最初のパラメータとして、常にデバイス識別子が含まれています。以下は、デバイス識別子が強調表示されたc8y_Restart オペレーションの 510 静的レスポンステンプレートの例です。

510,DeviceSerial

カスタム応答テンプレートも、最初のパラメータとして対象となるデバイスの外部IDを含んでいます。そちらにも同様の仕組みを実装することをお勧めします。

構成

構成 タブでは、デバイス構成に 3 つの異なる形式を使用できます。

• テキストベースの構成
• レガシーファイルベースの構成
• 型指定されたファイルベースの構成

これらはすべて、デバイスが現在の設定をプラットフォームにアップロードし、ユーザーが新しい設定をデバイスにインストールするという類似のコンセプトに従っています。 このタブは、デバイスが利用可能なフォーマットのサポートを知らせたときに表示されます。

テキストベースの構成

構成の最も基本的な形式は単純なテキストベースの構成です。ここでは、構成は文字列として直接保存され、転送されます。この形式は、マイクロコントローラベースのデバイスなど、人間が読める小さな構成ファイルのみに使用することをお勧めします。

デバイスの現在の構成状態は、デバイス自体のマネージドオブジェクト内の c8y_Configuration フラグメントで通信されます。これには、すべての制御文字を文字列として含む完全な構成が含まれています。エンコーディングが適切に行われるように特別な注意を払う必要があります。Things Cloud は UTF-8 文字をサポートしていますが、JSON ペイロードは JSON 仕様、SmartREST ペイロードは SmartREST 仕様 に従ったエスケープが必要な場合があります。

転送データ量とデバイスのリソースを節約するため、オンデマンドでのみ現在の構成をアップロードすることをお勧めします。デバイスが現在の構成をプラットフォームにアップロードするために用意されたオペレーションは、以下の通りです。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Configuration": {
       "config": "c8y.url.http=https://<tenantId>.je1.thingscloud.ntt.com\nc8y.url.mqtt=mqtt.je1.thingscloud.ntt.com\n"
   }
}

現在のテキスト構成をアップロードする

c8y_SupportedOperations に c8y_SendConfiguration を含むデバイスの場合、構成タブには、デバイスから Things Cloud に構成をアップロードするためのボタンが用意されています。このボタンをクリックすると、c8y_SendConfiguration が作成されます。

{
   "c8y_SendConfiguration": {}
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. c8y_Configuration フラグメントを使用して、現在の構成を独自のマネージドオブジェクトにアップロードする
3. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

c8y_SendConfiguration 操作に使用できる組み込みの静的応答テンプレートはありません。デバイスは、この機能を実装するためにカスタム テンプレートを作成する必要があります。このようなテンプレートとその使用がどのように機能するかについて、例を次に示します。

テンプレートの作成
11,100,,c8y_SendConfiguration,deviceId

オペレーションの受信：

1. 上記で作成したカスタムテンプレートを使用して c8y_SendConfiguration オペレーションを受信する
   100,DeviceSerial,4801
2. オペレーションのステータスをEXECUTINGに設定する
   501,c8y_SendConfiguration
3. 静的テンプレートを使用して現在の構成状態をアップロードする 113,"c8y.url.http=https://<tenantId>.je1.thingscloud.ntt.com\nc8y.url.mqtt=mqtt.je1.thingscloud.ntt.com\n"
4. オペレーションのステータスを SUCCESSFULに設定する
   503,c8y_SendConfiguration

テキスト構成のインストール

構成のインストールをサポートするデバイスは、c8y_SupportedOperationsに c8y_Configuration を追加することで、通信することができます。構成 タブはユーザーが設定した構成をデバイスに送信するためのボタンを提供します。その結果、このアクションにより、デバイスのマネージドオブジェクトで見つかったのと同じフラグメント署名を持つ c8y_Configuration オペレーションが作成されます。

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. ネストされたconfigプロパティに含まれる構成を c8y_Configuration フラグメントでインストールし、適用する
3. デバイスのマネージドオブジェクトの c8y_Configuration フラグメントを更新する
4. オペレーションのステータスを SUCCESSFULに設定する

SmartREST例

513 静的応答テンプレートは、 c8y_Configuration オペレーションを受信するために使用できます。

1. c8y_Configuration オペレーションを受信する
   511,DeviceSerial,"c8y.url.http=https://<tenantId>.je1.thingscloud.ntt.com\nc8y.url.mqtt=mqtt.je1.thingscloud.ntt.com\n"
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_Configuration
3. 含まれている構成をインストールして適用する
4. c8y_Configuration フラグメントを更新する
   113,"c8y.url.http=https://<tenantId>.je1.thingscloud.ntt.com\nc8y.url.mqtt=mqtt.je1.thingscloud.ntt.com\n"
5. オペレーションのステータスを SUCCESSFULに設定する
   503,c8y_Configuration

レガシーファイルベースの構成

構成をファイルとして管理するデバイスは、レガシーファイルベースの構成を使用して基本的な形を実現できます。新しいデバイス統合では、より用途が広いため、代わりに型指定されたファイルベースの構成を実装することをお勧めします。

この方法では、構成をバイナリ ファイルとして格納および転送します。

現在のレガシー構成をアップロードする

デバイスは、 c8y_SupportedOperationsにc8y_UploadConfigFile を追加することで、現在の構成を Things Cloud にアップロードするためのサポートを通知できます。これにより、構成 タブにある デバイスから新しいスナップショットを取得 ボタンが有効になります。これをクリックすると、デバイスに対して c8y_UploadConfigFile オペレーションが生成されます。

{
   "c8y_UploadConfigFile": {}
}

構成をアップロードする場合、デバイスは最初に構成ファイルを Things Cloud インベントリバイナリにアップロードしてから、インベントリ内に c8y_ConfigurationDump タイプのマネージドオブジェクトとして構成リポジトリのエントリを作成する必要があります。このオブジェクトには、アップロードしたばかりのファイルへのリンクが含まれている必要があります。このエントリは、ユーザーがリポジトリで目的の構成を見つけられるように、わかりやすい名前と説明で作成することをお勧めします。

POST /inventory/managedObjects

{
   "name": "myDevice configuration",
   "description": "Uploaded by myDevice on 2021-09-15T12:00:00+0200",
   "url": "https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/154702",
   "type": "c8y_ConfigurationDump"
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. 構成ファイルを Things Cloud のインベントリ バイナリにアップロードする
3. 構成リポジトリのエントリを作成する
4. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

520 静的応答テンプレートがこの機能で使用できます。

1. c8y_UploadConfigFile オペレーションを受信する
   520,DeviceSerial
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_UploadConfigFile
3. REST を使用したインベントリバイナリ API へ構成をアップロードする
4. REST を使用したインベントリに構成リポジトリのエントリを作成する
5. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_UploadConfigFile

レガシー構成のインストール

構成をリモートでインストールできるデバイスは、c8y_SupportedOperationsに c8y_DownloadConfigFile を追加して、これを知らせることができます。次に、 構成 タブに 構成をデバイスに送信 ボタンが表示されます。クリックすると、デバイスの c8y_DownloadConfigFile オペレーションが作成されます。

{
   "c8y_DownloadConfigFile": {
       "url": "https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/9100",
       "c8y_ConfigurationDump": {
           "id": "9200"
       }
   }
}

指定されたURLから構成をダウンロードしインストールした後、デバイスは独自のマネージドオブジェクトで現在インストールされている構成を参照する必要があります。これは、ネストされた c8y_ConfigurationDump フラグメント全体をデバイス自体のマネージドオブジェクトに転送することで行われます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_ConfigurationDump": {
       "id": "9200"
   }
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. 指定したURLから構成ファイルをダウンロードする
3. 構成ファイルをインストールする
4. デバイスのマネージドオブジェクトに現在インストールされている構成ダンプを更新する
5. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

521 静的応答テンプレートがこの機能で使用できます。:

1. c8y_DownloadConfigFile オペレーションを受信する
   521,DeviceSerial,https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/9100
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_DownloadConfigFile
3. 指定した URL から構成をダウンロードする
4. 構成ファイルをインストールする
5. オペレーションのステータスを SUCCESSFUL に設定し、現在インストールされている c8y_ConfigurationDump フラグメントをそれとなく設定する
   503,c8y_DownloadConfigFile

型指定されたファイルベースの構成

デバイス構成を管理する最も用途の広い方法は、型指定されたファイルベースの構成です。ここでは、デバイスは複数の構成ファイルを同時に管理できます。型指定されたファイル構成は、c8y_SupportedConfiguration フラグメントをデバイス自体のマネージドオブジェクトに追加することによって、デバイスに対してアクティブ化されます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_SupportedConfigurations": [
       "agent_conf",
       "ssh_conf"
   ]
}

Things Cloud では、構成のタイプを検証したり、さらに処理したりすることはありません。プラットフォームの観点からは、これらは単純な文字列です。これらのタイプ文字列を構成ファイルに関連付けることは、デバイス エージェントの役割です。

SmartREST例

c8y_SupportedConfiguration フラグメントは、静的テンプレート119を使用してアップロードできます。
119,agent_conf,ssh_conf

現在の構成ファイルをアップロードする

レガシー構成と同様に、 c8y_UploadConfigFile を c8y_SupportedOperations に追加することで、型指定された構成のアップロードが通知されます。この場合、ボタンをクリックすると、対象となる構成タイプを追加パラメータとして、非常に似た c8y_UploadConfigFile オペレーションが作成されます。

{
   "c8y_UploadConfigFile": {
       "type": "agent_conf"
   }
}

次に、デバイスは構成の種類と同じ種類のイベントを作成する必要があります。Things Cloud では、イベントがデバイスに自動的に関連付けられ、含まれている古いイベント (およびそのバイナリ添付ファイル) は保持ルールを使用して自動的にクリーンアップできるため、レガシーファイルベースの構成のようにインベントリではなく、ここでイベントを使用します。

POST /event/events

{
   "source": {
       "id": "4801"
   },
   "type": "agent_conf",
   "time": "2021-09-15T15:57:41.311Z",
   "text": "agent_conf upload requested"
}

アップロードしたばかりのイベントに構成ファイルを添付するには、Event Attachments API を使用する必要があります。ファイルは、multipart/form-data リクエストを使用して添付されます。

POST /event/events/<eventId>/binaries

Host: https://<TENANT_DOMAIN>
Authorization: <AUTHORIZATION>
Accept: application/json
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="object"

{ "name": "agent.conf", "type": "text/plain" }
--boundary
Content-Disposition: form-data; name="file"; filename="agent.conf"
Content-Type: text/plain

c8y.url.http=https://<tenantId>.je1.thingscloud.ntt.com
c8y.url.mqtt=mqtt.je1.thingscloud.ntt.com
--boundary--

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. 構成タイプのイベントを作成する
3. 構成ファイルをイベントに添付する
4. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

Things Cloud は、型指定された c8y_UploadConfigFile オペレーションのための 526 静的 SmartREST テンプレートを提供します。

1. 型指定された c8y_UploadConfigFile オペレーションを受信する
   526,DeviceSerial,agent_conf
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_UploadConfigFile
3. REST API を使用した config タイプのイベントを作成する
4. REST API を使用してターゲットの構成ファイルをイベントに添付する
5. オペレーションのステータスをSUCCESSFUL に設定する
   503,c8y_UploadConfigFile

構成ファイルのインストール

型指定された構成のインストールもレガシー構成と類似の動作を行います。デバイスのc8y_SupportedOperations に c8y_DownloadConfigFileを追加すると、 構成をデバイスに送信 ボタンの可用性が制御されます。クリックすると、構成タイプを含むc8y_DownloadConfigFileオペレーションが作成されます。

{
   "c8y_DownloadConfigFile": {
       "type": "agent_conf",
       "url": "https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/156719"
   }
}

デバイスが構成をダウンロードしてインストールしたとき、デバイス自体のマネージドオブジェクトにある特定タイプの現在インストールされている構成を更新する必要があります。これは、 c8y_Configuration_<config type> フラグメントをデバイス自体のマネージドオブジェクトに追加することで行われます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Configuration_agent_conf": {
       "name": "agent_conf",
       "time": "2021-09-15T15:47:13.721Z",
       "type": "agent_conf",
       "url": "https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/156719"
   }
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. 含まれているURLから構成ファイルをダウンロードする
3. 構成ファイルをインストールする
4. デバイスの現在インストールされている構成を、デバイス自体のマネージドオブジェクトにある型指定された構成フラグメントで更新する
5. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

524 静的なSmartREST応答テンプレートは、型指定された c8y_DownloadConfigFile オペレーションに使用でき、120静的テンプレートは、現在の構成をアップロードするために用意されています。

1. 型指定された c8y_UploadConfigFile operation を受信する
   524,DeviceSerial,https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/156719,agent_conf
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_DownloadConfigFile
3. 含まれているURLから構成ファイルをダウンロードする
4. 対象の構成タイプとして構成をインストールする
5. 現在インストールされている構成を設定する
   120,agent_conf,https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/156719,agent_conf.txt,2021-09-15T15:47:13.721Z
6. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_DownloadConfigFile

接続

接続 タブは、サードパーティの SIM 管理プラットフォームと統合され、Things Cloud のデバイス管理内で SIM 管理機能を提供します。次のすべての条件が満たされた場合にデバイスのタブが表示されます。

1. 接続マイクロサービスがサブスクライブされ、構成されている
2. デバイス管理オブジェクトには、MSISDN または ICCID プロパティが設定された c8y_Mobile フラグメントが含まれている
3. デバイスによって参照される SIM は、テナント用に構成された SIM 管理プロバイダーによって管理される

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Mobile": {
       "msisdn": "380561234567",
       "iccid": "89100423481F445593U"
   }
}

構成されている接続プロバイダーに応じて、MSISDN または ICCID を使用して、デバイスに存在する SIM を識別できます。常に両方を c8y_Mobile フラグメントに含めることをお勧めします。 c8y_Mobile フラグメントに関連付けられるモバイル接続関連のプロパティは他にも多数ありますが、接続管理に関連するのは MSISDN または ICCID のみです。

SmartREST例

111 静的テンプレートは、デバイスがモバイル情報を通信するために提供されています。

111,1234567890,8930000000000000459,54353

デバイスの可用性

デバイスの可用性 タブには、デバイスの可用性と接続ステータスが表示されます。これを実現するには、デバイスは、デバイス自体のマネージドオブジェクトの c8y_RequiredAvailability フラグメントを使用して、必要な間隔を通信する必要があります。このアクションにより、デバイスの可用性と接続の監視がアクティブになります。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_RequiredAvailability": {
       "responseInterval": 15
   }
}

通常、デバイスはプラットフォームへの最初の接続時に既定値で必要な間隔を一度だけ設定する必要があります。その後の変更はプラットフォームユーザーに任せることができます。

SmartREST例

117静的テンプレートは、SmartREST接続デバイスに必要な可用性を設定するために提供されます。このテンプレートは、既存の必要な可用性構成を上書きしないため、デバイスの起動時にファイア・アンド・フォーゲットのアプローチで送信できます。

117,15

可用性の監視

c8y_RequiredAvailability フラグメントに設定された応答間隔は、プラットフォームがデバイスからデータを受信する予定間隔として使用されます。この間隔でデータが受信されない場合、デバイスはオフラインとしてマークされ、 c8y_UnavailabilityAlarm タイプのアラームが自動的に発生します。このアラームは、デバイスがデータを再送信すると自動的にクリアされます。デバイスからのそれ以上の操作は必要ありません。

次のリクエストはデバイスの定期的な信号と見なされ、デバイスを使用可能としてマークします。

• X-Cumulocity-Application-Key ヘッダーが設定されていない場合の、メジャーメント、イベント、およびアラームの作成
• 空のマネージドオブジェクトの更新

接続監視

Things Cloud は、デバイスの接続監視も提供します。デバイスがオペレーションを受信することができる接続を確立すると、プラットフォームはこのデバイスを接続されたと見なします。これは、HTTPロングポーリング接続やMQTTセッションにも同様に適用されます。

デバイス情報

デバイス情報 タブは、既定のデバイス情報を組み合わせたいくつかのウィジェットを含む定義済みのダッシュボードです。例えば、デバイスステータス ウィジェットは、デバイス状態と最後に利用可能になった日時に関する情報を保持する c8y_Availability フラグメントから情報を取得します。詳細については、ユーザーガイドの デバイス管理 ＞ デバイスの監視と制御 をご覧ください。

デバイスマーカー

デバイスは、インベントリ内で、独自のマネージドオブジェクトのc8y_IsDevice フラグメントを付与されます。このフラグメントを持つデバイスのみが、デバイス管理アプリケーションの すべてのデバイス のリストに表示されます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_IsDevice": {}
}

エージェントマーカー

オペレーションを受信するために、デバイスは独自のマネージドオブジェクトでエージェントマーカーフラグメントを宣言する必要があります。これにより、プラットフォームは、このフラグメントを持たない子階層のすべての子デバイスに対して、デバイスにオペレーションを送ることができるようになります。

PUT /inventory/managedObjects/<deviceId>

{
   "com_cumulocity_model_Agent": {}
}

デバイスの再起動

リモートで再起動できるデバイスは、デバイスの c8y_SupportedOperations フラグメントに c8y_Restart オペレーション追加して、この機能を通知することができます。すると、デバイスの詳細 ページで、コンテキストメニューの中に 再起動 ボタンが表示されるようになります。

再起動操作

デバイス管理アプリケーションの 再起動 ボタンをクリックすると、次のような操作が送信されます。

{
  "c8y_Restart": {}
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. リクエストされた再起動を実行する
3. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

Things Cloud は、510 静的応答テンプレートを提供します。

1. デバイスは510静的応答テンプレートを介してコマンドを受信する
   510,DeviceSerial
2. デバイスがオペレーションステータスをEXECUTINGに設定する
   501,c8y_Restart
3. デバイスはオペレーション ステータスを SUCCESSFUL に設定して、正常に実行されたことを確認する
   503,c8y_Restart

ハードウェア情報

デバイスは、独自のマネージドオブジェクト内の c8y_Hardware フラグメントを使用して、基盤となるハードウェア情報をThings Cloud に通知することができます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Hardware": {
       "serialNumber": "1234567890",
       "model": "myModel",
       "revision": "1.2.3"
   }
}

SmartREST例

110 静的テンプレートを使用してハードウェア情報をアップロードします。通常、エージェントアプリケーションの起動時に一度実行できます。

110,1234567890,myModel,1.2.3

デバイスプロファイル

デバイスプロファイル タブには、追加されたデバイス プロファイルのさまざまなパラメータが表示されます。デバイス エージェントの観点から見ると、デバイス プロファイルは、ファームウェア更新、ソフトウェア更新、および型指定されたファイル ベースのデバイス構成の組み合わせです。これらの機能をサポートするエージェント コードの大部分は再利用できます。

デバイス プロファイル機能は、デバイスがc8y_SupportedOperationsで c8y_DeviceProfile オペレーションを通知すると有効になります。デバイスプロファイル タブでは、ユーザーはデバイスにプロファイルを適用できます。これにより、設定されたプロファイルに従ってc8y_DeviceProfile オペレーションが作成されます。ファームウェア、ソフトウェア、および構成が存在する場合、個々のオペレーション(c8y_Firmware、c8y_SoftwareUpdate、および型指定されたc8y_DownloadConfigFile)とまったく同じように処理する必要があります。最初にファームウェア、2番目にソフトウェア、3番目に構成をインストールして c8y_Profile オペレーションを実行し、その後のアクションが、それ以前のアクションを上書きする可能性を最小限に抑えることをお勧めします。

{
   "profileName": "my profile",
   "profileId": "158751",
   "c8y_DeviceProfile": {
       "software": [
           {
               "name": "curl",
               "action": "install",
               "version": "2.3.4",
               "url": "http://my.url.com"
           },
           {
               "name": "cumulocity_agent",
               "action": "install",
               "version": "1.2.3",
               "url": "https://cumulocity.com/agent"
           }
       ],
       "configuration": [
           {
               "name": "ssh_conf",
               "type": "ssh_conf",
               "url": "http://cumulocity.com/conf"
           },
           {
               "name": "agent_conf",
               "type": "agent_conf",
               "url": "https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/156719"
           }
       ],
       "firmware": {
           "name": "device_fw",
           "version": "1.0.1",
           "url": "https://cumulocity.com/fw"
       }
   },
}

デバイスが c8y_Profile オペレーションを受信したら、最初に独自のマネージドオブジェクトでターゲット プロファイルを通知する必要があります。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Profile": {
       "profileName": "my profile",
       "profileId": "158751",
       "profileExecuted": false
   }
}

3つの各セクションを完了した後、デバイスはフラグメント c8y_Firmware、 c8y_SoftwareList、およびc8y_Configuration_<type> を使用した個々のオペレーションで説明された同じ方法で、独自のマネージドオブジェクトで現在の状態を通知する必要があります。次に、デバイスは、profileExecuted プロパティを true に更新して、マネージドオブジェクトにインストールされているプロファイルの状態を更新する必要があります。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Profile": {
       "profileName": "my profile",
       "profileId": "158751",
       "profileExecuted": true
   }
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. デバイス独自のマネージドオブジェクトに c8y_Profile フラグメントを profileExecuted = false で設定する
3. ファームウェアが含まれている場合はインストールし、独自のマネージドオブジェクトの c8y_Firmware フラグメントを更新してインストールを完了する
4. ソフトウェアが含まれている場合はインストールし、独自のマネージドオブジェクトの c8y_SoftwareList フラグメントを更新してインストールを完了する
5. 構成が含まれている場合はインストールし、独自のマネージドオブジェクト内の構成ごとに c8y_Configuration_<type> フラグメントを更新してインストールを完了する
6. デバイスのマネージドオブジェクトに c8y_Profile フラグメントを profileExecuted = true で設定する
7. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

Things Cloud で提供されるファームウェア、ソフトウェア、および構成の静的テンプレートに加えて、デバイス プロファイルの処理に使用できる特定のテンプレートがあります。527 応答テンプレートは、オペレーションを受信するように設計されています。121 静的テンプレートを使用して、デバイス プロファイルの現在の状態を設定できます。

1. c8y_DeviceProfile オペレーションを受信する
   

527,DeviceSerial,$FW,device_fw,1.0.1,https://cumulocity.com/fw,false,,$SW,curl,2.3.4,http://my.url.com,install,cumulocity_agent,1.2.3,https://cumulocity.com/agent,install,$CONF,http://cumulocity.com/conf,ssh_conf,https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/156719,agent_conf

2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_DeviceProfile
3. ターゲットプロファイルを設定する
   121,false,
4. ダウンロード、インストールおよびファームウェアのインストール状態を確認する
   115,device_fw,1.0.1,https://cumulocity.com/fw
5. ダウンロード、インストールおよびソフトウェアのインストール状態を確認する
   116,curl,2.3.4,http://my.url.com,cumulocity_agent,1.2.3,https://cumulocity.com/agent
6. ダウンロード、インストールおよび各構成のインストール状態を確認する
   120,ssh_conf,http://cumulocity.com/conf,config,
120,agent_conf,https://<tenantId>.je1.thingscloud.ntt.com/inventory/binaries/156719,agent.cfg,
   
7. ターゲットプロファイルを実行済みとして設定する
   121,true,
8. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_DeviceProfile

ファームウェア

ファームウェア タブには、現在インストールされているファームウェアが表示され、ユーザーは別のバージョンをインストールすることができます。デバイスは、一度に1つのファームウェアしかインストールすることができません。Things Cloud でどのようなファームウェアが使用できるかは、デバイスに依存します。典型的な使用例としては、オペレーティングシステム、マイクロコントローラファームウェア、またはBIOSがあります。

ファームウェアは、完全インストールまたはパッチを使用してインストールできます。どのバリアントがデバイスに送信されるかは、ファームウェアがファームウェアリポジトリでどのように作成されたかによって異なります。

インストールされたファームウェア

デバイスは、最初に現在の状態をプラットフォームに通知する必要があります。次に、インストールされたファームウェアをデバイス独自のマネージドオブジェクトの c8y_Firmware フラグメントに入力する必要があります。デバイスは、起動時およびローカルの変更が検出されたときに、現在の状態を Things Cloud にアップロードする必要があります。これには、更新がリモートでトリガーされた場合も含まれます。

PUT /inventory/managedObjects/<deviceId>

{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.2",
       "url": "http://test.com"
   }
}

ソフトウェアと同様に、URLフィールドはオプションであり、デバイスによって省略できます。

SmartREST例

115 静的テンプレートは、デバイスが現在インストールされているファームウェアの状態を通信するために使用できます。

115,ubuntu core,20.04.3,http://test.com

ファームウェア イメージのインストール

ユーザーがインストールするために完全なファームウェアイメージを選択すると、デバイスのマネージドオブジェクトで見つけたものと同様の c8y_Firmware フラグメントを持つオペレーションが作成されます。このオペレーションは、デバイスによって達成される必要がある望ましい状態と見なす必要があります。

{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.3",
       "url": "http://test.com"
   }
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. ファームウェア イメージをインストールする
3. デバイス独自のマネージドオブジェクトにインストールされているファームウェアの状態を更新する
4. オペレーションのステータスを SUCCESSFUL に設定する

デバイスを更新すると、基本的なシステムコンポーネントが変更されることがよくあります。これは、常に重要なオペレーションと見なす必要があります。デバイスは、Things Cloud へのすべての接続パラメータがアップグレード中も保持され、後で接続を再開できることを確認する必要があります。デバイスが、必要に応じてロールバックできるA/Bファームウェア切り替えメカニズムを使用しているかを確認することをお勧めします。

SmartREST例

Things Cloud には、ファームウェア イメージのインストールを処理するための 515 静的応答テンプレートが用意されています。

1. c8y_Firmware オペレーション（イメージ）を受信する
   515,DeviceSerial,ubuntu core,20.04.3,http://test.com
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_Firmware
3. ファームウェア イメージをインストールする
4. インベントリでデバイスのインストール済みファームウェア状態を更新する
   115,ubuntu core,20.04.3,http://test.com
5. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_Firmware

ファームウェアパッチのインストール

ユーザーがデバイスにインストールするファームウェアパッチを選択した場合、 c8y_Firmware オペレーションが作成されます。この場合、ファームウェアパッチのインストールに役立つ2つの追加パラメータが含まれています。デバイス エージェントは、通常のインストールではなく、ファームウェア パッチ プロセスを担当します。

{
   "c8y_Firmware": {
       "name": "ubuntu core",
       "version": "20.04.4",
       "url": "http://test.com",
       "dependency": "20.04.3",
       "isPatch": true
   }
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. 現在インストールされているファームウェアのバージョンが依存バージョンと 一致するかどうかを確認する
3. ファームウェアパッチをインストールする
4. デバイス独自のマネージドオブジェクトにインストールされているファームウェアの状態を更新する
5. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

Things Cloud は、ファームウェア パッチのインストールを処理するための 525 静的応答テンプレートを提供します。これは、515 テンプレートと類似の動作を行いますが、5 番目のパラメータとして依存性パラメータが追加されています。このテンプレートはパッチに対してのみトリガーされるため、完全なイメージではなくパッチがインストールされるべきという事実は暗黙の了解となっています。

1. c8y_Firmware オペレーション（パッチ）を受信する
   525,DeviceSerial,ubuntu core,20.04.3,http://test.com,20.04.3
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_Firmware
3. 現在インストールされているファームウェアのバージョンと依存バージョンが一致するかどうかを確認する
4. ファームウェア イメージをインストールする
5. インベントリでデバイスのインストール済みファームウェア状態を更新する
   115,ubuntu core,20.04.3,http://test.com
6. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_Firmware

識別子

識別子 タブには、デバイスに関連付けられているすべての ID が表示されます。使用可能な ID がない場合、タブは表示されません。ID は一意のデバイス識別子 (IMEI や SN など) から Things Cloud のデバイスのマネージド オブジェクトにマップされます。これにより、デバイスはマネージドオブジェクトを見つけることができます。

REST

MQTT (SmartREST 2.0)

MQTT のコンテキストでは、クライアント ID はデバイスの外部 ID として使用されます。接続時に、MQTT クライアント ID を使用して、接続をインベントリ内のデバイスに自動的に関連付けられます。デバイスで追加の ID バインドを作成する必要はありません。これらは、100 および 101 テンプレートが使用されるときに内部的に作成されます。データを作成するすべてのメッセージは、デバイス コンテキストに自動的に関連付けられます。

Things Cloud に接続されたデバイスによるデバイス作成:

100,createdDeviceName,deviceType

Things Cloud に接続されているデバイスの子デバイス作成:

101,uniqueChildId,myChildDevice,myChildType

ログ

ログ タブは、デバイスからログを抽出するために使用されます。ログ タブは、デバイスの c8y_SupportedOperations にc8y_LogfileRequest フラグメントが存在する場合に使用できます。 デバイスには、サポートするログの種類の配列を保持する c8y_SupportedLogs フラグメントが含まれている必要があります。ログの種類は、後でログがリクエストされたときに参照されます。

サポートされているログ設定

サポートされているログタイプは、デバイスが独自のマネージドオブジェクトの c8y_SupportedLogs フラグメントを使用して、デバイスによって通知されます。

PUT /inventory/managedObjects/<deviceId>

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

SmartREST例

118 静的テンプレートは、デバイスのサポートされているログを通知するために使用できます。

118,syslog,dmesg

ログファイルのアップロード

ユーザーが ログ タブを使用してデバイスからログ ファイルをリクエストすると、 c8y_LogfileRequest オペレーションが作成されます。

{
   "c8y_LogfileRequest": {
       "searchText": "kernel",
       "logFile": "syslog",
       "dateTo": "2021-09-22T11:40:27+0200",
       "dateFrom": "2021-09-21T11:40:27+0200",
       "maximumLines": 1000
   }
}

デバイスがログを収集すると、それらをファイルとして Things Cloud にアップロードします。 イベントを作成し、イベントのバイナリ添付ファイルとしてログファイルをアップロードすることをお勧めします。 このようなイベントの例を次に示します。

POST /event/events

{
   "source": {
       "id": "4801"
   },
   "type": "c8y_Logfile",
   "time": "2021-09-15T15:57:41.311Z",
   "text": "syslog log file"
}

必要に応じて、デバイスはオペレーションから c8y_LogfileRequest フラグメントまたはオペレーション ID をイベントに含めることもできます。ファイルは、イベント ID とイベント バイナリ API を使用してイベントに添付されます。

POST /event/events/<eventId>/binaries

Host: https://<TENANT_DOMAIN>
Authorization: <AUTHORIZATION>
Accept: application/json
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="object"

{ "name": "syslog.txt", "type": "text/plain" }
--boundary
Content-Disposition: form-data; name="file"; filename="syslog.txt"
Content-Type: text/plain

Oct 25 13:28:53 wtp kernel: [  719.554855] sd 6:0:0:0: [sdb] Write Protect is off
Oct 25 13:28:53 wtp kernel: [  719.554864] sd 6:0:0:0: [sdb] Mode Sense: 03 00 00 00
Oct 25 13:28:53 wtp kernel: [  719.555033] sd 6:0:0:0: [sdb] No Caching mode page found
--boundary--

アップロードが正常に完了したら、デバイスはアップロードされたファイルへの URL をオペレーションのc8y_LogfileRequest フラグメントに含める必要があります。リンクはプロパティ “file” として表示する必要があります。このアクションは、オペレーションのステータスのSUCCESSFUL 設定と組み合わせることができます。

PUT /devicecontrol/operations/<operationId>

{
   "status": "SUCCESSFUL",
   "c8y_LogfileRequest": {
       "searchText": "kernel",
       "logFile": "syslog",
       "dateTo": "2021-09-22T11:40:27+0200",
       "dateFrom": "2021-09-21T11:40:27+0200",
       "maximumLines": 1000,
       "file": "https://<tenantId>.je1.thingscloud.ntt.com/event/events/157700/binaries"
   }
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. オペレーションで指定されたログ ファイルの読み込み、フィルター処理、およびトリミングする
3. ログ ファイル イベントを作成する
4. ログファイルをバイナリ添付ファイルとして上記のイベントにアップロードする
5. オペレーションのステータスを SUCCESSFUL に設定し、アップロードされたログ ファイルの URL を含める

SmartREST例

Things Cloud は、c8y_LogfileRequest オペレーションを受信するための 522 静的応答テンプレートを提供します。ログファイルがアップロードされると、デバイスは503静的テンプレートの暗黙的なパラメータ機能を使用してオペレーションのステータスを設定し、同時にファイルリンクを提供できます。

1. c8y_LogfileRequest オペレーションを受信する
   522,DeviceSerial,syslog,2021-09-21T11:40:27+0200,2021-09-22T11:40:27+0200,ERROR,1000
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_LogfileRequest
3. REST API を使用してログファイルイベントを作成する
4. REST APIを使用して、イベントバイナリとして新しく作成されたイベントにログファイルをアップロードする
5. オペレーションのステータスを SUCCESSFUL に設定し、アップロードされたファイルの URL を指定する
   503,c8y_LogfileRequest,"https://<tenantId>.je1.thingscloud.ntt.com/event/events/157700/binaries"

計測値（メジャーメント）

計測値（メジャーメント） タブでは、デバイスから送信されたメジャーメントフラグメントごとに 1 つのグラフが作成されます。これは、含まれているすべてのシリーズが1つのグラフにまとめて表示されることを意味します。したがって、デバイス統合は、このグループ化を考慮して行う必要があります。その可視性は、デバイスでサポートされているメジャーメントによって制御されます。Things Cloud は、以前に送信されたメジャーメントに基づいて、デバイスでサポートされているメジャーメントを自動的かつ動的に入力します。つまり、計測値（メジャーメント）タブは、デバイスが最初のメジャーメントを送信した後に効果的に表示されます。

SmartREST例

メッセージ ID の 2xx の範囲でメジャーメントを作成するために使用できる静的テンプレートがいくつかあります。200 の静的テンプレートを使用して、動的なフラグメントとシリーズを含むメジャーメントを作成します。

200,c8y_Temperature,T,25

このテンプレートは多くのユースケースで使用できますが、フラグメントとシリーズを動的に定義する必要がない場合は、すべてのユースケースでカスタムテンプレートを作成することをお勧めします。

ネットワーク

ネットワーク タブには、ネットワーク情報が表示されます。 c8y_Network フラグメントがデバイスのマネージドオブジェクトに存在するかどうかが表示されます。WAN、LAN、DHCPの3つのサブセクションがあります。これらは、ネストされたフラグメント c8y_ WAN、 c8y_LAN、c8y_DHCP によって、それぞれアクティブ化できます。

ネットワークステータス

デバイスは、デバイス独自のマネージドオブジェクトの c8y_Network フラグメントを使用して、現在のローカルネットワークのステータスと構成をプラットフォームに通知できます。

PUT /inventory/managedObjects/<deviceId>

{
   "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": "1.1.1.1",
           "dns1": "8.8.8.8",
           "domainName": "my.domain",
           "addressRange": {
               "start": "192.168.128.100",
               "end": "192.168.128.199"
           },
           "enabled": 1
       }
   }
}

ネットワーク構成の設定

デバイスが c8y_SupportedOperations に c8y_Network オペレーションを含んでいる場合、ユーザーはネットワークタブでデバイスのネットワーク構成を更新することもできます。変更された構成は、デバイスのマネージドオブジェクトに存在するのと類似のフラグメントを持つ c8y_Network オペレーションとして送信されます。このオペレーションの中の c8y_Network フラグメントは、1つ以上のネストされたフラグメントが含まれる場合があります。

{
   "c8y_Network": {
       "c8y_LAN": {
           "netmask": "255.255.255.0",
           "ip": "192.168.128.1",
           "enabled": 1
       },
       "c8y_WAN": {
           "password": "user-password",
           "authType": "chap",
           "apn": "example.apn.com",
           "username": "ee"
       },
       "c8y_DHCP": {
           "dns2": "1.1.1.1",
           "dns1": "8.8.8.8",
           "domainName": "my.domain",
           "addressRange": {
               "start": "192.168.128.100",
               "end": "192.168.128.199"
           },
           "enabled": 1
       }
   }
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. WAN、LAN、および DHCP 構成を適用する
3. デバイスのマネージドオブジェクトの新しいネットワーク構成ステータスを設定する
4. オペレーションのステータスを SUCCESSFUL に設定する

ネットワーク構成の変更は、デバイスが Things Cloud プラットフォームに接続する機能に影響を与える可能性があります。新しい設定で接続テストを実行することをお勧めします。テストが失敗した場合、デバイスは設定を以前の状態にロールバックし、オペレーションのステータスを FAILED に設定する必要があります。

SmartREST例

ネットワーク フラグメントの設定やネットワークオペレーションの受信に使用できる静的テンプレートはありません。代わりにカスタムテンプレートを使用できます。

10,100,PUT,INVENTORY,false,c8y_Network.c8y_LAN.name,STRING,,c8y_Network.c8y_LAN.ip,STRING,,c8y_Network.c8y_LAN.netmask,STRING,,c8y_Network.c8y_LAN.mac,STRING,,c8y_Network.c8y_LAN.enabled,STRING,,c8y_Network.c8y_WAN.simStatus,STRING,,c8y_Network.c8y_WAN.apn,STRING,,c8y_Network.c8y_WAN.username,STRING,,c8y_Network.c8y_WAN.password,STRING,,c8y_Network.c8y_WAN.authType,STRING,,c8y_Network.c8y_DHCP.addressRange.start,STRING,,c8y_Network.c8y_DHCP.addressRange.end,STRING,,c8y_Network.c8y_DHCP.domainName,STRING,,c8y_Network.c8y_DHCP.dns1,STRING,,c8y_Network.c8y_DHCP.dns2,STRING,,c8y_Network.c8y_DHCP.enabled,STRING,

11,200,,c8y_Network.c8y_WAN,c8y_Network.c8y_WAN.apn,c8y_Network.c8y_WAN.username,c8y_Network.c8y_WAN.password,c8y_Network.c8y_WAN.authType

11,201,,c8y_Network.c8y_LAN,c8y_Network.c8y_LAN.ip,c8y_Network.c8y_LAN.netmask,c8y_Network.c8y_LAN.enabled

11,202,,c8y_Network.c8y_DHCP,c8y_Network.c8y_DHCP.addressRange.start,c8y_Network.c8y_DHCP.addressRange.end,c8y_Network.c8y_DHCP.domainName,c8y_Network.c8y_DHCP.dns1,c8y_Network.c8y_DHCP.dns2,c8y_Network.c8y_DHCP.enabled

カスタムテンプレートの例では、デバイスが現在のネットワーク構成を完全にアップロードするための 100 テンプレートを提供します。デバイス エージェントの起動時および変更が検出されるたびに、このテンプレートを使用して、クラウド内の情報をローカルの実態と同期する必要があります。

このサンプルテンプレートには、3 つの異なるネストされたフラグメントをオペレーションとして受信するための 3 つの応答テンプレートも用意されています。各応答テンプレートは個別に処理できます。

WAN

1. WAN 構成オペレーションを受信する
   200,example.apn.com,user,secret,chap
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_Network
3. WAN 構成を適用する
4. インベントリでデバイスのネットワーク構成を更新する
   100,br0,192.168.128.1,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.100,192.168.128.199,my.domain,8.8.8.8,1.1.1.1,1
5. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_Network

LAN

1. LAN 構成オペレーションを受信する
   201,192.168.128.2,255.255.255.0,1
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_Network
3. LAN 構成を適用する
4. インベントリでデバイスのネットワーク構成を更新する
   100,br0,192.168.128.2,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.100,192.168.128.199,my.domain,8.8.8.8,1.1.1.1,1
5. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_Network

DHCP

1. DHCP 構成オペレーションを受信する
   202,192.168.128.150,192.168.128.199,my.other.domain,1.1.1.1,8.8.8.8,1
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_Network
3. DHCP 構成を適用する
4. インベントリでデバイスのネットワーク設定を更新する
   100,br0,192.168.128.1,255.255.255.0,00:60:64:dd:a5:c3,1,SIM OK,example.apn.com,user,secret,chap,192.168.128.150,192.168.128.199,my.other.domain,1.1.1.1,8.8.8.8,1
5. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_Network

リモートアクセス

リモートアクセスタブは、リモートコントロール プロトコルを介してリモートコントロール用のデバイスを構成およびアクセスするために使用されます。

リモートアクセス タブは、次の条件が満たされている場合に使用できます。

• クラウドリモートアクセス マイクロサービスは、必要なテナントにサブスクライブされている
• ユーザーに適切なアクセス許可が付与されている (リモート アクセス管理者権限)
• デバイスの c8y_SupportedOperations に c8y_RemoteAccessConnect が追加されている

リモートアクセス接続

ユーザーがリモートアクセス エンドポイントを選択して 接続 ボタンをクリックすると、 c8y_RemoteAccessConnect オペレーションが作成されます。

{
   "c8y_RemoteAccessConnect": {
     "hostname": "10.0.0.67",
     "port": 5900,
     "connectionKey": "eb5e9d13-1caa-486b-bdda-130ca0d87df8"
   }
}

このオペレーションでは、デバイスは認証用の接続キー (wss://<c8y host>/service/remoteaccess/device/<connectionKey>) と、指定されたホスト名とポートへのローカルソケットを使用して、マイクロサービス エンドポイントへの WebSocket 接続を開く必要があります。次に、WebSocket とローカルソケットの間でデータの双方向転送を確立する必要があります。

Things Cloud は現在、VNC、SSH、および Telnet をサポートしています。デバイスエージェントは、使用するリモートアクセス プロトコルとは無関係に実装する必要があります。この操作では、意図的にプロトコルは転送されません。エージェントは、確立された両方のソケット間で任意のデータを転送できる必要があります。

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. リモートアクセス マイクロサービスへの WebSocket 接続を確立する
3. 指定したホストとポートへのローカルソケット接続を確立する
4. WebSocket とローカルソケット間の双方向転送を確立する
5. オペレーションのステータスを SUCCESSFUL に設定する

接続が確立されると、オペレーションは SUCCESSFUL に設定されます。切断はサイレントに行われます。接続が関係するコンポーネントのいずれによっても正常に終了されなかった場合でも、オペレーションのステータスは SUCCESSFUL のままである必要があります。接続の 1 つ (WebSocket または TCP) が終了するたびに、デバイスエージェントはセッション終了と見なし、両方の接続も終了する必要があります。

SmartREST例

530 静的応答テンプレートは、 c8y_RemoteAccessConnect オペレーションの受信に使用できます。

1. c8y_RemoteAccessConnect オペレーションを受信する
   530,DeviceSerial,10.0.0.67,22,eb5e9d13-1caa-486b-bdda-130ca0d87df8
2. デバイスがオペレーション ステータスをEXECUTINGに設定する
   501,c8y_RemoteAccessConnect
3. HTTP を使用して WebSocket 接続を確立する
4. ローカルソケット接続を確立する
5. デバイスがオペレーションステータスを SUCCESSFULに設定する
   503,c8y_RemoteAccessConnect

シェル

シェル タブでは、デバイスに任意のデバイス固有のコマンドを送信することができます。デバイスのc8y_SupportedOperationsに c8y_Command オペレーションが存在する場合に表示されます。

デバイスにコマンドを送信する

コマンドテキストには、任意の文字列を入力することができます。フォーマットやその解釈はデバイスの統合に依存します。実行 ボタンをクリックすると、 c8y_Command オペレーションが作成されます。

{
   "c8y_Command": {
       "text": "get sw.version; get hw.version"
   }
}

実行の完了後、デバイスはオペレーションのステータスを SUCCESSFUL に設定するだけでなく、コマンドの戻り値の文字列を提供する必要があります。結果は、オペレーションの c8y_Command フラグメント内にネストされた文字列プロパティとして提供されます。

PUT /devicecontrol/operations/<operationId>

{
   "status": "SUCCESSFUL",
   "c8y_Command": {
       "text": "get sw.version; get hw.version",
       "result": "1.2.3; 9.8.7"
   }
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. コマンドを実行して戻り値を取得する
3. オペレーションのステータスを SUCCESSFUL に設定し、戻り値を含める

SmartREST例

SmartREST 接続デバイスの場合、 c8y_Command オペレーションを受信するために 511 静的応答テンプレートを使用できます。 さらに、503 静的テンプレートの暗黙的なパラメータ機能を使用して、戻り値を指定できます。

1. c8y_Command オペレーションを受信する
   511,DeviceSerial,"get sw.version; get hw.version"
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_Command
3. オペレーションのステータスを SUCCESSFUL に設定し、戻り値を指定する
   503,c8y_Command,"1.2.3; 9.8.7"

ソフトウェア

ソフトウェア タブでは、デバイスのソフトウェアファイル一式をインストールおよびアンインストールすることができます。ファイルは、URLを使用して配置することも、Things Cloud ソフトウェアリポジトリにホストすることもできます。デバイスエージェントは、そのローカルインストール、管理、アンインストール手順、およびオペレーション中のあらゆる種類のエラー処理に対して完全に対応します。

デバイスの詳細 ページには、デバイスのマネージドオブジェクトの c8y_SupportedOperations フラグメントで c8y_SoftwareList や c8y_SoftwareUpdate を通知するデバイスのソフトウェアタブが表示されます。また、少なくとも1つのソフトウェアサービスが実行されているデバイスのための サービス タブも表示されます。サービスにはメジャーメント、アラーム、イベントを割り当てることができます。

インストールされているソフトウェア

デバイスのマネージドオブジェクトがインストールされたソフトウェアパッケージを表すには、2つの方法があります。c8y_SoftwareList フラグメントまたは子を追加してリストにすることができます。後者の方法では、デバイスが c8y_SupportedSoftwareTypes フラグメントを持つことが必要です。最初のアプローチをレガシー、2番目のアプローチをアドバンスと呼びます。

リスト エントリまたは子追加として表されるソフトウェア パッケージには、次のプロパティが含まれている必要があります。

name と version は、パッケージを識別するために使用されます。すでに述べた c8y_SupportedSoftwareTypes フラグメントは、デバイスにインストール可能なソフトウェアの種類を制限します。

レガシーソフトウェア管理

デバイスは、マネージドオブジェクトの c8y_SoftwareList フラグメントを更新することで、ソフトウェア リストを更新できます。

PUT /inventory/managedObjects/<deviceId>

{
  "c8y_SoftwareList": [
    {
      "name": "software_a",
      "version": "3.0.0",
      "url": "http://example.com/software_a",
      "softwareType": "type A"
    },
    {
      "name": "software_b",
      "version": "2.0.0",
      "url": "http://example.com/software_b",
      "softwareType": "type B"
    }
  ]
}

デバイスは、起動時にインストールされているソフトウェアの完全なリストをアップロードする必要があります。さらに、ローカルの変更がトリガーまたは検出された場合は、常にリストを更新する必要があります。これには、Things Cloud の UIから変更がリクエストされた場合も含まれます。

SmartREST例

Things Cloud は、デバイスがインストールされたソフトウェアをアップロードするために、静的なSmartRESTテンプレート116を提供します。これは、ソフトウェアパッケージごとにトリプルの動的長さのリストをパラメータとして受け取ります。各トリプルは、個々のパッケージの名前、バージョン、およびURLプロパティとして解釈されます。

116,software_a,3.0.0,http://example.com/software_a,software_b,2.0.0,http://example.com/software_b

インストール済みソフトウェアの変更

ソフトウェア タブでは、ユーザーはデバイスにインストール、更新、およびアンインストールするソフトウェアを選択することができます。確認後、目的のソフトウェア構成をオペレーションとしてデバイスに送信されます。オペレーションの形式は、デバイスの c8y_SupportedOperations フラグに依存します。

ソフトウェア一覧

デバイスが c8y_SoftwareList オペレーションのみをサポートし、c8y_SupportedOperations　フラグメントが c8y_SoftwareUpdateを含まない場合、 c8y_SoftwareList オペレーションがデバイスに送信されます。このオペレーションには、デバイス独自のマネージドオブジェクトにすでに存在するものと非常に類似した c8y_SoftwareList フラグメントが含まれます。 c8y_SoftwareList オペレーションは、常にデバイスにインストールされるべきソフトウェアの全リストを含んでいます。リスト内のパッケージを正確にインストールする必要があります。また、リストに含まれていないインストール済みのパッケージは削除する必要があります。

{
  "c8y_SoftwareList": [
    {
      "name": "software_a",
      "version": "4.0.0",
      "url": "http://example.com/software_a"
    },
    {
      "name": "software_b",
      "version": "3.0.0",
      "url": "http://example.com/software_b"
    }
  ]
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスをEXECUTINGに設定する
2. アンインストールする必要があるソフトウェアをアンインストールする
3. インストールする必要があるソフトウェアをインストールする
4. デバイス独自のマネージドオブジェクトのソフトウェアリストを更新する
5. オペレーションのステータスをSUCCESSFULに設定する

何らかの理由で目的の状態を達成できない場合は、オペレーションをステータス FAILED で終了する必要があります。

SmartREST例

516静的応答テンプレートは、ソフトウェアのリスト操作に対応するために利用できます。これは、デバイス独自のマネージドオブジェクトを更新するために使用される116テンプレートと非常に類似して動作します。

1. c8y_SoftwareList オペレーションを受信する
   516,DeviceSerial,software_a,4.0.0,http://example.com/software_a,software_b,3.0.0,http://example.com/software_b
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_SoftwareList
3. ソフトウェアをアンインストールまたはインストールする
4. インベントリ内のデバイスのソフトウェアリストを更新する
   116,software_a,4.0.0,http://example.com/software_a,software_b,3.0.0,http://example.com/software_b
5. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_SoftwareList

ソフトウェアの更新

デバイスが c8y_SupportedOperations フラグメントで c8y_SoftwareUpdate オペレーションをサポートしている場合、ソフトウェア タブはデバイスの c8y_SoftwareUpdate オペレーションを作成します。概念としてソフトウェア更新は、ソフトウェアリストと類似しています。ソフトウェアの望ましい状態は、パッケージのリストという形でデバイスに送信されます。その違いは、 c8y_SoftwareUpdate は部分的なリストと考えるべきであるということです。各リスト要素には、パッケージをインストールするかアンインストールするかの追加指示が含まれます。ソフトウェア更新リストに記載されていないパッケージには触れないでください。

{
  "c8y_SoftwareUpdate": [
    {
      "name": "software_a",
      "version": "4.0.0",
      "url": "http://example.com/software_a",
      "action": "install"
    },
    {
      "name": "software_b",
      "version": "3.0.0",
      "url": "http://example.com/software_b",
      "action": "delete"
    }
  ]
}

デバイスは、次のアクションを実行する必要があります。

1. オペレーションのステータスを EXECUTING に設定する
2. オペレーションに含まれるパッケージのリストを反復処理し、それぞれのアクションを実行する
3. デバイス独自のマネージドオブジェクトのソフトウェアリストを更新する
4. オペレーションのステータスを SUCCESSFUL に設定する

SmartREST例

528 静的応答テンプレートは、ソフトウェアの更新オペレーションを処理するために使用できます。

1. c8y_SoftwareUpdate オペレーションを受信する
   528,DeviceSerial,software_a,4.0.0,http://example.com/software_a,install,
software_b,3.0.0,http://example.com/software_b,delete (表示上改行を追加しています)
2. オペレーションのステータスを EXECUTING に設定する
   501,c8y_SoftwareUpdate
3. ソフトウェアをアンインストールまたはインストールする
4. インベントリ内のデバイスのソフトウェアリストを更新する
   116,software_a,3.0.0,http://example.com/software_a
5. オペレーションのステータスを SUCCESSFUL に設定する
   503,c8y_SoftwareUpdate

サービス

Things Cloud UI では、デバイス上で動作するソフトウェアサービスを監視することができます。サービスは、Things Cloud ドメインモデルにおいて、 c8y_Service タイプを持つデバイスのマネージドオブジェクトの子追加として表します。

デバイスの詳細 ページには、少なくとも 1 つのソフトウェア サービスを持つデバイスの サービス タブが表示されます。サービスはメジャーメント、アラーム、イベントが割り当てられています。

マネージドオブジェクトを操作するために、Things Cloud REST API を使用してサービスのクエリ、更新、追加、削除を行います。

REST API 例

プラットフォームへのサービス通知

インベントリ REST API の使用:

POST /inventory/managedObjects/<deviceId>/childAdditions

Content-Type: "application/vnd.com.nsn.cumulocity.managedObject+json"

{
  "name": "MongoDB",
  "type": "c8y_Service",
  "serviceType": "systemd",
  "status": "up"
}

または、SmartREST静的テンプレート102を使用します。2番目のパラメータである一意のIDは、内部の数値IDではなく、プラットフォームとは異なり、デバイスによって定義される文字列ベースの外部IDを参照します。同じサービスを実行している他のデバイスとの競合を避けるため、一意のIDの前にデバイス固有のプレフィックスを付けることをお勧めします。

102,myDevice_MongoDb,systemd,MongoDb,up

サービスのステータス更新

インベントリ REST API の使用：

POST /inventory/managedObjects/<serviceId>

Content-Type: "application/vnd.com.nsn.cumulocity.managedObject+json"

{
  "status": "down"
}

または、SmartREST 静的テンプレート 104 を使用します（一意の ID を使用して MQTT トピック内のサービスを対象にすることを忘れないでください）。

104,down

サービスデータの送信

メジャーメント REST API：

POST /device/<serviceId>/measurements

Content-Type: "application/vnd.com.nsn.cumulocity.measurement+json"

{
  "source": {
    "id": "123"
  },
  "time": "2020-03-19T12:03:27.845Z",
  "type": "c8y_Memory",
  "c8y_Memory": {
    "allocated": {
      "unit": "MB",
      "value": 100
    }
  }
}

または、 s/us/<serviceUniqueId>トピックに送信されたSmartREST静的テンプレート200を使用します。

200,c8y_Memory,allocated,100,MB

メジャーメントと同様に、サービスに関連するアラームやイベントも送信できます。

トラッキング

トラッキング タブでは、デバイスのパスを可視化することができます。これを実現するために、デバイスは定期的にトラッキングイベントを送信し、その位置を更新する必要があります。

位置履歴の追跡

デバイスは、現在または過去の位置を、 c8y_Position フラグメントの位置更新イベントとしてアップロードすることができます。これは、ルート上のデバイスを追跡したり、一般的にデバイスの位置履歴を追跡するのに便利です。

POST /event/events

{
    "c8y_Position": {
    	"alt": 67,
      "lng": 6.95173,
      "lat": 51.151977
    },
    "time":"2013-06-22T17:03:14.000+02:00",
    "source": {
    	"id": "10300"
     },
    "type": "c8y_LocationUpdate",
    "text": "LocUpdate"
}

SmartREST例

Things Cloud には、SmartREST を使用して位置更新イベントを送信するための 401 静的テンプレートが用意されています。

401,51.151977,6.95173,67,2013-06-22T17:03:14.000+02:00

現在位置の設定

現在のデバイス位置は、デバイス独自のマネージドオブジェクトの c8y_Position フラグメントを使用して表されます。

PUT /inventory/managedObjects/<deviceId>

{
    "c8y_Position": {
    	"alt": 67,
      "lng": 6.95173,
      "lat": 51.151977
    }
}

SmartREST例

デバイスは、112 静的テンプレートを使用して現在の位置を更新できます。

112,51.151977,6.95173,67,

Things Cloud では、時間の経過に伴う追跡はイベントを使用して行われ、現在の位置はデバイス独自のマネージドオブジェクトのフラグメントとして表されます (詳細については、上記を参照)。実際には、デバイスは通常、一定間隔で現在の位置を決定し、測定された座標をアップロードします。この場合、現在の位置とその時点の位置は同じであり、402静的テンプレートを使用して同時にアップロードできます。

402,51.151977,6.95173,67,,