14. カスタムコレクタ#

14.1 カスタムコレクタとは#

SpeeDBee Hiveでは、データの収集を行うモジュールのことを"コレクタ"と呼びます。
標準ではPLC等のデータを収集する"コレクタ"が用意されていますが、ユーザーが独自にコレクタを開発、運用することも可能です。コレクタの開発にはC言語、もしくは、Pythonを使用できます。
本ドキュメントではC言語によるカスタムコレクタの開発方法を説明します。

14.2 カスタムコレクタのサンプル#

カスタムコレクタの作り方の説明のため、単純なデータ収集を行うシンプルなカスタムコレクタをサンプルとして提供しています。
SpeeDBee Hiveをインストール済みの場合、カスタムコレクタサンプルも下記の場所にインストールされています。

Linux

$ ls /usr/local/share/speedbeehive/example
Makefile fixarray.c randomsin.c

> dir “C:/Program Files/SALTYSTER/SpeeDBeeHive/share/example”
2021/07/29  17:00    <DIR>          .
2021/07/29  17:00    <DIR>          ..
2021/07/29  16:49             5,324 fixarray.c
2021/07/29  16:49               439 Makefile
2021/07/29  16:49             3,694 randomsin.c
               3 個のファイル               9,457 バイト

14.2.1 カスタムコレクタのサンプルの内容#

カスタムコレクタのサンプルとして２つのコレクタを提供しています。

• randomsin
  SIN波の振幅値(-1～+1)と、ランダムな0~100までの整数値の２つのデータを登録するコレクタのサンプルです。
  データはいずれも単純なスカラ値で、前者はDOUBLE型、後者はINT32型としています。
• fixarray
  円運動する物体のX-Y-Z座標値をデータとして登録するコレクタのサンプルです。
  データは３要素のDOUBLE型配列としています。

14.2.2 準備#

カスタムコレクタの開発のため、下記のソフトウェアを事前にインストールしてください。

14.2.2.1 Linux#

• gcc
• make

14.2.2.2 Windows#

• Visual Studio 2019

14.2.3 ビルド（シェアードライブラリの生成）#

14.2.3.1 Linux#

カスタムコレクタをホームディレクトリにコピーした上で、makeを実行してください。

$ cp -r /usr/local/share/speedbeehive/example ~/custom-example
$ cd ~/custom-example
$ make
cc -g -O2 -Wall -I/usr/local/include -shared -fPIC -L/usr/local/lib -o cltrfixarray.so fixarray.c -pthread -lm
cc -g -O2 -Wall -I/usr/local/include -shared -fPIC -L/usr/local/lib -o cltrrandomsin.so randomsin.c -pthread -lm

$ cd ~/custom-example
$ sudo make install
install -d /var/speedbeehive/libs
install -m 644 cltrfixarray.so cltrrandomsin.so /var/speedbeehive/libs

14.2.3.2 Windows#

x64 Native Tools Command Prompt for VS 2019を実行してください。

x64 Native Tools Command Prompt for VS 2019上でカスタムコレクタをデスクトップにコピーし、nmakeを実行してください。

> xcopy /I "C:\Program Files\SALTYSTER\SpeeDBeeHive\share\example" C:\Users\user_name\Desktop\test\example 
> cd  C:\Users\$user_name\Desktop\test\example
> nmake
Microsoft(R) Program Maintenance Utility Version 14.28.29915.0
Copyright (C) Microsoft Corporation.  All rights reserved.

> xcopy cltrfixarray.dll C:\ProgramData\SALTYSTER\SpeeDBeeHive\libs
> xcopy cltrrandomsin.dll C:\ProgramData\SALTYSTER\SpeeDBeeHive\libs

14.2.3.3 配置場所変更方法#

Web UIのカスタムモジュールパスを変更することで配置場所を変更する事が可能です。

14.2.4 利用設定#

インストールしたカスタムコレクタを利用する場合、設定画面から設定します。

14.2.4.1 カスタムコレクタ設定#

1. サブメニュー「カスタム」の をクリックすると新規登録画面が表示されます。

   

2. 各項目を入力し、「保存」をクリックし設定を保存します。

   

設定が必要な項目は以下の通りです。

14.2.4.2 カスタムコレクタ 参照・更新・削除#

1. サブメニューから参照するカスタムコレクタをクリックします。
2. 変更項目を入力後、「保存」をクリックし、設定を更新します。
3. データを削除したい場合は、「削除」をクリックし、設定を削除します。

14.2.4.3 データ初期化#

1. 「初期化」をクリックします。
2. データ一覧の表に「sin wave」「random integer」の二つが追加されます。

14.2.4.4 データ編集#

1. 「編集」をクリックし、データ編集画面に移動します。

   

2. 下部のデータ一覧から設定したい項目を選択します。

   

3. 各項目を変更し、「更新」をクリックし設定を保存します。
   変更が可能な項目は以下の通りです。
   

14.3 カスタムコレクタのソースコードの説明#

