デバイスモジュール作成ガイドライン¶
目次:
概要¶
デバイス制御モジュールを作成する際のガイドラインについて記述する。
新しい機器を導入する場合には本ガイドラインの内容に従ってデバイス制御モジュールを作成することが求められる。
デバイスモジュールのフォルダ¶
デバイスモジュールに関するコード類は iroha-device-server/devices
以下に作成されたモジュールフォルダに格納する。
フォルダ名¶
動作上、フォルダ名は任意でも問題ないが、以下のような規則で命名している。
<メーカー名><機器種類>_<型番>
例えば、Lake Shore製の温度コントローラーLS350のフォルダ名は LSTempCont_350 となる。
また、BL独自のデバイスを作成した場合にはフォルダ名の末尾に装置コード名を付与する。 例えば、BL01用の1軸ゴニオのフォルダ名は TJCPmc04_1AxisGonio_SIK となる。
フォルダ構成¶
デバイスモジュールのフォルダは以下の構成とする。
項番 |
フォルダ/ファイル |
説明 |
---|---|---|
1 |
dh~.py |
デバイスハンドラ |
2 |
dm~.py |
デバイスモデル |
3 |
devinfo.tpl |
デバイス設定テンプレート |
4 |
devstatus.tpl |
デバイスステータステンプレート |
5 |
params.tpl |
パラメータテンプレート |
6 |
views/ |
Web UIの表示をオーバーライドするHTMLファイルを格納するフォルダ |
7 |
devhelp.md |
デバイス監視画面のヘルプ |
8 |
devadminhelp.tpl |
デバイス管理画面のヘルプ |
その他、必要に応じてファイルを追加する。
デバイスモデルの作成¶
デバイスモデルはファイル名が dm で始まるPythonスクリプトに定義される。
ファイル名は dm+デバイスモジュールフォルダ名.py
とする(すべて小文字)。
デバイスモデルではデバイス制御サーバーで定義されている関数をオーバーライドすることで機器制御を実現する。
クラス¶
デバイスモデルでは、 irhlibdev.irhdevicemodel.IrhDeviceModel を継承したクラスを作成する。 クラス名は以下の様に命名する。
Dm<デバイスモジュールフォルダ名>
例えば、Lake Shore製の温度コントローラーLS350のフォルダ名は LSTempCont_350 となるため、 デバイスモデルのクラス名は DmLSTempCont_350 となる。
制御関数¶
irhlibdev.irhdevicemodel.IrhDeviceModel で定義されているいくつかの関数をオーバーライドし、機器制御を実現する。
OnCycleConnecting¶
引数 なし
返り値 成功/失敗(bool)
この関数はデバイスモジュール起動時に呼び出される。 つまり、デバイス制御サーバー起動時やデバイスインスタンス作成時、リセット時に呼び出される。 この関数のデフォルトの動作はTrueを返すだけなので、必ずオーバーライドで動作を定義する必要がある。
この関数では、
devinfo.tplの値の読み込み
デバイスとの接続
OnCycleUploadParamsの呼び出し
OnCycleUploadDevStatusの呼び出し
等を行う。 この関数の実行中は、デバイスの状態はConnectingとなる。
処理に成功した場合にはTrueを、失敗した場合にはFalseを返す必要がある。 接続に成功した場合、デバイスの状態はReadyとなる。 接続に失敗した場合は再接続を6度繰り返し、最後まで失敗した場合にはデバイスの状態はDisconnectとなる。
OnCycleUploadParams¶
引数 なし
返り値 成功/失敗(bool)
この関数はデバイス接続開始時とStopParamsでキャンセルされる場合に呼び出される。 この関数のデフォルトの動作はTrueを返すだけなので、必ずオーバーライドで動作を定義する必要がある。
この関数では、 params.tpl
で定義されたデバイスパラメータの初期値の設定を行う。
処理に成功した場合にはTrueを、失敗した場合にはFalseを返す必要がある。
OnCycleUploadDevStatus¶
引数 なし
返り値 成功/失敗(bool)
この関数は定周期で呼び出される。 この関数のデフォルトの動作はTrueを返すだけなので、必ずオーバーライドで動作を定義する必要がある。
この関数では、 devstatus.tpl
で定義されたデバイスステータスについて、
状態を収集し、デバイスステータスに値を格納する。
処理に成功した場合にはTrueを、失敗した場合にはFalseを返す必要がある。 処理に失敗した場合、デバイスの状態はReadyからConnectingへと遷移し、再度OnCycleConnectingが呼び出される。
OnCycleDownloadParams¶
引数 なし
返り値 成功/失敗(bool)
この関数はパラメータ送信時に呼び出される。 この関数はデフォルトでは以下の処理を行う。
- 送信されたすべてのパラメータについて、以下の処理を行う
- 送信されたパラメータの値と現在のパラメータの値が異なる場合、OnCycleDownloadParamsElmを呼び出す
ただし、
params.tpl
において、パラメータに forceUpdate=true 属性が追加されていた場合、パラメータ値が変化していない場合でもOnCycleDownloadParamsElmを呼び出す
OnCycleDownloadParamsElmがFalseを返してきた場合、即座にFalseを返す。
すべてのパラメータについて、OnCycleDownloadParamsElmがTrueを返してきた場合、Trueを返す。
したがって、実際にデバイスへパラメータを送信するのはOnCycleDownloadParamsElmの役割である。 このデフォルトの動作ではうまく制御できない場合に、この関数自体をオーバーライドする。
この関数がTrueを返した場合、デバイスの状態はInProgressへと遷移する。 Falseを返した場合、デバイスの状態はReadyからConnectingへと遷移し、再度OnCycleConnectingが呼び出される。
OnCycleDownloadParamsElm¶
引数 パラメータのXMLオブジェクト
返り値 成功/失敗(bool)
この関数はOnCycleDownloadParamsから呼び出される。 この関数のデフォルトの動作はTrueを返すだけなので、使用する場合にはオーバーライドで動作を定義する必要がある。
この関数では、OnCycleDownloadParamsから渡されたパラメータのXMLオブジェクトから値を読み取ってデバイスに送信する。
処理に成功した場合にはTrueを、失敗した場合にはFalseを返す必要がある。
OnCycleInProgress¶
引数 なし
返り値 なし
この関数はOnCycleDownloadParamsが成功した後、定周期で呼び出される。
この関数ではデバイスの状態を確認し、デバイスが定常状態になったと判断した場合にデバイスの状態をReadyに遷移させる。 この関数でデバイスの状態をReadyにしない限りは、定周期でこの関数が呼び出され続ける。 デフォルトの動作は、単にデバイスの状態をReadyにするだけなので、デバイスの定常状態を正確に判断したい場合には、必ずオーバーライドする必要がある。
この関数では値を返す必要はない(デバイス状態をReadyに遷移させるかさせないかで次の処理が変わる)。
OnDelete¶
引数 なし
返り値 なし
(v2.7より導入)
この関数はデバイスインスタンスが削除される際に呼び出される。 デフォルトでは何もしない。
デバイスインスタンス削除時にsocketを閉じる処理などを行う場合には、 この関数をオーバーライドして処理を実装する。
GetHomeInformation¶
引数 なし
返り値 デバイスの情報(str)
この関数ではWebUIのホームページに表示するメッセージを取得する。 デフォルトでは「No Information」と表示されるだけである。
ホームページにそのデバイスの情報を表示したい場合には、この関数をオーバーライドし、表示したい文字列を返す必要がある。
ライブラリ関数¶
irhlibdev.irhdevicemodel.IrhDeviceModel を継承したクラスでは以下に示す関数を使用することができる。
GetDevInfo¶
引数 なし
返り値 デバイス情報のXMLオブジェクト
devinfo.tplで定義されたデバイス情報をXMLオブジェクトとして取得する。 デバイスの接続に必要な情報などが含まれているため、主に OnCycleConnecting において使用する。
GetDevStatus¶
引数 なし
返り値 デバイス状態のXMLオブジェクト
devstatus.tplで定義されたデバイス状態をXMLオブジェクトとして取得する。 主に OnCycleUploadDevStatus において、デバイスから取得した状態を書き込むために使用される。
GetParams¶
引数 なし
返り値 デバイスパラメータのXMLオブジェクト
params.tplで定義されたデバイスパラメータをXMLオブジェクトとして取得する。 OnCycleUploadParams において、パラメータの初期値を書き込むために使用される。 また、 OnCycleDownloadParams においては、デバイスへ送信したパラメータの値を書き込むために使用される。
GetRequestParams¶
引数 なし
返り値 Web UIから送信されたデバイスパラメータのXMLオブジェクト
Web UIから送信されたデバイスパラメータをXMLオブジェクトとして取得する。 このXMLには、Web UIにおいて値を変更したかどうかに関わらず、設定できるすべてのパラメータの値が含まれている。 したがって、値が変更されたパラメータのみを処理したい場合には、 GetParams を利用して値の比較を行う必要がある。
SetStatus¶
引数 デバイス状態(str)
返り値 なし
デバイスの状態を引数で指定した状態に遷移させる。 主に OnCycleInProgress でInProgress状態からReady状態に遷移させるために使用される。
GetLogOper¶
引数 なし
返り値 ロガーオブジェクト
デバイス操作ログのロガーオブジェクトを取得する。 このロガーオブジェクトはログ出力用のメソッドを有しており、それぞれのログレベルに応じたログを出力する。
info・・・INFOレベルのログを出力するメソッド
warning・・・WARNINGレベルのログを出力するメソッド
error・・・ERRORレベルのログを出力するメソッド
debug・・・DEBUGレベルのログを出力するメソッド
SetInformationMessage¶
引数 メッセージ(str)
返り値 なし
Web UI画面にInformationメッセージを表示するために使用される。 この関数で設定したメッセージを実際にWeb UI上に表示させるためには、 HTMLファイルに埋め込んだPythonスクリプトにおいて GetInformationMessage を用いて設定したメッセージを取得する必要がある。
SetErrorMessage¶
引数 メッセージ(str)
返り値 なし
Web UI画面にErrorメッセージを表示するために使用される。 この関数で設定したメッセージを実際にWeb UI上に表示させるためには、 HTMLファイルに埋め込んだPythonスクリプトにおいて GetErrorMessage を用いて設定したメッセージを取得する必要がある。
デバイスハンドラーの作成¶
デバイスハンドラーはファイル名が dh で始まるPythonスクリプトに定義される。
ファイル名は dh+デバイスモジュールフォルダ名.py
とする(すべて小文字)。
デバイスハンドラーではデバイス制御サーバーで定義されている関数をオーバーライドすることでPOST/GET処理のカスタマイズを行う。
クラス¶
デバイスハンドラーでは、 irhlibdev.irhdevicemh.IrhDeviceMh を継承したクラスを作成する。 クラス名は以下の様に命名する。
Dh<デバイスモジュールフォルダ名>
例えば、Lake Shore製の温度コントローラーLS350のフォルダ名は LSTempCont_350 となるため、 デバイスハンドラーのクラス名は DhLSTempCont_350 となる。
制御関数¶
irhlibdev.irhdevicemh.IrhDeviceMh で定義されているいくつかの関数をオーバーライドする。 以下に示した関数以外にもオーバーライド可能な関数があるため、既存のデバイスモジュール等を参考に実装する。
OnGetDevHome¶
この関数をオーバーライドすることで、カスタマイズしたデバイスホームページを表示することができる。
OnGetDevInfo¶
この関数をオーバーライドすることで、カスタマイズしたデバイス情報ページを表示することができる。
OnGetDevStatusUi¶
この関数をオーバーライドすることで、カスタマイズしたデバイス状態ページを表示することができる。
OnGetDevParamsUi¶
この関数をオーバーライドすることで、カスタマイズしたパラメータ表示ページを表示することができる。
OnGetDevMeasLog¶
この関数をオーバーライドすることで、カスタマイズした測定ログページを表示することができる。
OnGetDevMeasGraph¶
この関数をオーバーライドすることで、カスタマイズした測定ロググラフページを表示することができる。
OnGetDevSurvLog¶
この関数をオーバーライドすることで、カスタマイズした監視ログページを表示することができる。
OnGetDevOperLog¶
この関数をオーバーライドすることで、カスタマイズした操作ログページを表示することができる。
OnGetDevExt¶
未定義のURIに対するGETリクエストが送られてきた際の処理を実装する。
OnPostDevExt¶
未定義のURIに対するPOSTリクエストが送られてきた際の処理を実装する。
ライブラリ関数¶
irhlibdev.irhdevicemh.IrhDeviceMh を継承したクラスでは以下に示す関数を使用することができる。
DevSrvSubTemplate¶
引数 HTMLファイルのパス, サーバーモデル, デバイスモデル
返り値 展開されたHTML
この関数はサーバー監視画面の各サブコンテンツのHTMLを作成するために使用される。 デバイスハンドラーの制御関数において使用し、Web UIの画面をカスタマイズする。
DevAdmSubTemplate¶
引数 HTMLファイルのパス, サーバーモデル, デバイスモデル
返り値 展開されたHTML
この関数はサーバー管理画面の各サブコンテンツのHTMLを作成するために使用される。 デバイスハンドラーの制御関数において使用し、Web UIの画面をカスタマイズする。
Note
デバイスハンドラーによる画面のカスタマイズについての詳細は、既存のデバイスモジュールを参考にすること。
tplファイルの作成¶
各デバイスモジュールには devinfo.tpl
devstatus.tpl
params.tpl
の3種類のtplファイルがある。
これらのファイルはデバイスモジュールがインスタンス化された(デバイスをAddした)際に作成される設定ファイルのひな型となる。
devinfo.tpl¶
デバイス情報を記述するXMLファイルであり、デバイス名やホスト名、ポート番号など、接続に必要な値や接続後は変更しないを定義する。
ルート要素の要素名は DevInfo<デバイスモジュール名> となる。 例えば、Lake Shore製の温度コントローラーLS350のモジュール名は LSTempCont_350 であるから、 ルート要素名は DevInfoLSTempCont_350 となる。
ルート要素の下には<name>要素と<params>要素を定義する。
<name>要素にはインスタンス化時に入力したデバイス名が入る。
<params>要素にはデバイスから情報を収集する時間間隔などの情報を入れる。
intervalReady・・・未測定時のデバイスからの情報収集間隔
intervalInProgress・・・InProgress時のデバイスからの情報収集間隔
intervelMeasurement・・・測定時のデバイスからの情報収集間隔
また、ホスト名やポート番号など、その他の情報については任意の階層に定義してよい。
作成例:Sampleデバイス¶
<?xml version="1.0" encoding="UTF-8"?>
<DevInfoSample>
<name>newName</name>
<instType>999</instType>
<type>999</type>
<model>9</model>
<addr>localhost</addr>
<portNo>30101</portNo>
<path/>
<devTag/>
<params>
<intervalReady>10</intervalReady>
<intervalMeasurement>5</intervalMeasurement>
<intervalInProgress>1</intervalInProgress>
<param>
<connect>on</connect>
<connectWait>3</connectWait>
<logSurvDisable>no</logSurvDisable>
<logMeasHeader>off</logMeasHeader>
<logSurvHeader>off</logSurvHeader>
</param>
</params>
</DevInfoSample>
devstatus.tpl¶
デバイス状態を記述するXMLファイルであり、デバイスの状態を表すパラメータの定義を行う。
ルート要素の要素名は DevStatus となる。
ルート要素の下には<name>要素と<status>要素、<params>要素を定義する。
<name>要素にはインスタンス化時に入力したデバイス名が入る。
<status>要素には定期的に収集されるデバイスインスタンスの状態が入る。
<params>要素の下には各パラメータの要素を入れる。 ただし、既存のデバイスモジュールと揃えるため、<params>要素の下に<param>要素を作り、その下に各パラメータの要素を入れる。 各パラメータの要素にはいくつかの属性を定義することができる。
measLog・・・onにするとそのパラメータの値は測定ログに記録される(インスタンス作成後に設定可能)
logging・・・meassLog=onとする場合にはonにする
logName・・・測定ログのヘッダーに使用するパラメータ名
type・・・パラメータの型(int/float/string)
unit・・・パラメータの単位(測定ログのヘッダーに使用)
range・・・パラメータの範囲(上限:下限:幅)
作成例:Sampleデバイス¶
<?xml version="1.0" encoding="UTF-8" ?>
<devStatus>
<name/>
<status>Idle</status>
<params>
<param>
<log>Off</log>
<testSet logging="on" measLog="on" logName="Test Setting" type="int" unit="K" range="0:500:1" >0</testSet>
<testCur logging="on" measLog="on" logName="Test Current" type="int" unit="K" range="0:500:1" >0</testCur>
<sin logging="on" measLog="on" logName="Sin Curve" type="float" unit="" range="0.0::0.1">123.455</sin>
<sinsign logging="on" measLog="on" logName="Sin Sign" type="string" unit="" range="Negative:Zero:Positive">Zero</sinsign>
<cos logging="on" measLog="on" logName="Cos Curve" type="float" unit="" range="0.0::0.1">123.455</cos>
<random logging="on" measLog="on" logName="Random 2000-3000" type="float" unit="usec" range="0.0:3000.0:0.1">3000.9</random>
<percent logging="on" measLog="on" logName="PercentItem" type="float" unit="%" range="0.0:100.0:0.1">100</percent>
</param>
</params>
</devStatus>
params.tpl¶
デバイスパラメータを記述するXMLファイルであり、デバイスへ送信するパラメータの定義を行う。
ルート要素の要素名は params となる。
ルート要素の下には<param>要素を定義し、その下に各パラメータの要素を入れる。 各パラメータの要素にはいくつかの属性を定義することができる。
type・・・パラメータの型(int/float/string)
range・・・パラメータの範囲(上限:下限:幅)
unit・・・パラメータの単位
forceUpdate・・・trueの場合、パラメータ値に変化がない場合にもパラメータ表示画面のUpdateを更新する
default・・・値が設定されている場合、パラメータの送信後にパラメータの表示値をその値にする(v2.7より導入)
Note
ルート要素<params>の下に直接各パラメータの要素を入れることはできるが、 シーケンス管理サーバーのファサード自動作成機能を使用するためには ルート要素の下に<param>要素を定義してその下に各パラメータの要素を定義する必要がある。
Note
params.tplの<param>要素の要素名は任意の名前に変更してもよい。 例えば、LSTempCont_350では<tmpcnt>としている。
Note
typeで指定した型とrangeにおける値の型が不一致の場合、ファサードにおけるパラメータチェックで問題となる場合がある
(例えば、type=’float’に対して、range=’0:100:1’と指定した場合)。
バージョン2.8.3以降では、params.tplの内容をチェックするスクリプト iroha2/util/xml/dev_params_checker.py
を用意している。
作成例:Sampleデバイス¶
<param>要素の代わりに<sample>要素を使用している。
<?xml version="1.0" encoding="UTF-8" ?>
<params>
<sample>
<stritem type='string' range="on|off|none" >on</stritem>
<control type='int' range="0:1:1" >1</control>
<testSet type='int' range="0:500:1" >1</testSet>
</sample>
</params>
HTMLファイルの作成¶
IROHA2ではWebアプリケーションフレームワークとしてbottle.pyを使用しており、 テンプレートの機能を使うことで動的にHTMLファイルの内容を変更することができる。 具体的には、Pythonスクリプトを埋め込んだHTMLファイルをデバイスハンドラーで指定し、 そのPythonスクリプトを実行することでその結果に応じたHTMLが生成される。
HTMLファイルは各デバイスモジュールフォルダの views
フォルダに格納する。
ファイル名は任意で良いが、既存のデバイスと統一感を持たせるため、
dev-sc-<デバイスを表す言葉>-<ページを表す言葉>.html という法則で命名する。
ヘルプの作成¶
各デバイスモジュールのヘルプページはMarkdown形式で記述する。
devhelp.md¶
デバイス監視画面において Help ボタンを押下した際に表示されるヘルプページを記述する。
devadminhelp.md¶
デバイス管理画面において Help ボタンを押下した際に表示されるヘルプページを記述する。