Observable を活用したIoTデータ可視化の探索からカスタムウィジェット開発までのチュートリアル

投稿日 / 更新日 / 投稿者名

2022.2.10 / 2024.9.9 / アプリチーム

はじめに

本レポートは、Things Cloud の利用例をより知っていただくための実利用レポートとして作成したものです。
Things Cloud は極力後方互換性を持つよう開発されていますが、今後のリリースにより、一部画面やコマンド、手順などが変更となったり、利用できない可能性があることをあらかじめご了承ください。
なお、作成にあたり、以下バージョンを用いています。

• ver.1018.0.259（Frontend）
  
  

難易度　★★

所要時間（目安）

60分

概要

本レポートでは、ノートブック型 JavaScript 実行環境を提供するプラットフォーム Observable を活用したIoTデータ可視化の探索方法と、Observable 上で作成したアウトプット（グラフ、表など）を Things Cloud のカスタムウィジェットへ移行する方法を紹介します。

カスタムウィジェット開発には通常であればプログラミング経験や前提知識を要しますが、本レポートでは、カスタムウィジェットや Observable ノートブックのテンプレートを提供しています。Things Cloud 特有の前提知識が必要となる箇所を最小限にしているため、0からカスタムウィジェットを開発するよりも小さなコストで開発でき、IoT データ可視化の探索や試行錯誤に注力いただけます。

Observable の詳細な使い方については NTT Communications Engineer's Blog でもご紹介しています。是非ご覧ください。

前提条件

• 以下を扱えること
  • JavaScript/TypeScript
  • REST API
• カスタムウィジェット開発に必要な環境を準備していること
  • Node.js (v10.16.3以上推奨)
  • npm (Node.js と一緒にインストールされます)
  • @c8y/cli パッケージ (c8ycli コマンドの使用に必要です)
• 基本的な Things Cloud のデータモデル(Alarm, Managed Object など)の理解があること
• (望ましい) Observable の利用経験
  • Observable は、ノートブック型 JavaScript 実行環境を提供するプラットフォームです。主にデータの探索や量的な事象を可視化するのに用いられ、ノートブックを共有、共同編集、フォークする、などコラボレーション機能も多く備えています。
    本記事で紹介している方法で Observable を利用する場合、新規アカウント作成は不要です。本記事の Notebook を Fork したり、新規 Notebook をご利用になる場合は必要に応じてアカウントを作成してください。
  • 本レポートのカスタムウィジェットテンプレートに対応しているライブラリは Observable Plot (npm) です。

本レポートでは、通常のカスタムウィジェット開発で必要とされる、以下スキルについては極力不要となるように考慮されています。

• @c8y/client
• @c8y/ngx-components
• Web SDK for Angular

完成イメージ

備考: 棒グラフはThings Cloudの標準ウィジェット機能では提供されておりません。 本記事では、ObservableのPlotライブラリを用い、簡単に作成しています。

開発の流れ

以下の流れで作業を進めます。

1. ダウンロード、ローカルで確認
2. データの前準備
3. Observable側の準備
4. カスタムウィジェットの準備
5. ローカルで確認
6. デプロイ

1. ダウンロード、ローカルで確認

作業の流れ

この章の操作をgifアニメーションにしています。クリックすると拡大して表示されます。

テンプレートzip をダウンロード

以下のファイルをダウンロードします。

• テンプレートzip(cockpit-chart.zip)

zip ファイルを解凍し、適当なディレクトリに保存して下さい。ここがカスタムウィジェットプログラムを作成するディレクトリになります。

ファイル構成

以下の17ファイルが解凍されます。

└─cockpit-chart
        app.module.spec.ts
        app.module.ts
        chart-template-config.component.ts
        chart-template.component.css
        chart-template.component.html
        chart-template.component.ts
        chart-template.service.ts
        i18n.ts
        index.ts
        jest.config.js
        ng1.ts
        package.json
        polyfills.ts
        preview-chart-template.png
        setup-jest.js
        tsconfig.json
        tsconfig.spec.json

ファイルについて

本記事では、以下２ファイルを編集します。

以下ファイルはビルドに必要なものですが、編集不要です。

ビルド

ダウンロードしたテンプレート zip にはサンプルのウィジェットが含まれていますので、正常に構築できるか試しましょう。

ビルド、実行には Node.js および c8ycli をインストールする必要があります。

Node.js のインストール