この節ではカスタムコレクタサンプルのrandomsinのソースコードrandomsin.c をもとにカスタムコレクタの作りについて説明します。randomsin.cは以下の場所に配置されています。

• Linux: /usr/local/share/speedbeehive/example/randomsin.c
• Windows: C:/Program Files/SALTYSTER/SpeeDBeeHive/share/example/randomsin.c

14.3.1 インクルードヘッダ#

カスタムコレクタを実装する際は下記のヘッダファイルをインクルードしてください。
このヘッダは以下の場所に配置されています。

• Linux: /usr/local/include/
• Windows: C:/Program Files/SALTYSTER/SpeeDBeeHive/include/
  以降に説明する種々の構造体や関数のプロトタイプが宣言されていますので、詳細はこちらを参照してください。
  

#include "sdcltr_collector.h"

14.3.2 コレクタ情報定義#

下記はカスタムコレクタの固有情報をSpeeDBee Hiveに伝えるための定義データです。
COLLECTOR_INFO構造体の実態定義、および、その定義をEXPORT_COLLECTOR_INFO()でSpeeDBee Hiveに登録します。

/* コレクタ定義データ：名前、説明、パラメータ、出力データを記述する.  */
const static COLLECTOR_INFO info = {
  .name          = "random&sin",           // コレクタの名称
  .description   = "ランダム値とサイン波", // コレクタの説明
  .multiple      = true,                   // 複数インスタンスを許すかどうか
  .functions     = {
    .constructor = constructor,
    .destructor  = NULL,
    .main        = mainloop,
  },
};

/* コレクタ定義データを外部シンボルに出力するマクロ（必須）.  */
EXPORT_COLLECTOR_INFO(info);

定義が必要な情報は下記のとおりです。

14.3.3 コンストラクタ#

このコレクタの開始時に最初に実行される関数です。

引数として"COLLECTOR *collector"と"params"を受け取っています。
collectorはこのSpeeDBee Hiveが用意している様々な関数をコールするために必要になります。
paramsはWeb UIでパラメータとして定義した文字列です。
パラメータを受け取って動作を変えた場合は参照してください。

static const COLLECTOR_OUTPUT_TYPE *constructor(COLLECTOR *collector, const char *params) {

  /* コレクタが出力するデータの定義. データ０はSIN波の浮動小数点数、
    データ１はランダムな整数. 最後はNONEにする.  */
  const static COLLECTOR_OUTPUT_TYPE output_types[] = {
    // type             array type          description         sampling rate
    { SDCLTR_DOUBLE,    SDCLTR_SCALAR,      "sin wave",         200           },
    { SDCLTR_INT32,     SDCLTR_SCALAR,      "random integer",   0             },
    { SDCLTR_NOTYPE },  // 終端は必ずNOTYPEとする
  };
  return output_types;
}

14.3.4 メインループ#

カスタムコレクタのデータ収集のメイン処理を記述する関数です。

このサンプルでは、単純にsdcltr_interval_call()関数を呼んでいます。
これにより、引数に与えられたproc関数が定期的にコールされ、コレクタの終了通知が来ると自動的に終了します。

static int mainloop(COLLECTOR *collector) {
  double phase = 0.0;

  srand(time(NULL));
  int code = sdcltr_interval_call(collector, proc, 1000*1000, &phase); // １秒周期でprocをコール

  sdcltr_exit(collector, code);
}

下記のprocは、sdcltr_interval_call()の内部から、定期的にコールされる関数です。
ここで１周期分のデータを収集し、SpeeDBee Hiveに登録しています。
このサンプルでは、特に外部からデータを取得するわけではなく、内部的に計算した結果をデータとして登録しています。

static int proc(COLLECTOR *collector, void *data) {

  // １つ目のデータ（１回で200個登録）
  double v0[200];
  double *phase = (double*)data;
  for (int i=0; i<200; i++) {
    v0[i] = cos(*phase);
    *phase += M_PI/7;
  }
  sdcltr_insert_data_array(collector, 0, &v0, 200);
  HIVE_DEBUG("insert 200 data for sin wave: [%lf, .. %lf].\n", v0[0], v0[199]);

  // ２つ目のデータ
  int v1 = rand() % 100;
  sdcltr_insert_data(collector, 1, &v1);
  HIVE_DEBUG("insert 1 data for random integer: [%d].\n", v1);

  return SDCLTR_EXIT_SUCCESS;
}

14.4 カスタムコレクタ内で利用可能な型・構造体・関数#

14.4.1 カスタムコレクタ用関数#

14.4.1.1 sdcltr_insert_data() … データ登録#

コレクタが収集したデータをSpeeDBee Hiveに登録する関数

書式

bool sdcltr_insert_data(COLLECTOR *collector, int dataNo, void *data);

引数

戻り値

• false: 登録失敗
• true: 登録成功

説明

コレクタが収集したデータをSpeeDBee Hiveに登録するための関数です。BINARY型以外のデータはこの関数で登録できます。
登録するデータのタイムスタンプはコンストラクタで設定したデータの頻度によって異なります。

