GUIを用いたデバイス制御

Things Cloudのデバイス管理アプリケーションを利用したデバイス制御の利用方法について説明します。デバイス制御の全体の仕組みを知りたい場合はデバイス制御をご覧ください。

また、デバイス側の実装は各デバイスの仕様に従い、別途実施する必要があります。

概要

Operation GUI

デバイス管理アプリは各デバイスの詳細を表示するGUIを提供しています。デバイスの詳細情報を表示するには、デバイスリストでデバイスをクリックします。デバイスの詳細情報画面で左側に表示されるタブメニューまたは「もっと見る」内のメニューを選択し、以下のオペレーションを発行することができます。

ただし、本機能を利用するためには対象となるデバイスに特定のフラグメント（c8y_SupportedOperations）に対して規定の配列値を与えることが必要となることに注意してください。

デバイス詳細情報画面のタブで実行できるオペレーション

タブメニュー	発行できるオペレーション	フラグメントの規定値
制御	-
構成	デバイス設定変更	c8y_Configuration
	現在のデバイス設定内容の取得	c8y_SendConfiguration
	構成スナップショットの取得	c8y_UploadConfigFile
	構成スナップショットの適用	c8y_DownloadConfigFile
ソフトウェア	ソフトウェアのインストール	c8y_SoftwareList
	ファームウェアのインストール	c8y_Firmware
ネットワーク	WAN設定変更	c8y_Network.c8y_WAN
	LAN設定変更	c8y_Network.c8y_LAN
	DHCP設定変更	c8y_Network.c8y_DHCP
シェル	シェルコマンド送信	c8y_Command
ログ	ログファイル取得	c8y_LogfileRequest

デバイス詳細情報画面の「もっと見る」で実行できるオペレーション

メニュー	発行できるオペレーション	フラグメントの規定値
デバイスを再起動	デバイス再起動	c8y_Restart
計測値を取得	メジャーメント取得	c8y_MeasurementRequestOperation
測定調査を開始	メジャーメント定期送信の開始	c8y_MeasurementPollFrequencyOperation

デバイス管理アプリ（GUI）におけるオペレーション利用方法

Operation Overview

オペレーションの実行フローは上図で示した通りです。以下に続く節ではGUIによるオペレーションの利用方法にフォーカスした説明を行いますので、上図のステップ2、ステップ3、ステップ5 の説明は各オペレーションに特有の考慮事項がない限り省略します。この部分の詳細を知りたい場合はデバイス制御の「オペレーションの利用方法」の節ををご覧ください。

タブメニュー：制御

control

「制御」タブは特別なフラグメントを付与することなく表示されます。このメニューでは何らかの方法によって生成されたオペレーションの状態管理を行うことができます。

オペレーションは次の4つの状態のいずれかになり、それぞれのアイコンで示されます。

状態	説明
保留	操作は作成されたばかりで、デバイスが操作を取得するのを待っています。
実行中	操作はデバイスによって取得され、実行中です。
成功	操作はデバイスによって正常に実行されました。
失敗	デバイスで操作を実行できませんでした。

トップメニューバーの左側にあるステータスボタンの1つをクリックすると、対応する操作が非表示になります。もう一度クリックすると、操作が再度表示されます。

トップメニューバーの右側にあるリアルタイムをクリックすると、デバイスからの操作がリアルタイムで表示されます。

オペレーションは時間の降順で一覧表示されます。オペレーションごとに、次の情報が表示されます。

情報	説明
状態	保留、実行中、成功、失敗のいずれかです(上記参照)。
名前	オペレーションの名前。

行をクリックすると展開され、操作の詳細が表示されます。

詳細:操作名とステータスに関する情報を提供します。status=FAILEDの場合は、（オペレーション更新の際に設定されていれば）失敗の理由が表示されます。
変更履歴:操作の過去の変更に関する情報を提供します。

Operation Details

タブメニュー：構成

「構成」タブは以下のフラグメントを対象となるデバイスに付与することで表示されます。（配列要素のいずれか1つが含まれていれば表示されます）

{
  "c8y_SupportedOperations": [
    "c8y_Configuration",
    "c8y_SendConfiguration",
    "c8y_UploadConfigFile",
    "c8y_DownloadConfigFile"
  ]
}

表示される画面は以下の通りです。

configuration

デバイス設定変更

「構成」タブの「構成」ウインドウの中に記載した設定値をデバイスに向けて送信します。本機能を利用するためには c8y_SupportedOperations: ["c8y_Configuration"] が必要です。

「構成」ウインドウの内容は、デバイスに付与された "c8y_Configuration" フラグメントの値が自動的に読み込まれます。このオペレーションを受け取ったデバイスは、デバイス内の設定値を更新するとともに、Things Cloud上のデバイスに対して "c8y_Configuration" フラグメントの更新を行い、設定値を 保存するべき(SHOULD) です。

configuration-sequence

ステップ1．設定値を更新し「保存」ボタン押下

「構成」タブの「構成」ウインドウの中の設定値を編集し、「保存」ボタンをクリックします。

edit config

Things Cloud& 内で以下のようなオペレーションが生成されます。