Node.js から Node.js(v16.14以降)をインストールして下さい。

c8ycli

続いて、以下コマンドにより c8ycli コマンドをグローバルインストールして下さい。

$ npm install -g @c8y/cli

npm は Node.js に含まれるパッケージ管理ソフトです。

npm install

解凍ファイルを格納したディレクトリで、以下コマンドを実行します。

$ cd chart-cockpit
$ npm install

npm install では、関連パッケージをインターネットから自動的にダウンロードします。

数分～数十分程度時間がかかる場合があります。

  :
(省略)
  :
  :
npm WARN deprecated xterm@3.14.5: This package is now deprecated. Move to @xterm/xterm instead.
npm WARN deprecated angular-i18n@1.6.9: For the actively supported Angular, see https://www.npmjs.com/package/@angular/core. AngularJS support has officially ended. For extended AngularJS support options, see https://goo.gle/angularjs-path-forward.

added 1863 packages, and audited 1864 packages in 1m

213 packages are looking for funding
  run `npm fund` for details

40 vulnerabilities (1 low, 6 moderate, 31 high, 2 critical)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

上記のようなメッセージが出れば完了です。

package.json の編集

package.json 内 scripts の start の -u以降を削除 することで、npm run start コマンドで、localhostでの動作確認ができます。また、localhostへのリクエストを -u オプションによって指定した URL へプロキシするように指定できます。同じように scripts の build や deploy に c8ycli コマンドをあらかじめ設定することで、c8ycli コマンドを意識せず、npm run ...コマンドにより実行することができます。

{
  "name": "cockpit-chart",
  "version": "1018.0.259",
  "description": "",
  "scripts": {
    "start": "c8ycli server",
    "build": "c8ycli build",
    "deploy": "c8ycli deploy",
    "locale-extract": "c8ycli locale-extract",
    "postinstall": "ngcc",
    "test": "jest"
  },
  "keywords": [],
  :
}