• 不定期なデータの場合
  この関数を呼出した時点の現在時刻がタイムスタンプとなります
  
• 固定周期データの場合
  初回のデータ登録ではこの関数を呼出した時点の現在時刻、
  二回目以降のデータ登録の場合、前回のタイムスタンプ+１周期分の時間となります。
  データ型が配列の場合、その配列要素の先頭アドレスを引数'data'に渡してください。
  
  
  

14.4.1.2 sdcltr_insert_data_ts() … タイムスタンプ指定のデータ登録#

コレクタが収集したデータをタイムスタンプとともにSpeeDBee Hiveに登録する関数

書式

bool sdcltr_insert_data_ts(COLLECTOR *collector, int dataNo, 
void *data, sdcltr_time_t ts);

戻り値

• false: 登録失敗
• true: 登録成功

説明

コレクタが収集したデータをSpeeDBee Hiveに登録するための関数です。BINARY型以外のデータはこの関数で登録できます。
登録するデータのタイムスタンプは引数tsで指定した時刻となります。
データ型が配列の場合、その配列要素の先頭アドレスを引数'data'に渡してください。

14.4.1.3 sdcltr_insert_data_array() … 配列データの登録#

コレクタが収集した複数個のデータを纏めて登録する関数

書式

int sdcltr_insert_data_array(COLLECTOR *collector, int dataNo, void *data, int length);

引数

戻り値

説明

コレクタが収集したデータをSpeeDBee Hiveに登録するための関数です。高サンプルレートの際の複数のデータをまとめて登録できます。
登録するデータのタイムスタンプは配列の先頭が登録された際の現在時刻になります。

14.4.1.4 sdcltr_reset_timestamp() … タイムスタンプのリセット#

周期データにおいてタイムスタンプをリセットする関数

書式

void sdcltr_reset_timestamp(COLLECTOR *collector, int dataNo, sdcltr_time_t ts);

引数

戻り値

• なし

説明

周期データにおいて、エラーなど何らかの要因によりデータを定期的に登録できなかった場合、SpeeDBee Hive側で持つ時刻の連続情報にずれが生じます。
コレクタ内で定期的な登録ができないことを検出した場合に、この関数をコールして、次回以降のデータ登録から再度タイムスタンプを連続保持することをSpeeDBee Hiveに通知してください。 次回以降のデータ登録は、引数’ts’に指定した時刻から開始となります。 ’ts’が0の場合、本関数コール時点の時刻を開始時刻とします。

14.4.1.5 sdcltr_interval_call() … 定期処理関数#

一定の周期で指定した関数を継続的に実行する関数

書式

int sdcltr_interval_call(COLLECTOR *collector, sdcltr_interval_proc_t interval_proc, int interval_usec, void *data);

引数

戻り値

• SDCLTR_EXIT_SUCCESS:
  interval_procが一度もエラーとならずに、SpeeDBee Hiveがコレクタを終了させた場合にこのコードが返却されます。
  
• その他:
  interval_proc内でエラーが発生した場合、internval_procの戻り値がそのままこの関数の戻り値となります。
  

説明

一定の周期で何らかの処理を実行する場合に、この関数を使用してください。

多くのコレクタは、定期的なデータ収集を行うため、データ収集の処理を定義した関数のポインタを'interval_proc'引数に渡すことで基本的な動きを実現できます。
（「カスタムコレクタのソースコードの説明」を参照）

14.4.1.6 sdcltr_exit() … コレクタの強制終了#

コレクタのメイン処理を強制終了する関数

書式

void sdcltr_exit(COLLECTOR *collector, int code);

引数

戻り値

• この関数は呼び出し元に戻りません。

説明

コレクタのメイン処理を強制終了する関数です。

14.4.1.7 sdcltr_running() … コレクタの実行可否状態取得#

コレクタの実行可否状態取得関数

書式

bool sdcltr_running(COLLECTOR *collector);

引数

戻り値

• true: このコレクタのメイン処理を継続可
• false: このコレクタのメイン処理を継続不可

説明

コレクタの実行はSpeeDBee Hiveにより制御されているため、何らかの理由によりコレクタに停止要求が出ることがあります。
コレクタは定期的にこの関数をコールして状態をチェックし、この関数がfalseを返した場合には速やかにメイン処理を終了しなければなりません。

14.4.1.8 HIVE_XXXX() … コレクタ用のログ出力#

コレクタ用のログ出力マクロ関数

書式

void HIVE_TRACE(const char *format, ...);   
void HIVE_DEBUG(const char *format, ...);   
void HIVE_INFO(const char *format, ...);    
void HIVE_WARNING(const char *format, ...); 
void HIVE_ERROR(const char *format, ...);   

引数

戻り値

• なし

説明

SpeeDBee Hive本体のログ出力に文字列を出力するためのマクロ関数です。
引数'format'、および、それに続く可変長引数は、標準Cライブラリのprintf()と同様に使用できます。
マクロは５種類用意されており、それぞれログレベルに対応しています。