{
  creationTime: "2019-10-03T09:19:42.371+09:00",
  deviceId: "142653",
  deviceName: "OpenBlocks IoT EX1 (I2E00454)",
  self: "<<URL to this operation mapping>>",
  id: "142654",
  status: "PENDING",
  c8y_Configuration: {
    config: "{ "sensors": [ { "002cbd78": { "profile": "f60204", "memo": "002cbd78" } } ] }"
  },
  description: "Configuration update"
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_Cofiguration の値に、フォームに記載した設定値が指定されます。

ステップ4-1．設定値を変更

ステップ2. で受け取ったc8y_Configuration の内容を元に、デバイス内部の設定値を変更します。これは再起動を伴うこともあるでしょう。

ステップ4-2. デバイス更新

ステップ4-1. で変更した設定内容をThings Cloud上のマネージドオブジェクトにも反映します。このためには、マネージドオブジェクトに "c8y_Configuration" のフラグメントとして付与することになります。GUIと連動するためには "config" キーに対する文字列として設定内容を付与する必要があることに注意してください。

具体的には以下のAPIリクエストを行うことになります。

利用するAPI

PUT /inventory/managedObjects/<<ManagedObjectID>>

リクエスト例：

PUT /inventory/managedObjects/143943 HTTP/1.1
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
...
{
  "c8y_Configuration": {
    "config": "{\n    \"lang\": \"en\",\n    \"pollingTime\": 30000\n}"
  }
}

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
...
{
  "owner": "device_SampleDevice",
  "creationTime": "2019-10-24T11:27:31.010+09:00",
  "lastUpdated": "2019-11-11T11:56:49.619+09:00",
  "name": "SampleDevice",
  "id": "143829",
  "com_cumulocity_model_Agent": {},
  "c8y_IsDevice": {},
  "c8y_Configuration": {
    "config": "{\n    \"lang\": \"en\",\n    \"pollingTime\": 30000\n}"
  },
  "c8y_SupportedOperations": [
    "c8y_Configuration",
    "c8y_SendConfiguration",
    "c8y_UploadConfigFile",
    "c8y_DownloadConfigFile"
  ]
}

現在のデバイス設定送信要求

現在のデバイスの設定値を「構成」タブの「構成」ウインドウの中に反映させます。本機能を利用するためには c8y_SupportedOperations: ["c8y_SendConfiguration"] が必要です。

configuration-sequence

ステップ1．再読み込みを押下

「構成」タブの右上にある「再読み込み」をクリックします。

edit config

Things Cloud®内で以下のようなオペレーションが生成されます。

{
  "creationTime": "2019-11-11T12:40:44.818+09:00",
  "deviceId": "143829",
  "deviceName": "SampleDevice",
  "self": "<<URL to this operation mapping>>",
  "id": "144600",
  "status": "PENDING",
  "c8y_SendConfiguration": {},
  "description": "Requested current configuration"
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_SendCofiguration の値は空のjsonオブジェクトとなります。

ステップ4-1．設定値を変更

ステップ2. で c8y_SendConfiguration を受け取った事を契機とし、Things Cloudに通知するためのデバイス内部の設定値を取得します。

ステップ4-2. デバイス更新

ステップ4-1. で取得した設定内容をThings Cloud上のマネージドオブジェクトに反映します。このためには、マネージドオブジェクトに "c8y_Configuration" のフラグメントとして付与することになります。GUIと連動するためには "config" キーに対する文字列として設定内容を付与する必要があることに注意してください。

具体的には以下のAPIリクエストを行うことになります。

利用するAPI

PUT /inventory/managedObjects/<<ManagedObjectID>>

リクエスト例：

PUT /inventory/managedObjects/143943 HTTP/1.1
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
...
{
  "c8y_Configuration": {
    "config": "{\n    \"lang\": \"en\",\n    \"pollingTime\": 30000\n}"
  }
}

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
...
{
  "owner": "device_SampleDevice",
  "creationTime": "2019-10-24T11:27:31.010+09:00",
  "lastUpdated": "2019-11-11T11:56:49.619+09:00",
  "name": "SampleDevice",
  "id": "143829",
  "com_cumulocity_model_Agent": {},
  "c8y_IsDevice": {},
  "c8y_Configuration": {
    "config": "{\n    \"lang\": \"en\",\n    \"pollingTime\": 30000\n}"
  },
  "c8y_SupportedOperations": [
    "c8y_Configuration",
    "c8y_SendConfiguration",
    "c8y_UploadConfigFile",
    "c8y_DownloadConfigFile"
  ]
}

構成スナップショットの取得

現在のデバイスの設定のスナップショットを取得します。本機能を利用するためには c8y_SupportedOperations: ["c8y_UploadConfigFile"] が必要です。

editConfig

ステップ１. 「デバイスから新しいスナップショットを取得」押下

「構成」タブの「構成スナップショット」の右側にある「デバイスから新しいスナップショットを取得」をクリックします。

UploadConfigulation

Things Cloud®内で以下のようなオペレーションが生成されます。

{
  "creationTime": "2019-11-12T16:43:21.941+09:00",
  "deviceId": "8174669",
  "deviceName": "SampleDevice",
  "self": "<<URL to this operation mapping>>",
  "id": "7941423",
  "status": "PENDING",
  "description": "Retrieve configuration snapshot",
  "c8y_UploadConfigFile": {}
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_UploadConfigFile の値は空のjsonオブジェクトとなります。

ステップ4-1．設定値を取得

ステップ2. で c8y_UploadConfigFile を受け取った事を契機とし、デバイス内部の現在の設定値を設定スナップショットとしてファイル保存します。デバイスによっては、設定スナップショットファイルは既に端末内に保存されていて、このタイミングで特別な操作を行うことはないかもしれません。

ステップ4-2. バイナリファイルアップロード

ステップ4-1. で取得した設定内容を Things Cloud にファイルとしてアップロードします。このファイルはThings Cloud 内では「バイナリ」として扱われ、「管理」アプリケーション内の「ファイルリポジトリ」で管理されます。

具体的には以下のAPIリクエストを行うことになります。

利用するAPI

POST /inventory/binaries

リクエスト例：

POST /inventory/binaries
Host: ...
Authorization: Basic ...
Content-Type: multipart/form-data; boundary=--myBoundary
Accept: application/json

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

{
  "name":"my-file.json",
  "type":"application/json",
  ...
}
--myBoundary
Content-Disposition: form-data; name="filesize"

217152
--myBoundary
Content-Disposition: form-data; name="file"; filename="my-file.json"
Content-Type: application/json

<<file content>>
--myBoundary

応答例：

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Location: https://.../inventory/binaries/8286354

{
    "type": "application/json",
    "lastUpdated": "2019-11-29T16:07:24.774+09:00",
    "name": "config1.json",
    "self": "https://.../inventory/binaries/8235155",
    "id": "8235155",
    ...
}

ステップ4-3. 構成スナップショット追加

ステップ4-2.でアップロードしたファイルを指定し、管理用の情報を付加した構成スナップショット情報を作成します。構成スナップショット情報は Things Cloud 内で「マネージドオブジェクト」として管理され、4-2. で登録したバイナリを指し示すURLを保持します。

具体的には以下のAPIリクエストを行うことになります。

利用するAPI

POST /inventory/managedObjects

リクエスト例：

POST /inventory/managedObjects
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
{
  "name" : "Sample",
  "description": "Upload 2019/11/29",
  "url": "<<4-2の応答に含まれるselfのurl>>",
  "type": "c8y_ConfigurationDump"
}

応答例：

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Content-Length: ...
Location: <<URL of new object>>
{
    "creationTime": "2019-11-29T16:17:15.133+09:00",
    "type": "c8y_ConfigurationDump",
    "lastUpdated": "2019-11-29T16:17:15.133+09:00",
    "name": "Sample",
    "self": "https://.../inventory/managedObjects/8235277",
    "id": "8235277",
    "description": "Upload 2019/11/29",
    "url": "https://.../inventory/binaries/8235155"
}

ステップ4-4. デバイス更新

ステップ4-3. で作成した構成スナップショット情報をデバイスに紐付けます。

具体的には以下のAPIリクエストを行うことになります。

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例：

PUT /inventory/managedObjects/8174669
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
{
    "c8y_ConfigurationDump": {
        "id": "<<4-3の応答に含まれるidの値>>"
    }
}

応答例：

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Content-Length: ...
{
    ...
    "creationTime": "2019-11-28T10:14:48.318+09:00",
    "lastUpdated": "2019-11-29T16:18:18.599+09:00",
    "name": "SampleDevice",
    "self": "https://.../inventory/managedObjects/8174669",
    "id": "8174669",
    "c8y_IsDevice": {},
    "c8y_Global": {},
    "c8y_SupportedOperations": [
        "c8y_UploadConfigFile"
    ],
    "c8y_ConfigurationDump": {
        "id": "8235277"
    }
}

構成スナップショットの適用

デバイスへ新しい設定情報を追加します。本機能を利用するためには c8y_SupportedOperations: ["c8y_DownloadConfigFile"] が必要です。

configuration-sequence

ステップ1. デバイスへ新しいスナップショットを追加

「構成」タブの「使用されている構成リポジトリエントリを選択」で構成スナップショットを選択します。その後、「デバイスへの新しいスナップショットの追加」をクリックします。

DownloadConfigulation

Things Cloud 内で以下のようなオペレーションが生成されます。

{
  "creationTime": "2019-12-02T10:41:37.180+09:00",
  "deviceName": "SampleDevice",
  "deviceId": "8174672",
  "self": "https://.../devicecontrol/operations/8174687",
  "id": "8174687",
  "status": "PENDING",
  "c8y_DownloadConfigFile": {
    "url": "https://.../inventory/binaries/8011023",
    "c8y_ConfigurationDump": {
      "id": "8174678"
    }
  },
  "description": "Apply configuration snapshot"
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_DownloadConfigFile の値はjsonオブジェクトとなります。
- urlはバイナリファイルがダウンロードできるURLとなります。
- c8y_ConfigurationDumpのidは構成スナップショット情報のManagedObjectIDとなります。

構成スナップショットは前節の「構成スナップショットの取得」で記載した機能を利用した登録の他、デバイス管理アプリケーションのGUIでも登録することができます。

DownloadConfigulation

「+ 構成スナップショットを追加」を押下して「構成スナップショットリポジトリ」の画面に遷移します。

DownloadConfigulation

「名前」「説明」「デバイスタイプ」「構成スナップショットファイル」に必要な情報を入力し、「構成スナップショットを追加」ボタンをクリックします。

「構成スナップショットファイル」には、ファイル取得用のURLを記載する、あるいはローカルに存在するファイルをアップロードすることが可能です。

本作業により、Things Cloud 内で以下のようなマネージドオブジェクトが生成されます。

{
  ...
  "creationTime": "2019-12-02T10:08:34.974+09:00",
  "type": "c8y_ConfigurationDump",
  "lastUpdated": "2019-12-02T10:08:34.974+09:00",
  "name": "Sample",
  "self": "https://.../inventory/managedObjects/8174678",
  "id": "8174678",
  "deviceType": "",
  "c8y_Global": {},
  "description": "",
  "url": "https://.../inventory/binaries/8011023"
}

nameは入力した構成スナップショットの名前となります。
id はこのマネージドオブジェクトを表すIDとなります。
deviceTypeと同じタイプを持つデバイスにのみ構成スナップショットを適用できます。
c8y_Globalの値は空のjsonオブジェクトとなります。
descriptionは説明が入ります。
urlはバイナリファイルがダウンロードできるURLとなります。

ここで、GUIからアップロードした構成スナップショットについては "c8y_Global": {} フラグメントが付与されていることに注目してください。これは、本作業によってアップロードされたスナップショットファイルについてはOwnerが強い権限（Business、Adminなど）であることが想定され、デバイスユーザの権限ではファイルの取得ができないといった不具合の発生が想定されるためです。

このように、特別の権限のないユーザーも含め全てのユーザーにオブジェクトへアクセスする許可を与える必要がある場合には "c8y_Global": {} フラグメントを付与することでうまく事象を解決できることがあります。

ステップ4-1. 設定ファイルを取得

c8y_DownloadConfigFile の url の値にアクセスしファイルをダウンロードします。

Things Cloud に保存した構成スナップショットファイルをダウンロードする際は、通常の Things Cloud へのAPIリクエストと同様に認証が必要となることに注意してください。

ステップ4-2. 設定値をデバイスに保存

ダウンロードした設定ファイルをデバイスに保存し、設定を反映します。

タブメニュー：ソフトウェア

「ソフトウェア」タブでは、デバイスのファームウェアとデバイスにインストールされているソフトウェアを管理および更新できます。

「ソフトウェア」タブは以下のフラグメントを対象となるデバイスに付与することで表示されます。（配列要素のいずれか1つが含まれていれば表示されます）

"c8y_SupportedOperations": [
  "c8y_SoftwareList",
  "c8y_Firmware"
]

デバイス上のソフトウェア更新

本機能は、指示されたソフトウェアコンポーネントおよびバージョンがインストールされている状態を確保するようリクエストします。本機能を利用するためには c8y_SupportedOperations: ["c8y_SoftwareList"] が必要です。

「ソフトウェア」ウィンドウの内容は、デバイスに付与された"c8y_SoftwareList"フラグメントの値が自動的に読み込まれます。

edit config

ステップ1-a-1. ソフトウェアリポジトリの「ソフトウェアを追加」押下

ソフトウェアの更新にあたり、事前にサイドバーの「管理」メニュー内にある「ソフトウェアリポジトリ」からソフトウェア情報を登録しておく必要があります。

サイドバーの「管理」メニュー内にある「ソフトウェアリポジトリ」から、ソフトウェアリポジトリ画面を表示し、画面右上の「ソフトウェアを追加」ボタンをクリックします。

表示されるウィンドウにソフトウェアの「名前」「バージョン」「ファイル」を入力し、「保存」ボタンをクリックします。

「ファイル」にはファイル取得用のURLを記載する、あるいはローカルに存在するファイルをアップロードすることが可能です。

edit config

ステップ1-a-2. ソフトウェア追加

ソフトウェアの追加を行うと、Things Cloud 内で以下のようにソフトウェアの情報が保存されます。

{
  "c8y_Global": {},
  "c8y_IsBinary": "",
  "contentType": "text/plain",
  "id": "393010",
  "lastUpdated": "2019-12-27T18:02:52.438+09:00",
  "length": 337,
  "name": "test.txt",
  "owner": "hogehoge@example.com",
  "self": "https://.../inventory/binaries/393010",
  "type": "text/plain"
}

contentTypeはアップロードするファイルのファイルタイプとなります。
idはこのオペレーションを表すIDとなります。
nameはアップロードするファイルのファイル名となります。

ステップ1-a-3．インストールするソフトウェアを選択し、「インストール」ボタン押下

「ソフトウェア」タブの「ソフトウェア」ウィンドウのプルダウンからインストールするソフトウェアを選択し、「インストール」ボタンをクリックします。

edit config

インストールするソフトウェアの情報がソフトウェアの一覧に追加されたことを確認してください。必要なソフトウェアを全て追加したら、「操作を送信」ボタンをクリックします。

なお、誤ったソフトウェアを追加してしまった場合は、対象のソフトウェアの行に表示される「×」マークをクリックするか、「変更をリセット」をクリックすることで変更をキャンセルできます。

ステップ1-a-4．オペレーション発行

Things Cloud®内で以下のようなオペレーションが生成されます。

{
  "creationTime": "2019-11-13T15:38:27.897+09:00",
  "deviceId": "256243",
  "deviceName": "device_001",
  "self": "https://.../devicecontrol/operations/392612",
  "id": "392612",
  "status": "PENDING",
  "c8y_SoftwareList": [
    {
      "name": "Software A",
      "version": "1.0.1",
      "url": "www.some-external-url.com"
    },
    {
      "name": "Software B",
      "version": "2.1.0",
      "url": "https://mytenant.je1.thingscloud.ntt.com/inventory/binaries/12345"
    },
    {
      "name": "TestSoftware",
      "version": "1.0.2",
      "url": "https://example.com"
    }
  ],
  "description": "Update device software."
}

deviceIdは選択しているデバイスのManagedObjectIDとなります。
deviceNameは選択しているデバイスの名前となります。
idはこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
statusはオペレーション生成時はPENDINGとなります。
c8y_SoftwareListの値にはインストール対象のソフトウェア情報が格納されます。

“c8y_SoftwareList” フラグメントは、各種のパッケージ管理システムにおける設定ファイルと同様の意味を持ちます。つまり、記載されていないソフトウェアを削除し、デバイスにまだインストールされていないソフトウェアをインストールし、異なるバージョンでインストールされているソフトウェアをアップグレードまたはダウングレードすべきであることを意味します。

ステップ4-1．ソフトウェアのインストール

ステップ2.で受け取ったc8y_SoftwareListの内容を元に、ソフトウェアのインストールを行います。

ステップ4-2．デバイス更新

ステップ4-2.でインストールしたソフトウェア内容をThings Cloud上のマネージドオブジェクトにも反映します。GUIと連動するためには、マネージドオブジェクトの　c8y_SoftwareList　フラグメントに配列として追加する必要があることに注意してください。

具体的には以下のAPIリクエストを行うことになります。

利用するAPI

PUT /inventory/managedObjects/<<ManagedObjectID>>

リクエスト例：

PUT /inventory/managedObjects/256243 HTTP/1.1
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
...
{
  "c8y_SoftwareList": [
    {
      "name": "Software A",
      "version": "1.0.1",
      "url": "www.some-external-url.com"
    },
    {
      "name": "Software B",
      "version": "2.1.0",
      "url": "https://mytenant.je1.thingscloud.ntt.com/inventory/binaries/12345"
    },
    {
      "name": "TestSoftware",
      "version": "1.0.2",
      "url": "https://example.com"
    }
  ]
}

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
...

デバイス上のファームウェア更新

本機能は、指示されたファームウェアのバージョンがインストールされている状態を確保するようリクエストします。本機能を利用するためには c8y_SupportedOperations: ["c8y_Firmware"] が必要です。

「ファームウェア」ウィンドウの内容は、デバイスに付与された"c8y_Firmware"フラグメントの値が自動的に読み込まれます。

edit config

ステップ1-a-1. ファームウェアリポジトリの「ファームウェアを追加」押下

サイドバーの「管理」メニュー内にある「ファームウェアリポジトリ」から、ファームウェアリポジトリ画面を表示し、画面右上の「ファームウェアを追加」ボタンをクリックします。

表示されるウィンドウにファームウェアの「名前」、「バージョン」、「ファイル」を入力し、「保存」ボタンをクリックします。「ファイル」はローカルPCにあるファイルもしくはURLを指定してください。

edit config

ステップ1-b-1．インストールするファームウェアを選択し、「インストール」ボタン押下

「ファームウェア」タブの「ファームウェア」ウィンドウのプルダウンからインストールするファームウェアを選択し、「インストール」ボタンをクリックします。

edit config

Things Cloud®内で以下のようなオペレーションが生成されます。

{
    "creationTime": "2019-11-13T14:33:16.027+09:00",
    "deviceId": "256243",
    "deviceName": "device_001",
    "self": "https://.../devicecontrol/operations/392608",
    "id": "392608",
    "status": "PENDING",
    "c8y_Firmware": {
        "name": "TestFirmware",
        "version": "0.8.3",
        "url": "https://.../inventory/binaries/392606"
    },
    "description": "ファームウェアを更新: TestFirmware - 0.8.3"
}

deviceIdは選択しているデバイスのManagedObjectIDとなります。
deviceNameは選択しているデバイスの名前となります。
idはこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
statusはオペレーション生成時はPENDINGとなります。
c8y_Firmwareの値にインストール済み、もしくはインストール予定のファームウェアが格納されます。

ステップ4-1．ファームウェアのインストール

ステップ2.で受け取ったc8y_Firmwareの内容を元に、ファームウェアのインストールを行います。

ステップ4-2．デバイス更新

ステップ4-2.でインストールしたファームウェア内容をThings Cloud上のマネージドオブジェクトにも反映します。GUIと連動するためには、マネージドオブジェクトのc8y_Firmwareフラグメントに追加する必要があることに注意してください。

具体的には以下のAPIリクエストを行うことになります。

利用するAPI

PUT /inventory/managedObjects/<<ManagedObjectID>>

リクエスト例：

PUT /inventory/managedObjects/256243 HTTP/1.1
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
...
{
    "c8y_Firmware": {
        "name": "TestFirmware",
        "version": "0.8.3",
        "url": "https://.../inventory/binaries/392606"
    }
}

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
...

タブメニュー：ネットワーク

「ネットワーク」タブは以下のフラグメントを対象となるデバイスに付与することで表示されます。

"c8y_Network": {}

表示される画面は以下の通りです。

edit config

WAN設定変更

「ネットワーク」タブの「WAN」ウインドウの中に記載した設定値をデバイスに向けて送信します。本機能を利用するためには c8y_SupportedOperations: ["c8y_Network.c8y_WAN"] が必要です。

configuration-sequence

ステップ1-a-1. 「設定の変更」押下

「ネットワーク」タブの「WAN」ウィンドウの中にある各設定項目を入力し、「変更を保存」をクリックします。

注：Things Cloud では「変更を保存（SMS）」の利用はできません。

edit config

Things Cloud®内で以下のようなオペレーションが生成されます。

{
  "creationTime": "2019-12-02T11:55:01.880+09:00",
  "deviceId": "8283793",
  "deviceName": "SampleDevice",
  "self": "https://.../devicecontrol/operations/8283963",
  "id": "8283963",
  "status": "PENDING",
  "c8y_Network": {
    "c8y_WAN": {
      "password": "user-password",
      "authType": "chap",
      "apn": "example.apn.com",
      "username": "test"
    }
  },
  "description": "Configure WAN settings"
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_Network の値はGUIで変更した設定情報です。

ステップ4-1. 設定値を変更

ステップ2.で受け取ったc8y_Networkの内容を元に、WANの設定情報をデバイスに設定します。

ステップ4-2. 設定値の変更を反映

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例：

Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
{
    "c8y_Network": {
        "c8y_WAN": {
            "password": "user-password",
            "authType": "chap",
            "apn": "example.apn.com",
            "username": "test",
            "simStatus":"SIM OK"
        }
    }
}

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
{

LAN設定変更

「ネットワーク」タブの「LAN」ウインドウの中に記載した値をデバイスに設定します。本機能を利用するためには c8y_SupportedOperations: ["c8y_Network.c8y_LAN"] が必要です。

また、「ネットワーク」タブの「LAN」ウィンドウにある「名前」と「MACアドレス」は必須であり、かつGUIからの変更は不可のため、事前にAPIでデバイスのManagedObjectに以下のフラグメントを追加しておく必要があります。

{
    "c8y_Network": {
        "c8y_LAN": {
            "name": "<<デバイスのNICの名前>>",
            "mac": "<<デバイスのMACアドレス>>"
        }
    }
}

例：

{
    "c8y_Network": {
        "c8y_LAN": {
            "name": "br0",
            "mac": "00:60:64:FF:D4:10"
        }
    }
}

この作業は、本機能を利用するデバイスの新規登録時にデバイスインテグレーションの一環として 実行しておくべき(SHOULD) 内容です。詳しくはREST開発者ガイド > デバイスインテグレーションのSTEP2、及びSTEP4を参照してください。

configuration-sequence

ステップ1-a-1. 「設定の変更」押下

「ネットワーク」タブの「LAN」ウィンドウの中にある「IPアドレス」「サブネットマスク」に値を入力し、「有効」「無効」を選択して「変更を保存」をクリックします。

edit config

Things Cloud®内で以下のようなオペレーションが生成されます。

{
  "creationTime": "2019-12-02T14:12:21.616+09:00",
  "deviceId": "8284649",
  "deviceName": "SampleDevice",
  "self": "https://.../devicecontrol/operations/8285616",
  "id": "8285616",
  "status": "PENDING",
  "c8y_Network": {
    "c8y_LAN": {
      "netmask": "255.255.255.0",
      "ip": "192.168.1.2",
      "enabled": 1
    }
  },
  "description": "Configure LAN settings"
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_Network の値はGUIで変更した設定情報です。
- enabled は「有効」の場合1、「無効」の場合0となります。

ステップ4-1. 設定値を取得

ステップ2.で受け取ったc8y_Networkの内容を元に、LANの設定情報をデバイスに設定します。

ステップ4-2. 設定値を変更

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例：

PUT /inventory/managedObjects/8284649
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;=ver...
{
  "c8y_Network": {
    "c8y_LAN": {
      "netmask": "255.255.255.0",
      "ip": "192.168.1.2",
      "name": "br0",
      "mac": "00:60:64:FF:D4:10",
      "enabled": 1
    }
  }
}

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Content-Length: ...
{

DHCP設定変更

本機能はDHCPサーバ向けの設定機能です。「ネットワーク」タブの「DHCP」ウィンドウの中に記載した値をデバイスに設定します。本機能を利用するためには c8y_SupportedOperations: ["c8y_Network.c8y_DHCP"] が必要です。

また、「ネットワーク」タブの「LAN」ウィンドウの状態が「無効」となっている場合、「DHCP」ウィンドウは設定不可となることに注意してください。

configuration-sequence

ステップ1. 「設定の変更」押下

「ネットワーク」タブの「DHCP」ウィンドウの中にある「アドレスの範囲」「DNS」「DNS2」「ドメイン名」を入力し、「有効」「無効」を選択して「変更を保存」をクリックします。

edit config

Things Cloud 内で以下のようなオペレーションが生成されます。

{
  "creationTime": "2019-12-02T15:00:36.129+09:00",
  "deviceId": "8284649",
  "deviceName": "SampleDevice",
  "self": "https://.../devicecontrol/operations/8286197",
  "id": "8286197",
  "status": "PENDING",
  "c8y_Network": {
    "c8y_DHCP": {
      "dns2": "192.168.1.201",
      "dns1": "192.168.1.200",
      "domainName": "example.com",
      "addressRange": {
        "start": "192.168.1.100",
        "end": "192.168.1.199"
      },
      "enabled": 1
    }
  },
  "description": "Configure DHCP settings"
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_Network の値はGUIで変更した設定情報です。
- enabled は「有効」の場合1、「無効」の場合0となります。

ステップ4-1. 設定値を変更

ステップ2.で受け取ったc8y_Networkの内容を元に、DHCPの設定情報をデバイスに設定します。

ステップ4-2. 設定値の変更を反映

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例：

Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
{
  "c8y_Network": {
    "c8y_DHCP": {
      "dns2": "192.168.1.201",
      "dns1": "192.168.1.200",
      "domainName": "example.com",
      "addressRange": {
        "start": "192.168.1.100",
        "end": "192.168.1.199"
      },
      "enabled": 1
    }
  }
}

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
{

タブメニュー：シェル

「シェル」タブは以下のフラグメントを対象となるデバイスに付与することで表示されます。

{
  "c8y_SupportedOperations": [
    "c8y_Command"
  ]
}

表示される画面は以下の通りです。

operation-gui-Shell

シェルコマンド送信

Things Cloudからデバイスに任意のコマンドを発行することができます。

本機能を利用するためには c8y_SupportedOperations: ["c8y_Command"] が必要です。

command-sequence

ステップ1. 「実行」押下

「コマンド」ウィンドウに任意のコマンドを入力し、「実行」を押下します。

Things CloudではSMSによるコマンド実行をサポートしていません。

operation-gui-Shell

Things Cloud 内で以下のようなオペレーションが生成されます。

{
    "deviceId": "169",
    "deviceName": "testDevice",
    "self": "https://.../devicecontrol/operations/172167",
    "id": "172167",
    "status": "PENDING",
    "c8y_Command": {
        "text": "command"
    },
    "description": "Execute shell command"
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_Command はデバイスに対するコマンド実行命令を表します。
- text の値はGUIで入力した文字列です。

なお、Things Cloudにはいくつかのデバイスで頻繁に使用されるコマンドが用意されています。トップメニューバーの右側にある「>_定義済みのコマンドを取得」をクリックすると、使用可能な事前定義済みコマンドのリストを含むウィンドウが開きます。目的のコマンドを選択し、「使用」をクリックしてそのコマンドをコマンドウィンドウにコピーするか、または、「実行」をクリックしてコマンドをすぐに実行することができます。

operation-gui-Shell

さらに、新規コマンドを追加して再利用することも可能です。「新規追加」をクリックし、「名前」「カテゴリ」「コマンドテンプレート」の値を入力して「保存」を押下してください。「保存」を行うと以下のマネージドオブジェクトが生成されます。

operation-gui-new-shell

事前に定義するコマンドは、同じデバイスタイプを持つデバイスのみが利用可能となることに注意してください。

{
  "creationTime": "2020-01-06T16:30:34.848+09:00",
  "type": "c8y_DeviceShellTemplate",
  "lastUpdated": "2020-01-06T16:30:34.848+09:00",
  "name": "再起動",
  "self": "https://.../inventory/managedObjects/145110",
  "id": "145110",
  "deviceType": "SampleType",
  "owner": "businessuser",
  "c8y_Global": {},
  "category": "デバイス",
  "command": "sudo reboot"
}

type の値は固定文字列です。
name の値は「名前」欄に入力した文字列です。
deviceType は選択しているデバイスのタイプになります。
owner はGUIへのログインユーザとなります。
c8y_Globalの値は空のjsonオブジェクトとなります。
category の値は「カテゴリ」欄に入力した文字列です。
command の値は「コマンドテンプレート」の欄に入力した文字列です。

ステップ4. コマンド実行

ステップ2.で受け取ったc8y_Commandの内容を元に、与えられたコマンドを実行します。

この際、c8y_Commandの値は自由文字列で与えられることに注意し、与えられたコマンドが実行可能か、不正なコマンドの実行を要求されていないか、等に注意することが必要です。デバイス側では可能な限り事前定義されたコマンドのみを実行するような実装と しておくべき(SHOULD) です。

ステップ5. オペレーション更新

ステップ4. におけるコマンドの実行結果を更新します。

この際、通常のステップ5. におけるオペレーションの "status" の更新に加え、「シェル」タブでの実行結果をThings Cloudに通知するために "c8y_Command" の更新も同時に行うことで、より詳細にデバイスのコマンド実行結果を管理することができます。

Things Cloudでは c8y_Command.result の値をコマンド実行結果の格納のために利用することを推奨しています。この際、元のコマンド実行命令の内容を保持するために c8y_Command.text の値も合わせて送信する必要があることに注意してください。

利用するAPI

PUT /devicecontrol/operations/<<operationId>>

リクエスト例

PUT /devicecontrol/operations/172167 HTTP/1.1
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.operation+json;ver=...
...
{
  "status": "SUCCESSFUL",
  "c8y_Command": {
    "text": "command",
    "result": "Success"
  }
}

応答例

PUT /devicecontrol/operations/172167
Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
...
{
  "deviceId": "169",
  "deviceName": "testDevice",
  "self": "https://.../devicecontrol/operations/172167",
  "id": "172167",
  "status": "SUCCESSFUL",
  "c8y_Command": {
    "text": "command",
    "result": "Success"
  },
  "description": "Execute shell command"
}

タブメニュー：ログ

「ログ」タブは以下のフラグメントを対象となるデバイスに付与することで表示されます。

{
  "c8y_SupportedOperations": [
    "c8y_LogfileRequest"
  ]
}

表示される画面は以下の通りです。

Log GUI

ログファイル取得

デバイスにログファイル送信を要求します。本機能を利用するためには、"c8y_SupportedOperations": ["c8y_LogfileRequest"]　が必要です。

また、本機能を用いてログ取得を行う場合、対象となるログファイル種別を指定する必要があります。ログファイル種別はリストによる選択形式となるため、事前に対象となるデバイスに対し以下のフラグメントを付与し、利用可能な値を定義しておく必要があります。ログファイル種別は任意の文字列を指定することが可能です。

指定例

{
  "c8y_SupportedLogs": [
    "dmesg",
    "logread",
    "ipsec",
    "customlog"
  ]
}

logview-sequence

ステップ1. 「ログの要求」押下

「ログ」タブでトップメニューバーの右側にある「ログファイルをリクエスト」をクリックします。

表示されるウィンドウで、ログ情報に次の設定を指定します。

Request Logs

「開始日」、「終了日」：取得対象となる日付と時間の範囲を指定します。
「ログのタイプ」：対象となるデバイスの "c8y_SupportedLogs" の値に指定されている値が選択可能となります。
「テキストで絞り込む」：ログをフィルタリングするオプションのテキストを指定します。
- 例えば「error」と入力すると、「error」という文字列を含む行のみを含むログを返却するようなデバイス側実装のために利用されます。
「表示する最終行」：取得するログの最大行数を指定します。デフォルト値は1000です。

Things Cloud 内で以下のようなオペレーションが生成されます。

{
  "deviceId": "169",
  "deviceName": "testDevice",
  "id": "172161",
  "status": "PENDING",
  "c8y_LogfileRequest": {
    "searchText": "error",
    "logFile": "dmesg",
    "dateTo": "2019-11-18T09:29:57+0900",
    "dateFrom": "2019-11-17T09:29:57+0900",
    "maximumLines": 100
  },
  "description": "Log file request"
}

deviceId は選択しているデバイスのManagedObjectIDとなります。
deviceName は選択しているデバイスの名前となります。
id はこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
status はオペレーション生成時は PENDING となります。
c8y_LogfileRequest はデバイスに対するログファイル取得命令を表します。
- searchText の値は「テキストで絞り込む」の欄に入力した文字列です。
- logFile の値は「ログのタイプ」で選択したタイプ名です。
- dateTo の値は「開始日」で指定した日時です。
- dateFrom の値は「終了日」で指定した日時です。
- maximumLines の値は「表示する最終行」の欄に入力した数値です。

ステップ4-1．. ログ取得

ステップ2.で受け取ったc8y_LogfileRequestの内容を元に、指定された条件に従ってログを収集します。

日時、検索文字、最大行数等のフィルタリング処理は、デバイス個々の環境に応じた実装を行ってください。

ステップ4-2. ログファイル送信

ステップ4-1. で取得したログを Things Cloud にファイルとしてアップロードします。このファイルはThings Cloud 内では「バイナリ」として扱われ、「管理」アプリケーション内の「ファイルリポジトリ」で管理されます。

具体的には以下のAPIリクエストを行うことになります。

利用するAPI

POST /inventory/binaries

リクエスト例

POST /inventory/binaries
Host: ...
Authorization: Basic ...
Content-Type: multipart/form-data; boundary=--myBoundary

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

{
  "name":"dmesg",
  "type":"text/plain"
}
--myBoundary
Content-Disposition: form-data; name="filesize"

12345
--myBoundary
Content-Disposition: form-data; name="file"; filename="dmesg"
Content-Type: text/plain

<<file content>>
--myBoundary

応答例

Location としてログファイルのオブジェクトが生成されます。この値をログファイルの応答で使用します。

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Location: https://.../inventory/binaries/172164

ステップ5．オペレーション更新

オペレーション更新によりログ要求の結果をThing Cloud に送信します。

fileは、ステップ4−2の応答で取得したLocationの値を指定してください。

ステップ4. におけるログ要求の結果を更新します。

この際、通常のステップ5. におけるオペレーションの "status" の更新に加え、"c8y_LogfileRequest" の更新も同時に行うことで、「ログ」タブの中で取得したログファイルの情報を閲覧することが可能になります。

Things Cloudでは c8y_LogfileRequest.file に対する値としてステップ4-2. で取得したバイナリの"self"の値を送信します。この際、元のログファイル取得命令の内容を保持するためにその他の c8y_LogfileRequest の値も合わせて送信する必要があることに注意してください。

利用するAPI

PUT /devicecontrol/operations/<<operationId>>

リクエスト例：

PUT /devicecontrol/operations/172161
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.operation+json;ver=...
...
{
  "status": "SUCCESSFUL",
  "c8y_LogfileRequest": {
    "searchText": "error",
    "logFile": "dmesg",
    "dateTo": "2019-11-18T09:29:57+0900",
    "dateFrom": "2019-11-17T09:29:57+0900",
    "maximumLines": 100,
    "file": "<<4-2.の応答に含まれるselfのurl>>"
  }
}

応答例：

{
    "creationTime": "2019-11-18T09:45:47.769+09:00",
    "deviceId": "169",
    "deviceName": "testDevice",
    "self": "https://.../devicecontrol/operations/172161",
    "id": "172161",
    "status": "SUCCESSFUL",
    "c8y_LogfileRequest": {
        "searchText": "error",
        "file": "https://.../inventory/binaries/172164",
        "logFile": "dmesg",
        "dateTo": "2019-11-18T09:29:57+0900",
        "dateFrom": "2019-11-17T09:29:57+0900",
        "maximumLines": 100
    },
    "description": "Log file request"
}

タブメニュー：Modbus

「Modbus」タブは以下のフラグメントを対象となるデバイスに付与することで表示されます。

{
  "com_cumulocity_model_Agent": {},
  "c8y_SupportedOperations": [
    "c8y_ModbusDevice"
  ],
  "c8y_ModbusConfiguration": {
    "protocol": "TCP",
    "transmitRate": 1200,
    "pollingRate": 10,
    "maxFieldbusVersion": 5
  },
  "c8y_SerialConfiguration": {
    "baudRate": 19200,
    "stopBits": 1,
    "parity": "E",
    "dataBits": 8
  }, 
  "c8y_IsDevice": {},
  "c8y_ModbusDevice": { "active":true },
  "c8y_Modbus": { "active":true },
}

表示される画面は以下の通りです。

Modbus GUI

Modbusデバイスの追加

本機能は、対象となるデバイスの小デバイスとして、Modbusデバイスを追加する事ができます。

ステップ1-a-1. 「TCP/RTUデバイスを追加」を実行

Modbusタブにて、「TCPデバイスを追加」もしくは「RTUデバイスを追加」を押下します。

Modbus GUI

必要な事項を入力し、「追加」ボタンを押下することで、以下のようなオペレーション要求が発行されます。また、オペレーションの発行とともに子デバイスのMOが生成されます。

{
  "creationTime": "2020-08-27T11:33:29.362+09:00",
  "deviceId": "508402",
  "deviceName": "testDevice",
  "self": "https://...../devicecontrol/operations/538284",
  "id": "538284",
  "status": "PENDING",
  "c8y_ModbusDevice": {
    "protocol": "TCP",
    "address": 1,
    "name": "childtest",
    "ipAddress": "192.168.1.1",
    "id": "538283",
    "type": "/inventory/managedObjects/182391"
  },
  "description": "Added new child device to \"testDevice\" (ID: 508402)."
}

deviceIdは選択しているデバイスのManagedObjectIDとなります。
deviceNameは選択しているデバイスの名前となります。
idはこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
statusはオペレーション生成時はPENDINGとなります。
c8y_ModbusDeviceはGUIで設定した値が格納されます。

4. 設定値の変更

GUIで設定したIPアドレスの値をModbusデバイスに反映します。

シリアル接続設定の変更

本機能は、対象デバイスのシリアル接続設定を変更する事ができます。本機能を使用するためには、以下のフラグメントを追加する必要があります。

{
  "c8y_SupportedOperations": [
    "c8y_SerialConfiguration"
  ]
}

Modbus flow

ステップ1-a-1. 「変更を保存」押下

Modbusタブ内の、シリアル接続において、必要事項を入力し、「変更を保存」を押下します。

Modbus GUI

デバイスにてオペレーションを所得することで、以下のようなオペレーション要求が確認出来ます。

{
  "creationTime": "2020-08-27T11:51:51.311+09:00",
  "deviceId": "508402",
  "deviceName": "testDevice",
  "self": "https://...../devicecontrol/operations/538728",
  "id": "538728",
  "status": "PENDING",
  "c8y_SerialConfiguration": {
    "baudRate": 19200,
    "stopBits": 2,
    "parity": "E",
    "dataBits": 8
    },
  "description": "Set serial configuration"
}

deviceIdは選択しているデバイスのManagedObjectIDとなります。
deviceNameは選択しているデバイスの名前となります。
idはこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
statusはオペレーション生成時はPENDINGとなります。
c8y_SerialConfigurationはGUIで設定した値が格納されます。

ステップ4-1. 設定値を変更

受け取ったc8y_SerialConfigurationの値を参照し、デバイスの設定値を変更します。

ステップ4-2. 設定値の変更を反映

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例

Host: ...
Authorization: Basic ...
Content-Type: application/json
Accept: application/json
{
  "c8y_SerialConfiguration": {
    "baudRate": 19200,
    "stopBits": 2,
    "parity": "E",
    "dataBits": 8
  }
}

応答例

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json;charset=UTF-8;ver=0.9
{
    ...

    "creationTime": "2020-08-26T14:48:07.375+09:00",
    "type": "Sample_type",
    "lastUpdated": "2020-09-03T16:10:47.106+09:00",
    "name": "test",
    "self": "https://...../inventory/managedObjects/508402",
    "id": "508402",

    ...

    "c8y_SerialConfiguration": {
        "baudRate": 19200,
        "stopBits": 2,
        "parity": "E",
        "dataBits": 8
    }
}

Modbus通信設定の変更

本機能は、Modbus通信設定の変更を行う事ができます。本機能を使用するためには、以下のフラグメントを追加する必要があります。

{
  "c8y_SupportedOperations": [
    "c8y_ModbusConfiguration"
  ]
}

ステップ1-a-1. 「変更を保存」押下

Modbusタブ内の、Modbus 通信において、必要事項を入力し、「変更を保存」を押下します。

Modbus GUI

デバイスにてオペレーションを所得することで、以下のようなオペレーション要求が確認出来ます。

{
  "creationTime": "2020-08-27T11:58:55.651+09:00",
  "deviceId": "508402",
  "deviceName": "testDevice",
  "self": "https://...../devicecontrol/operations/538903",
  "id": "538903",
  "status": "PENDING",
  "description": "Set modbus configuration",
  "c8y_ModbusConfiguration": {
    "protocol": "TCP",
    "transmitRate": 1200,
    "pollingRate": 10
  }  
}

deviceIdは選択しているデバイスのManagedObjectIDとなります。
deviceNameは選択しているデバイスの名前となります。
idはこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
statusはオペレーション生成時はPENDINGとなります。
c8y_ModbusConfigurationはGUIで設定した値が格納されます。

ステップ4-1. 設定値を変更

受け取ったc8y_ModbusConfigurationの値を参照し、デバイスの設定値を変更します。

ステップ4-2. 設定値の変更を反映

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例

Host: ...
Authorization: Basic ...
Content-Type: application/json
Accept: application/json
{
  "c8y_ModbusConfiguration": {
    "protocol": "TCP",
    "transmitRate": 1200,
    "pollingRate": 10
  }
}

応答例

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json;charset=UTF-8;ver=0.9
{
    ...

    "creationTime": "2020-08-26T14:48:07.375+09:00",
    "type": "Sample_type",
    "lastUpdated": "2020-09-03T16:00:47.106+09:00",
    "name": "test",
    "self": "https://...../inventory/managedObjects/508402",
    "id": "508402",

    ...

    "c8y_ModbusConfiguration": {
      "protocol": "TCP",
      "transmitRate": 1200,
      "pollingRate": 10
    }
}

コイル・レジスターの設定

本機能は、登録した子デバイスの、コイルやレジスタの値を変更できます。本機能を使用するには、それぞれ以下のフラグメントを追加する必要があります。

{
  "c8y_SupportedOperations": [
    "SetCoil",
    "SetRegister"
  ]
}

Modbus flow

ステップ1-a-1. 各種ボタン押下

コックピットアプリケーションに移動し、ダッシュボードにて「フィールドバスデバイスウィジェット」を追加します。

Modbus GUI

追加されたウィジェット上に存在する、Coilボタンを押下する事でc8y_SetCoilオペレーションが、レジスタの値を入力し、「設定」ボタンを押下する事でc8y_SetRegisterオペレーションがそれぞれ発行されます。

Modbus GUI

デバイスにてオペレーションを所得することで、以下のようなオペレーション要求が確認出来ます。

{
  "creationTime": "2020-08-27T13:52:50.694+09:00",
  "deviceId": "541624",
  "deviceName": "childtest",
  "self": "https://...../devicecontrol/operations/541660",
  "id": "541660",
  "status": "PENDING",
  "description": "Change status of \"Coil\" to \"1\".",
  "c8y_SetCoil": {
    "input": false,
    "coil": 1,
    "address": 1,
    "value": 1
  }
}

{
  "creationTime": "2020-08-27T13:53:01.343+09:00",
  "deviceId": "541624",
  "deviceName": "childtest",
  "self": "https://...../devicecontrol/operations/541669",
  "id": "541669",
  "status": "PENDING",
  "description": "Change value of \"Reg1\" to 4.",
  "c8y_SetRegister": {
    "input": false,
    "address": 1,
    "startBit": 0,
    "noBits": 16,
    "ipAddress": "192.168.1.1",
    "value": 4,
    "register": 1
  }
}

deviceIdは選択しているデバイスのManagedObjectIDとなります。
deviceNameは選択しているデバイスの名前となります。
idはこのオペレーションを表すIDとなります。以降のステップではこのIDを指定してオペレーション更新を行っていきます。
statusはオペレーション生成時はPENDINGとなります。
c8y_SetCoilおよびc8y_SetRegisterは、GUIで設定した値になります。

ステップ4-1. 設定値を変更

受け取ったフラグメントの値を参照し、デバイスの設定値を変更します。

ステップ4-2. 設定値の変更を反映

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例

Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
{
    "c8y_SetCoil":{
        "input": false,
        "coil": 1,
        "address": 1,
        "value": 1
    }
}

応答例

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json;charset=UTF-8;ver=0.9
{
    ...

    "creationTime": "2020-08-26T14:48:07.375+09:00",
    "type": "Sample_type",
    "lastUpdated": "2020-09-03T16:23:47.106+09:00",
    "name": "test",
    "self": "https://...../inventory/managedObjects/508402",
    "id": "508402",

    ...

    "c8y_SetCoil":{
        "input": false,
        "coil": 1,
        "address": 1,
        "value": 1
    }
}

その他のオペレーション

測定調査を開始

本機能は、指示された測定間隔で測定時間のデバイスのリソースモニターを取得をリクエストします。測定するリソースはデバイス固有の情報となり、例えばCPU使用率、メモリ使用率、ネットワークの利用状況があげられます。

リクエストを受け取ったデバイスは、オペレーションを実行中に更新し、測定時間の測定間隔の周期タイマータスクを作成するなどして測定を行い、収集したデータをメジャーメントとしてTingsCloudに送信します。

測定時間での測定が完了し次第、オペレーションを完了に更新します。

本機能を利用するためは、 "c8y_SupportedOperations":["c8y_MeasurementPollFrequencyOperation"]　のフラグメントが必要です。

operation-flow

ステップ1-a-1. 「測定調査を開始」押下

デバイス管理機能から、対象のデバイスを選択し「もっと見る」から「測定調査を開始」を選択します。

operation-gui-support

FREQUENCY に収集する間隔（秒）、DURATIONに収集時間（分）を入力します。

operation-gui-support

デバイスにてオペレーションを所得することで、以下のようなオペレーション要求が確認出来ます。

{
    "operations": [
        {
            "creationTime": "2019-11-27T14:21:27.314+09:00",
            "deviceName": "testDevice",
            "deviceId": "169",
            "self": "https://...../devicecontrol/operations/172504",
            "id": "172504",
            "status": "PENDING",
            "description": "Initiate measurement poll",
            "c8y_MeasurementPollFrequencyOperation": {
                "duration": 10,
                "frequency": 10
            }
        }
    ]
}

duration: 測定時間（分）
frequency:測定（秒）

ステップ3. オペレーションの更新

オペレーションを実行中に更新します。

利用するAPI

PUT {{url}}/devicecontrol/operations/<<deviceId>>

リクエスト例:

{
	"status": "EXECUTING"
}

レスポンス例:

{
    "creationTime": "2019-11-27T14:21:27.314+09:00",
    "deviceName": "testDevice",
    "deviceId": "169",
    "self": "https://...../devicecontrol/operations/172504",
    "id": "172504",
    "status": "EXECUTING",
    "description": "Initiate measurement poll",
    "c8y_MeasurementPollFrequencyOperation": {
        "duration": 10,
        "frequency": 10
    }
}

ステップ4-2. メジャーメントの送信

デバイス固有の測定値例えば、CPU使用率、メモリ使用率、ディスク使用率、ネットワーク使用状況などを収集し、メジャーメントとして送信します。詳細はメジャーメントAPIをご参照願います。

使用するAPI

POST {{url}}/measurement/measurements

リクエストメジャーメントコレクション使用しCPU使用率、メモリ使用率、ネットワーク使用情報をリクエストした例:

POST /measurement/measurements
Host: ...
Authorization: Basic ...
Content-Type: application/json
Accept: application/vnd.com.nsn.cumulocity.measurementCollection+json
{
  "measurements": [
    { 
      "time": "2019-12-03T07:32:47.267Z",
      "source": {
        "id": "169"
      },
      "type": "c8y_CPUMeasurement",
      "c8y_CPUMeasurement": {
        "Workload": {
          "value": 99,
          "unit": "%"
        }
      }
    },
    {
      "time": "2019-12-03T07:32:47.267Z",
      "source": {
        "id": "169"
      },
      "type": "c8y_MemoryMeasurement",
      "c8y_MemoryMeasurement": {
        "Used": {
          "value": 99,
          "unit": "MB"
        },
        "Total": {
          "value": 2000,
          "unit": "MB"
        }
      }
    },
    {
      "time": "2019-12-03T07:32:47.267Z",
      "source": {
        "id": "169"
      },
      "type": "c8y_NetworkStatistics",
      "c8y_NetworkStatistics": {
              "Download": {
          "value": 100,
          "unit": "KB/s"
        },
        "Upload": {
          "value": 200,
          "unit": "KB/s"
        }
      }
    }
  ]
}

計測値を取得

本機能は、デバイスのリソース取得をリクエストします。測定するリソースはデバイス固有の情報となり、例えばCPU使用率、メモリ使用率、ネットワークの利用状況があげられます。測定調査とは異なり、1度の実行につき1回のリソースリクエストになります。

リクエストを受け取ったデバイスは、オペレーションを実行中に更新し、収集したデータをメジャーメントとしてTingsCloudに送信します。

本機能を利用するためは、 "c8y_SupportedOperations":["c8y_MeasurementRequestOperation"]　のフラグメントが必要です。

ステップ1-a-1. 「測定値を取得」押下

デバイス管理機能から、対象のデバイスを選択し「もっと見る」から「測定値を取得」を選択します。

operation-gui-support

デバイスにてオペレーションを所得することで、以下のようなオペレーション要求が確認できます。

{
    "operations": [
        {
            "creationTime": "2020-08-26T15:22:33.657+09:00",
            "deviceId": "1295000",
            "deviceName": "testDevice",
            "self": "https://...../devicecontrol/operations/3439503",
            "id": "3439503",
            "status": "PENDING",
            "description": "Get measurements",
            "c8y_MeasurementRequestOperation": {
                "requestName": "LOG"
            }
        }
    ]
}

ステップ4-1 計測値の取得

デバイスの測定値を取得します。

ステップ4-2 メジャーメントの送信

利用するAPI

POST /measurement/measurements

リクエスト例

Host: ...
Authorization: Basic ...
Content-Type: application/json
Accept: application/vnd.com.nsn.cumulocity.measurement+json
{
    "c8y_TemperatureMeasurement": {
    	"T": { 
            "value": 25,
            "unit": "C" }
        },
    "time":"2020-09-03T17:03:14.000+02:00", 
    "source": {
    	"id":"508402" }, 
    "type": "c8y_TemperatureMeasurement"
}

応答例

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;charset=UTF-8;ver=0.9
Location: https://...../measurement/measurements/786089
{
    "self": "https://...../measurement/measurements/786089",
    "time": "2020-09-03T17:03:14.000+02:00",
    "id": "786089",
    "source": {
        "self": "https://...../inventory/managedObjects/508402",
        "id": "508402"
    },
    "type": "c8y_TemperatureMeasurement",
    "c8y_TemperatureMeasurement": {
        "T": {
            "unit": "C",
            "value": 25
        }
    }
}

デバイス再起動

本機能を利用するためは、 "c8y_SupportedOperations":["c8y_Restart"]　のフラグメントが必要です。

デバイス管理アプリの該当デバイスのページに「もっと見る > デバイスを再起動」のメニューが追加されます
デバイスを再起動を実行すると以下のようなオペレーションが生成されます

{
  "creationTime": "2019-10-23T20:50:45.711+09:00",
  "deviceId": "37501",
  "deviceName": "NTC-6200-12 (S/N 166311152950106)",
  "self": "https://yoshino.iot-trialpack.com/devicecontrol/operations/143775",
  "id": "143775",
  "status": "PENDING",
  "description": "Restart device",
  "c8y_Restart": { }
}

リレー制御

本機能は、リレー制御における開閉を設定できます。本機能を利用するためは、 "c8y_SupportedOperations":["c8y_Relay"]　のフラグメントが必要です。

relay-flow

ステップ1-a-1. ボタン押下

対象となるデバイスを含むグループにおいて、ダッシュボードを作成します。その後ウィジェットを追加メニューから、リレー制御を選択します。

operation-gui-support

追加されたウィジェト上のトグルボタンを押下します。

operation-gui-support

デバイスにてオペレーションを所得することで、以下のようなオペレーション要求が確認できます。

{
    "operations": [
        {
            "creationTime": "2020-08-26T16:42:02.653+09:00",
            "deviceId": "1295000",
            "deviceName": "testDevice",
            "self": "https://...../devicecontrol/operations/3445223",
            "id": "3445223",
            "status": "PENDING",
            "description": "Close relay",
            "c8y_Relay": {
                "relayState": "CLOSED"
            }
        }
    ]
}

ステップ4-1. 設定値を変更

受け取ったc8y_Relayの値を参照し、デバイスの設定値を変更します。

ステップ4-2. 設定値の変更を反映

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例

Host: ...
Authorization: Basic ...
Content-Type: application/json
Accept: application/json
{
    "c8y_Relay":{
        "relayState": "CLOSED"
    }
}

応答例

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json;charset=UTF-8;ver=0.9
{
    ...

    "creationTime": "2020-08-26T14:48:07.375+09:00",
    "type": "Sample_type",
    "lastUpdated": "2020-09-03T16:49:47.106+09:00",
    "name": "test",
    "self": "https://...../inventory/managedObjects/508402",
    "id": "508402",

    ...

    "c8y_Relay": {
        "relayState": "CLOSED"
    }
}

リレーアレイ制御

本機能は、複数のリレーの開閉を一括で設定できます。本機能を利用するためは、 "c8y_SupportedOperations":["c8y_RelayArray"]　のフラグメントが必要です。

さらに、対象となるデバイスには、 "c8y_RelayArray":["OPEN","OPEN"] のような状態配列を持つフラグメントを追加しておく必要があります。

ステップ1-a-1. ボタン押下

リレー制御と同様に、ダッシュボード上でリレーアレイ制御ウィジェットを選択します。

operation-gui-support

追加されたウィジェット上の任意のトグルボタンを押下します。

デバイスにてオペレーションを所得することで、以下のようなオペレーション要求が確認できます。

{
    "operations": [
        {
            "creationTime": "2020-08-26T16:20:28.082+09:00",
            "deviceId": "1295000",
            "deviceName": "testDevice",
            "self": "https://...../devicecontrol/operations/3443667",
            "id": "3443667",
            "status": "PENDING",
            "description": "リレー 1 を閉じる",
            "c8y_RelayArray": [
                "CLOSED",
                "OPEN"
            ]
        }
    ]
}

ステップ4-1. 設定値を変更

受け取ったc8y_RelayArrayの値を参照し、デバイスの設定値を変更します。

ステップ4-2. 設定値の変更を反映

利用するAPI

PUT /inventory/managedObjects/<<生成されたオペレーションのdeviceIdの値>>

リクエスト例

Host: ...
Authorization: Basic ...
Content-Type: application/json
Accept: application/json
{
    "c8y_RelayArray": [
        "CLOSED",
        "OPEN"
    ]
}

応答例

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json;charset=UTF-8;ver=0.9
{
    ...

    "creationTime": "2020-08-26T14:48:07.375+09:00",
    "type": "Sample_type",
    "lastUpdated": "2020-09-03T17:08:41.410+09:00",
    "name": "test",
    "self": "https://...../inventory/managedObjects/508402",
    "id": "508402",

    ...

    "c8y_RelayArray": [
      "CLOSED",
      "OPEN"
    ]
}

概要

デバイス詳細情報画面のタブで実行できるオペレーション

デバイス詳細情報画面の「もっと見る」で実行できるオペレーション

デバイス管理アプリ（GUI）におけるオペレーション利用方法

タブメニュー：制御

タブメニュー：構成

デバイス設定変更

ステップ1．設定値を更新し「保存」ボタン押下

ステップ4-1．設定値を変更

ステップ4-2. デバイス更新

現在のデバイス設定送信要求

ステップ1．再読み込みを押下

ステップ4-1．設定値を変更

ステップ4-2. デバイス更新

構成スナップショットの取得

ステップ１. 「デバイスから新しいスナップショットを取得」押下

ステップ4-1．設定値を取得

ステップ4-2. バイナリファイルアップロード

ステップ4-3. 構成スナップショット追加

ステップ4-4. デバイス更新

構成スナップショットの適用

ステップ1. デバイスへ新しいスナップショットを追加

ステップ4-1. 設定ファイルを取得

ステップ4-2. 設定値をデバイスに保存

タブメニュー：ソフトウェア

デバイス上のソフトウェア更新

ステップ1-a-2. ソフトウェア追加

ステップ1-a-3．インストールするソフトウェアを選択し、「インストール」ボタン押下

ステップ1-a-4． オペレーション発行

ステップ4-1．ソフトウェアのインストール

ステップ4-2．デバイス更新

デバイス上のファームウェア更新

ステップ1-a-1. ファームウェアリポジトリの「ファームウェアを追加」押下

ステップ1-b-1．インストールするファームウェアを選択し、「インストール」ボタン押下

ステップ4-1．ファームウェアのインストール

ステップ4-2．デバイス更新

タブメニュー：ネットワーク

WAN設定変更

ステップ4-1. 設定値を変更

ステップ4-2. 設定値の変更を反映

LAN設定変更

ステップ1-a-1. 「設定の変更」押下

ステップ4-1. 設定値を取得

ステップ4-2. 設定値を変更

DHCP設定変更

ステップ4-1. 設定値を変更

ステップ4-2. 設定値の変更を反映

タブメニュー：シェル

シェルコマンド送信

ステップ1. 「実行」押下

ステップ4. コマンド実行

ステップ5. オペレーション更新

タブメニュー：ログ

ログファイル取得

ステップ1. 「ログの要求」押下

ステップ4-1．. ログ取得

ステップ4-2. ログファイル送信

ステップ5．オペレーション更新

タブメニュー：Modbus

Modbusデバイスの追加

ステップ1-a-1. 「TCP/RTUデバイスを追加」を実行

4. 設定値の変更

シリアル接続設定の変更

ステップ1-a-1. 「変更を保存」押下

ステップ4-1. 設定値を変更

ステップ4-2. 設定値の変更を反映

Modbus通信設定の変更

ステップ1-a-1. 「変更を保存」押下

ステップ4-1. 設定値を変更

ステップ4-2. 設定値の変更を反映

コイル・レジスターの設定

ステップ1-a-1. 各種ボタン押下

ステップ4-1. 設定値を変更

ステップ4-2. 設定値の変更を反映

その他のオペレーション

測定調査を開始

ステップ1-a-1. 「測定調査を開始」押下

ステップ3. オペレーションの更新

ステップ4-2. メジャーメントの送信

計測値を取得

ステップ1-a-4．オペレーション発行