Comment on page

Format Parser

TWELITE PAL の親機出力形式を解釈するコードです。

​
​TWELITE PAL 親機の書式フォーマット (ASCII形式のみ) を解釈しています。多くはその定義に従います。
Version 1.0 では書式フォーマットの解釈を VB.NET にて実装していましたが、v1.2 では C# による実装となりました。
当アプリのビルドでは PAL_PARSER プロジェクト（ターゲットフレームワーク .NET Framework 4, クラスライブラリ）が該当し、VB.NET 側の PAL_VIEWER プロジェクトから参照関係になっています。
本書では VB からの呼び出し例として記載します。
​
TWELITE PAL / ARIA / CUE の無線パケットは App_Wings を書き込んだ MONOSTICK などで受信します。この受信データは :80000...<CR><LF> といった電文で、データ量も多く複数の形式になるためデータの取り出しが容易では有りません。ここでは .NET 開発環境家で、この解釈処理を行うためのライブラリについて解説します。
PAL の書式フォーマットの構造は、大まかには、共通データ部とセンサーデータ部に分別されます。センサーデータ部は[センサーデータ]のブロックが並んでいる構造で、PALの種別などによって数と種類は変わります。
[共通ヘッダ]{[センサーデータ1][センサーデータ2]...[センサーデータn]}
​
以下に挙げた関数とクラスを受信データ解釈に用います。
関数とクラス
解説
PAL_Utils.genDataPresentation()
データ列の解釈を行う
ClsDataFormatPalApp
共通ヘッダ部の解釈データ
ClsDataPayloadPalSensors
センサーデータ部
​
関連ソースファイル
以下のソースコードにより PAL 親機より出力されるデータを解釈します。
※ ソースコードはパルアプリビューアのサイトより入手ください。
ファイル名
内容
ITweDataPresentation.cs
UART 電文のエンコード(ASCII 書式)を解釈する。解釈ができれば、ITweDataFormat による解釈も行う。
ClsDataPresentationAscii.cs
ASCII書式 :800...<CR><LF> の解釈。
ITweDataFormat.cs
上記 ASCII 書式で解釈されたデータ書式を表現する（アドレス情報など共通情報や、データ書式内のデータ構造など）。また書式を解釈後、ITweDataPayloadを生成する。
ClsDataFormatPAL.cs
PAL のデータ書式を解釈する。
ITweDataPayload.cs
センサー情報など各データを表現する。
ClsDataPayloadPalSensors.cs
SENSE PAL の個別センサーの集約データ型。
ClsDataPalSenseElement.cs
SENSE PAL の単独センサーのデータ型。
MUtils.cs
ITWE??? 抽象型より、適切なクラスの生成を行うジェネレータや、諸ユーティリティ。
プロジェクトへの組み込み方法
上記は Visual Studio (2019を想定) で、プロジェクト定義されたライブラリなどを参照する手順です。詳細はマニュアルや一般の情報を参照ください。
1.PAL_PARSER ディレクトリを開発プロジェクト配下の適当な場所にコピーします。
2.Visual Studio の[ソリューション]にPAL_PARSER プロジェクトを追加します。
3.開発プロジェクト中のプロジェクト[プロパティ]>[参照設定]にPARL_PARSERを追加します。
4.利用するソースコードの先頭部で Imports MONOW_PAL_PARSER を追加します。
上記参照設定を行えば、ソースコード中で PAL_PARSER ライブラリのクラスなどが参照可能になります。
読み出し方法
TWELITE PAL Viewer では、SerialPort1 の .DataRecievedイベントを起点として、書式の解釈が行われます。
以下のコード例(VB.NET)は、シリアルポートからのデータを String型の文字列 ( :80000000CF0002 ) として受け取り、内容を解釈した後、解釈文字列として戻す関数です。（一例で、すべてのデータ要素やセンサーに対応したコードではありません）
​VB.NET​
​C#​
以下は、VB.NET のコードを例に解説しています。
エラー処理は、Try Catch 構文で、まとめて例外処理しています。内部からのエラー時には throw new Exception(); といった例外が発生します。
​
まず、解釈のために文字列をバイト列に変換して、genDataPresentation() により、データ解釈を行います。実行後、解釈済みのClsDataPresentationAsciiオブジェクトが生成されます。（末尾の改行コードが省略された場合を想定してdataText & vbCr と CR コードを追記した上、念の為末尾をCRの連続と変換しています。PAL_PARSERは末尾 CR (&H0D) を終端と処理しています）
' String -> Byte()
Dim b() As Byte = System.Text.Encoding.ASCII.GetBytes(dataText & vbCr)
' 末尾のコントロール文字を CR(&H0D) に書き換え
For i = b.Length - 1 To 0 Step -1 
    If b(i) < &H20 Then b(i) = &HD Else Exit For