npm run start を実行した後、Webブラウザに以下のURL ( http://localhost:9000/apps/cockpit-chart/ ) を入力し、アクセスします。アクセス後、テナントID・ユーザ名・パスワードの入力が求められるためこれらを入力し、リクエストをプロキシしているテナントへログインします。ログイン後、アプリケーションの動作確認ができるようになります。

npm run start

次のコマンドを入力します。

$ npm run start

http://localhost:9000/apps/cockpit-chart/ 98 % - after emitting - angular-compiler

上記 % 表示が 100 になるまでお待ちください。

完了すると、以下表示となります。数分以上かかる場合があります。

http://localhost:9000/apps/cockpit-chart/ done - finished in 123 s - 237.738 ms

ブラウザから閲覧

Chrome, Firefox, Edge などのブラウザのアドレスバーに、http://localhost:9000/apps/cockpit-chart/ を入力し、テナントID、ユーザー、パスワードを入力して下さい。

テナントID は、あらかじめテナントにログインし、右上のユーザーボタンで確認しておいて下さい。

詳細は、ユーザーオプションと設定 に記載があります。

ログイン後、コックピットアプリケーションの「ホーム」で右上の「ウィジェットを追加」をクリックして下さい。以下のように、「ChartTemplate Widget」が選択できるようになっていれば、build は成功です。

2. データの前準備

作業の流れ

この章の操作をgifアニメーションにしています。クリックすると拡大して表示されます。

ここでは、グラフへ出力させるためのデータを準備します。今回は説明のために、Things Cloudの機能であるシミュレータを利用します。
また、お手持ちのIoTセンサーやデータがあればそちらもご利用可能です。

シミュレータの準備

今回はシミュレータ機能でデフォルトで用意されている温度シミュレータを利用します。シミュレータを追加する手順は以下となります。

1. Things Cloudのデバイス管理画面を開き、シミュレータ -> シミュレータを追加 をクリック
2. プリセット 温度計測 を選択し、作成 をクリック
3. 作成した温度シミュレータを 実行中 へ変更 (データが生成されるまで少し時間がかかります)

以上でシミュレータの準備は完了となります。シミュレータについて、詳しくはこちらをご覧ください。

ObservableがThings Cloud APIからデータを取得できるようにするために、管理アプリ -> 設定 -> アクセス制御に「*」を設定してください。 (ご利用状況に応じて設定内容はカスタマイズしてください)
詳細は ユーザーガイド -> 管理 -> 設定の変更 -> アプリケーション設定の変更のアクセス制御の記載をご覧ください。

3. Observable側の準備

作業の流れ

この章の操作をgifアニメーションにしています。クリックすると拡大して表示されます。

ここでは、カスタムウィジェットでグラフを作成する前に、Observable Notebook上でグラフを作成する手順をご紹介します。 まずはObservablehqへログインし、Things Cloud Chart Template Widgetへアクセスします。

備考: こちらのNotebookをカスタマイズされたい場合は、ご自身のアカウントでこのNotebookをforkします。forkの方法は以下となります。

1. Things Cloud Chart Template Widgetを開く
2. 右上の3点ボタンから Fork をクリック

Observable Notebookについて

Things Cloud Chart Template Widget の解説をします。

まず、以下ではChartTemplateServiceクラスをimportしています。
別の Observable Notebook からimportしており、詳細は割愛させていただきますが、Things Cloudから各種データを取得するNotebookとなっております。

データの取得

以下では、importした ChartTemplateService を用いて、Things Cloudからデータを取得しています。
データを取得する際に必要なデータは、デバイス/グループの ManagedObject ID及び取得するデータのフィルター条件となるので、それらを引数として、データを取得するメソッドを呼び出しております。
今回は温度シミュレータのMeasurementデータを取得するので、Measurementフィルターを設定し、chartTemplateService の getMeasurementsArray メソッドを呼び出し変数へ格納します。

ManagedObject IDの取得方法

対象のManagedObject ID取得方法は以下となります。

グループの場合

1. コックピット画面へログインし、対象のグループをクリックします。
2. urlの {{tenantUrl}/apps/cockpit/index.html#/group/{{groupid}} の {{groupid}} 部分がManagedObject IDとなります。

デバイスの場合

1. コックピット画面へログインし、対象のデバイスをクリックします。
2. urlの {{tenantUrl}/apps/cockpit/index.html#/device/{{deviceid}} の {{deviceid}} 部分がManagedObject IDとなります。

Managed Object ID及びフィルター条件は適宜変更下さい。

注意 Measurement, Alarm, Event データの time プロパティは Date 型で格納され、Observable では UTC 時刻として取り扱われます。必要に応じて時刻をずらす変換を行ってください。

グラフの表示

以下では、取得したデータからグラフを表示しています。
温度シミュレータのデータ(Measurement)を取得し、温度範囲ごとのカウント数をヒストグラムとして表示させています。
Observableで独自に実装されているPlotというメソッドを使用し、グラフを作成できます。
Observable Plotに関し、詳細は こちら をご覧ください。

テナント情報

Observable上でのThings Cloudからのデータ取得は、データ取得のためのテナント情報が必要となります。
テナント情報入力欄で以下を入力ししばらく待機すると、グラフが表示されます。

• 対象テナントのURL
• 対象テナントログイン時のユーザ名
• 対象テナントログイン時のパスワード

4. カスタムウィジェットの準備

作業の流れ

この章の操作をgifアニメーションにしています。クリックすると拡大して表示されます。

グラフの表示

Observableのノートブックで表示したいグラフが描けたら、セルのJavaScriptコードをコピーして、カスタムウィジェットのコンポーネント cockpit-chart/chart-template.component.ts の createPlot 関数 に貼り付けます。

コピー&ペーストする時は、以下にご注意ください。

• カスタムウィジェットでの表示に必要なため、以下は消さない
  • const plot =
  • return plot;
• データの変数に this を追加する (例: data.measurements → this.measurements）

:
@Component({
  selector: "chart-template",
  templateUrl: "./chart-template.component.html",
  styleUrls: ["./chart-template.component.css"],
})
export class ChartTemplate implements OnInit {
  :
  /**
   * Observable Plot ライブラリを使いグラフを描画する
   * 
   * Observable 上でデータ可視化を試行錯誤し、その結果を以下に貼り付ける。貼り付け時の注意点は以下の通り
   * - データの変数(measurements, events, alarms, devices)に this を追加する
   * - 以下はカスタムウィジェットでの表示に必要なため、残しておく
   *    - const plot = 
   *    - return plot;
   * 
   * @returns グラフ描画用のsvg要素
   * 
   */
  createPlot(): any {
    // 以下に Observable で作成したグラフ描画部分を追記してください
    const plot = Plot.plot({
      marks: [
        Plot.rectY(this.measurements, Plot.binX({y: "count"}, {x: "c8y_Temperature_T_value", fill: "source_id"}))
      ]
    });

    return plot;
  }
}

データの取得

Things Cloud のデータは、chart-template.service.ts の ChartTemplateService クラスで、@c8y/client を使い、取得しています。このクラスでは、グラフに表示したいデータをフィルタリング情報をもとに取得し、またグラフに読み込ませやすいデータにクレンジングしています。

カスタムウィジェットのコンポーネント cockpit-chart/chart-template.component.tsで ChartTemplateService クラスを利用できるように設定し、get{Measurements or Alarms or Events}Array メソッドからグラフに表示するデータを取得しています。メジャーメント、アラーム、イベントのデータを取得できますので、ご活用ください。

:
@Component({
  selector: "chart-template",
  templateUrl: "./chart-template.component.html",
  styleUrls: ["./chart-template.component.css"],
})
export class ChartTemplate implements OnInit {
  :
  ngOnInit(): void {
    (async () => {
      // Measurements データ取得
      const measurementsFilter = ({
        fragmentType: 'c8y_Temperature',
        dateFrom: new Date("2022-01-01"),
        dateTo: new Date("2030-01-01"),
        pageSize: ChartTemplate.PAGE_SIZE,
      });
      this.measurements = await this.chartTemplateService.getMeasurementsArray(this.config.device.id, measurementsFilter);

      // Alarms データ取得
      const alarmsFilter = ({
        type: '',
        dateFrom: new Date("2022-01-01"),
        dateTo: new Date("2030-01-01"),
        pageSize: ChartTemplate.PAGE_SIZE,
      });
      this.alarms = await this.chartTemplateService.getAlarmsArray(this.config.device.id, alarmsFilter);
    
      // Events データ取得
      const eventsFilter = ({
        fragmentType: '',
        dateFrom: new Date("2022-01-01"),
        dateTo: new Date("2030-01-01"),
        pageSize: ChartTemplate.PAGE_SIZE,
      });
      this.events = await this.chartTemplateService.getEventsArray(this.config.device.id, eventsFilter);
      
      // グラフを表示
      this.chart.nativeElement.appendChild(this.createPlot()); 

    })();
  }
  :
}

対象のアセット もしくは デバイス

this.config.device.id には、カスタムウィジェットの構成画面で選択したデバイス、またはアセット(グループ)のIDが 設定されますので、変更する必要はありません。

filterに指定できるパラメータ

5. ローカル環境での動作確認

作業の流れ

この章の操作をgifアニメーションにしています。クリックすると拡大して表示されます。

package.json の編集がされていることを確認下さい。

ダッシュボードで、ウィジェットの追加から「ChartTemplate Widget」を選択した後、保存します。以下のようなウィジェットが作成されれば成功です。すでにウィジェットを追加済みの場合は、ブラウザをリロードします。

この時点ではプロキシしているテナントで修正中のカスタムウィジェットを確認することはできません。デプロイ後に、プロキシしているテナントでもカスタムウィジェットを確認することができます。

6. Things Cloud へのデプロイ手順

作業の流れ

この章の操作をgifアニメーションにしています。クリックすると拡大して表示されます。

ローカル環境での動作が正常であることを確認したら、Things Cloud へデプロイします。アプリケーションのルートディレクトリ (cockpit-chart/ 直下) に移動し、以下のコマンドを実行します。

$ npm run build
$ npm run deploy
prompt: Instance URL:  (http://demos.cumulocity.com) テナントのURLを入力 (例: https://<テナント名>.je1.thingscloud.ntt.com)
prompt: Username:  (admin) ユーザ名を入力
prompt: Password: パスワードを入力

npm run build コマンドを実行し、アプリケーションをビルドします。ビルド後、アプリケーションのディレクトリに dist/ ディレクトリが作成されます。このディレクトリが作成されたことを確認したら、npm run deploy コマンドで Things Cloud へアプリケーションをデプロイします。デプロイコマンド実行時に、アプリケーションのデプロイ先 URL とユーザ情報の入力が必要になります。

参考

以下に本レポートを実施する上で参考となる Web サイトへのURLを記載します。

• Observable Tutorials
• Observable Plot
• Web SDK for Angular を利用したカスタムウィジェットの作り方1
• Web SDK for Angular を利用したカスタムウィジェットの作り方2