Next
' :8000... を解釈しバイナリ列に[80 00 ...]に変換し、書式の解釈まで行う
Dim dataArrival = PAL_Utils.genDataPresentation(b)
​
続いて、データ書式、センサー情報を取り出します。dataFmt はデータ書式で、アドレス情報などを得ることができます。dataPayはセンサー情報で複数のセンサーの情報をひとまとめにしています。
Dim dataFmt As ClsDataFormatPalApp = dataArrival.objFormat 'データ形式、無線ノードの情報
Dim dataPay As ClsDataPayloadPalSensors = dataFmt.objPayload '各種センサー情報
​
データ書式(ClsDataFormatPalApp)で得られる情報を列挙します。
名前
​
内容
BLQI
Byte
LQI（受信感度相当）情報
UsDataSer
UShort
続き番号
BBalPCB
Byte
SENSE PAL 種別識別子
BSrcAddr
Byte
SENSE PAL の論理ID
UiSrcAddr
UInteger
SENSE PAL のアドレス
UiRepeater
UInteger
配送経路（&H80000000UI なら直接、それ以外の場は最後に配送した中継器のアドレス）
※ PAL アプリの設定によって中継器のアドレスの定義は変化します。
​
次にセンサーの情報を得ます。dataPay.SensoerCode() により、センサーの種別を指定して情報を得ることができます。戻り型はList(Of ClsDataPalSenseElement)で、０個以上の要素が格納されます（Nothingにはならない）。ここでは電圧関連(ClsDataPalSenseElement.E_SNSCD.VOLT)のリストを探索します。
Dim l = dataPay.SensorCode(ClsDataPalSenseElement.E_SNSCD.VOLT)
ここでは、電源電圧(ClsDataPalSenseElement.E_EXCD_VOLT.POWER)の情報が欲しいので、リストの中にあるか探索します。見つかったらローカル変数 iVoltに値を格納します。
For Each m In l
    If m.Ex = ClsDataPalSenseElement.E_EXCD_VOLT.POWER Then
        iVolt = m.Data(0)
    End If
Next
​
ClsDataPalSenseElement クラス
このクラスは、各センサーの単一のデータを表現します。以下にデータの取り出しのためのプロパテを列挙します。
名前
型
内容
IsError
Boolean
データエラーの場合は True となる。
ErrorCode
Byte
エラーコードが入ります。
Data
Object(Byte,Shortなど)
センサーのデータを格納します。エラーなどで Nothing になる場合があります。データについては要素数が１つであっても配列型となります。
例えば Byte型のデータが一つだけ含まれる場合であっても Byte(0) で宣言された配列オブジェクトとなります。
SensorCode
Byte
センサー種別が入ります。
Ex
Object(Byte)
拡張データが入ります。主に電圧情報など、センサー種別が同じでも、複数ある場合に使われます。
​
​
​
センサーの種別を調べるための列挙型ClsDataPalSenseElement.E_SNDCDの定義は以下です。
名前
内容
HALL
開閉磁気センサー
TEMP
温度センサー
HUMD
湿度センサー
LUMI
照度センサー
VOLT
電圧
​
電圧センサーの種別を特定するための列挙型ClsDataPalSenseElement.E_EXCD_VOLTは以下です。
名前
内容
POWER
電源電圧
ADC1
ADC1
​

関数とクラス	解説
`PAL_Utils.genDataPresentation()`	データ列の解釈を行う
`ClsDataFormatPalApp`	共通ヘッダ部の解釈データ
`ClsDataPayloadPalSensors`	センサーデータ部

最終更新 1yr ago

名前		内容
`BLQI`	Byte	LQI（受信感度相当）情報
`UsDataSer`	UShort	続き番号
`BBalPCB`	Byte	SENSE PAL 種別識別子
`BSrcAddr`	Byte	SENSE PAL の論理ID
`UiSrcAddr`	UInteger	SENSE PAL のアドレス
`UiRepeater`	UInteger	配送経路（`&H80000000UI` なら直接、それ以外の場は最後に配送した中継器のアドレス） ※ PAL アプリの設定によって中継器のアドレスの定義は変化します。

名前	型	内容
`IsError`	Boolean	データエラーの場合は True となる。
`ErrorCode`	Byte	エラーコードが入ります。
`Data`	Object(Byte,Shortなど)	センサーのデータを格納します。エラーなどで Nothing になる場合があります。データについては要素数が１つであっても配列型となります。例えば Byte型のデータが一つだけ含まれる場合であっても `Byte(0)` で宣言された配列オブジェクトとなります。
`SensorCode`	Byte	センサー種別が入ります。
`Ex`	Object(Byte)	拡張データが入ります。主に電圧情報など、センサー種別が同じでも、複数ある場合に使われます。

ファイル名	内容
ITweDataPresentation.cs	UART 電文のエンコード(ASCII 書式)を解釈する。解釈ができれば、ITweDataFormat による解釈も行う。
ClsDataPresentationAscii.cs	ASCII書式 `:800...<CR><LF>` の解釈。
ITweDataFormat.cs	上記 ASCII 書式で解釈されたデータ書式を表現する（アドレス情報など共通情報や、データ書式内のデータ構造など）。また書式を解釈後、ITweDataPayloadを生成する。
ClsDataFormatPAL.cs	PAL のデータ書式を解釈する。
ITweDataPayload.cs	センサー情報など各データを表現する。
ClsDataPayloadPalSensors.cs	SENSE PAL の個別センサーの集約データ型。
ClsDataPalSenseElement.cs	SENSE PAL の単独センサーのデータ型。
MUtils.cs	ITWE??? 抽象型より、適切なクラスの生成を行うジェネレータや、諸ユーティリティ。

名前	内容
`HALL`	開閉磁気センサー
`TEMP`	温度センサー
`HUMD`	湿度センサー
`LUMI`	照度センサー
`VOLT`	電圧