- 汎用シリアルツール用にカスタマイズした、クラスライブラリです。
- 携帯電話等の１６芯インタフェースを使用したシリアルツールの設計が、出来る限り簡単に出来る様に設計しています。
本体
- rslib.obj ライブラリ本体
- rslib.h ライブラリヘッダ
- rslib.cpp ライブラリソース
- mklib.bat ライブラリ構築用バッチ
- doc\rslib.html このドキュメント
- doc\*.gif ドキュメント補足画像
test.cpp Windows版サンプルソースmk.bat Windows版サンプルビルドバッチtestd.cpp DOS版サンプルソースmkd.bat DOS版サンプルビルドバッチ※公開版には、サンプルは含んでおりません。
- Windowsアプリに組み込む場合、基本的には、スレッド側で使用して下さい。DOSアプリで使用する事も可能です。(サンプル参照)
- ユーザは、SerialFunctionクラスを継承して使用して下さい。
- 継承側でカスタマイズが必要となる部分は、Timerを使う部分と、SerialJobの部分です。この部分を、作成するWindowsアプリの仕様に合わせてカスタマイズして下さい。
※サンプルプログラムを参考にして下さい。 - デフォルトのタイマ機能は、チックカウントを使用しています。そのままでも使用出来ますが、Windowsを起動して、49.7日経過した前後で使用すると、49日間タイムアップしない場合が起こります，また、指定がint型で、ミリ秒単位の為，最大で３２秒程度までしか指定出来ませんので、ユーザ側でSetTimerを使用する等して、拡張する事をお勧めします。
- SerialJobは、そのままでも使用出来ますが、プライオリティの変更や、処理の追加等が有れば、拡張する事が出来ます。但し、こちらは、SerialJobのソースを読んで、動作を理解している方に限り拡張を行う様にして下さい。
- 継承先を、そのまま使用しても結構ですが、より効率的に使用出来るSerialControlクラスを用意しましたので、このクラスに渡して使う事を推奨します。
※サンプルプログラムを参照して下さい。
- SerialControlクラスは、基本的に、SerialFunctionクラスを、汎用のシリアル向けにカスタマイズしたものですが、SerialFunctionのインスタンスそのものを使います。サンプルプログラムの例を参考に、SerialFunctionを継承したクラスのインスタンスを渡すか、若しくは、SerialFunction自体のインスタンスを渡せばＯＫです。
- 基本的には、ポートのOpen()を行った後、Work()をポーリングします。
Work()は、SerialFunctionのSerialJobを呼び出す様に設定されています。これを行わないと、基本的にシリアルポートへの入出力はおろか、Trap等のファンクションも走りませんので、必ず行って下さい。SerialJobが拡張されている場合，拡張されたSerialJobが走ります。
- データの送信には、何種類かのインタフェースがあるので、仕様に合ったインタフェースを使用して下さい。
- 受信データの取り出し方法には、２種類の方法が有ります。
- Ｌｏｇを使用する方法
LogON(TRUE)を実行すると、ログバッファが有効になります。
LogON(FALSE)を実行すると、ログバッファは無効になります。
→Ｌｏｇについては後述
- SI_FIFOを使用する方法
SIFIFO_Enable(TRUE)にて、SIバッファが有効になります。
SIFIFO_Enable(FALSE)にて、SIバッファが無効になります。
SIバッファが有効な場合のみ,以下のメンバによるデータの取得が出来ます。
- int SenseSIData(void) ;
int SIDataLength(void) ;
int GetSIData(void) ;
void GetSIString(char *bf,int len) ;
int GetSIString(char *bf) ;
int GetSIHexString(char *xbf) ;
- Log,SI_FIFOは、デフォルトで無効になっているので、Trapで取得した以外のデータが必要な場合は、何れかを有効にする必要があります。勿論、両方有効にする事も可能ですし、ログの表示や解析などは必要無いという場合には、両者共に無効のままで使用しても問題有りません。
- Ｌｏｇを使用する方法
- Work(SerialJob)は、何らかの変化があると、０以外を返しますので、この値を参照して、操作の分岐を行うと良いでしょう。
- SerialJobの現在の戻り値は、
D0: SO出力有り→普通，無視しても良いです。
D1: SI入力有り→ログデータ等の表示/解析が必要であれば、FIFOからデータを読み出して下さい。
D2: TRAPが終了しています。→結果等を参照して下さい。
D3: TRAPがタイムアップしました。→結果を参照し、エラー処理等をします。
D4: TRAPがタイムアップしましたが、リトライを実施しました。→途中に処理を挟みたい場合等に利用します。
以上のデータを、共用体 SJRESULTで受けて、解析する事をお勧めします。
- Log機能について，
Logバッファは、int型のバッファで、シリアルの入出力を、クラスが管理する範囲で時間順に保存しています。
取り出した、１個のデータは、
- 下位８ビット＝送受信したデータ
- D8:SI/SOの区別(０＝SO,１＝SI)
- D9:SIのError表示 ※ここは、将来改版します。
- 下位８ビット＝送受信したデータ
修正：図内,CommPortSerialは、class CommSerialを示します。
- class SerialFunction : public CommSerial
- int OpenError ;
メンバ：シリアルポートOpen時のエラー番号が入ります。
- SerialFunction() ;
メンバ関数：コンストラクタ
- virtual ~SerialFunction() ;
メンバ関数：デストラクタ
- void SetBufferLength(long len) ;
メンバ関数：シリアルポートのFIFOバッファサイズを指定します。
デフォルトは、1024バイトが指定されていますが、これを変更する場合にのみ使用します。ユーザ拡張を行った場合は、コンストラクタから呼んで下さい。
- void SetEventMask(DWORD Msk) ;
メンバ関数：イベントマスクを設定します。
デフォルトは、０が指定されていますが、これを変更する場合にのみ使用します。ユーザ拡張を行った場合は、コンストラクタから呼んで下さい。
- BOOL Open(const char *Cport,UINT Br,BYTE Db,int Sb,int Pty) ;
メンバ関数：シリアルポートを開き、結果を返します。
失敗の場合、FALSEを返すので、OpenErrorを参照して、エラー処理を行って下さい。
- void Close(void) ;
メンバ関数：シリアルポートを閉じます。
- BOOL IsOpen(void) ;
メンバ関数：シリアルポートがオープンされている場合にTRUEを返します。
- void Log(BOOL sw) ;
メンバ関数：ログ機能を有効にします。
※↓下記UseSIFIFO参照
- void UseSIFIFO(BOOL sw) ;
メンバ関数：SI_FIFOを有効にします。
※Log及びSI_FIFOは、デフォルトで無効になっています。受信データを単独で解析する必要が有ればSI_FIFOを、送受信の履歴を解析する必要が有れば、Logを有効にして下さい。(両者共に有効にする事も出来ます)
- int GetLogBuff(int *gbf,int maxlen) ;
メンバ関数：ログデータを取得し、取得した長さを返します。
取得したデータは、gbfに格納され、最大でmaxlenまで取得します。Log機能が有効な場合のみ有効です。
- int GetLogData(void) ;
メンバ関数：ログデータを１個ずつ取り出します。
ログデータが無い場合は、0xffffを返します。 Log機能が有効な場合のみ有効です。
- virtual int SerialJob(void) ;
メンバ関数：拡張対象
シリアルインタフェースのメイン関数です。
この関数が呼ばれないと、SerialFunctionは、シリアルポートへの入出力を一切しませんので、必ずループ内でポーリングする様に設計して下さい。尚、この関数は、下記のメンバ関数を組み合わせて構成されています。ユーザ拡張の際は、これらの関数を利用される事を推奨します。
-
int TrapJob(void) ;
int TrapTimerCheck(void) ;
int SIJob(void) ;
int SOJob(void) ;
- virtual int SenseSIData(void) ;
メンバ関数：拡張対象(※１)
SI_FIFOにデータが蓄積されているかを調べます。SI_FIFOが有効な場合のみ有効です。
- virtual int SIDataLength(void) ;
メンバ関数：拡張対象(※１)
SI_FIFOの蓄積長を調べます。SI_FIFOが有効な場合のみ有効です。
- virtual int GetSIData(void) ;
メンバ関数：拡張対象(※１)
SI_FIFO内のデータを１バイト得ます。SI_FIFOが有効な場合のみ有効です。
- virtual void GetSIString(char *bf,int len) ;
メンバ関数：拡張対象(※１)
SI_FIFOのデータの先頭からlenバイトを、バッファbfに得ます。SI_FIFOが有効な場合のみ有効です。
(※１) SerialJobを拡張する等して、SI_FIFOを外部に用意する場合等、 この辺も拡張しておくというイメージで考えて下さい。
- virtual BOOL SetSOData(int a) ;
メンバ関数：拡張対象
SO_FIFOに、データを１バイトセットします。
SO_FIFOに空きが無い場合、失敗となりFALSEが返ります。
- virtual int SetSOString(char *bf,int len) ;
メンバ関数：拡張対象
SO_FIFOに、バッファbfのデータをlenバイトセットします。
SO_FIFOにセットしたバイト数を返します。
- BOOL SetTrapFunction(TRAPVALUE Tpv) ;
メンバ関数：トラップを仕掛けます。
引数は、構造体TRAPVALUEにセットして渡します。
- int GetTrapResult(char *gtbf,int len) ;
メンバ関数：最後に行われたトラップの結果を得ます。
継続データを取得している場合は、gtbfに取得したデータをlen文字分得る事が出来ます。
結果が成功の場合：１
結果が失敗の場合：０
結果が無効の場合：−１
を返します。
- BOOL IsTrapRunning(void) ;
メンバ関数：トラップが実行中か否かを検査します。
- virtual void SetTrapTimer(int tup) ;
メンバ関数：拡張対象
トラップのタイマをセットします。
- virtual void StopTrapTimer(void) ;
メンバ関数：拡張対象
トラップのタイマを停止します。
- virtual BOOL IsTrapTimeUp(void) ;
メンバ関数：拡張対象
トラップタイマがタイムアップしたか否かを検査します。
- int OpenError ;
- LOGDATAFORM共用体
-
Ｌｏｇバッファ(LogFIFO)を使用する場合，ログデータ読み出し時に使用する。
- 宣言
typedef union _LOGDATA_FORM_{
struct{
unsigned Data:8 ;
unsigned InOut:1 ;
unsigned PtErr:1 ; // ParityErr
unsigned Err:1 ; // その他エラー(Parity含む)
unsigned Dmmy:5 ;
}Param ;
struct{
unsigned Data:8 ;
unsigned Attr:8 ;
}part ;
int ix ;
} LOGDATAFORM ;
- Param.Data
- part.Data
- シリアルポートに送受信したログデータそのものです。
- part.Attr
- 該当データの属性を格納しています。内容は、下記の通り読み出す事が出来ます。
- Param.InOut
- 送受信(IN/OUT)の区別を記録するビットです。IN=1,OUT=0となります。
- Param.PtErr
- 受信データにパリティエラーを検出した場合、１となります。
- Param.Err
- パリティエラーを含むエラーがあった場合１となります。
- Param.Dmmy
- リザーブ,今後の拡張用に予約します。現行は、データ有りの場合、常に０となるので、ログデータの有無判別に使用出来ます。
- Param.InOut
- ix
ログデータ１個分の全体です。
- 宣言
- TRAPVALUE構造体
-
Trapファンクションを掛ける場合のパラメータ
- 宣言
typedef struct _TRAP_VALUE_{
char *SendData ;
int SendLength ;
char *TrapData ;
int TrapLength ;
int WaitLength ;
int TimeUp ;
int RetryCount ;
BOOL Reserve ;
} TRAPVALUE ;
- char *SendData ;
- int SendLength ;
- 送信するデータを、char型配列に格納し、先頭ポインタをSendData,送信するデータ長をSendLengthに指定します。
- char *TrapData ;
- int TrapLength ;
- 送信データを送出し、受信を待つデータをSendData,SendLength同様に指定します。
- int WaitLength ;
- Ｔｒａｐが成功し、継続するデータを受信する場合，そのデータ長を指定します。
- int TimeUp ;
- Ｔｒａｐ開始から、受信データ待ちのタイムアップ値を指定します。指定する単位は、SerialFunctionを拡張した場合は、そちらの仕様に従って指定します。デフォルトでは、ミリ秒単位で指定出来ます。
- int RetryCount ;
- Ｔｒａｐがタイムアップした場合の再試行回数を指定します。０ならば、１ショットです。
注）Reserve属性の場合、タイムアップ値が、その回数分延びるだけです。
- BOOL Reserve ;
- この値をTRUEとした場合、SendDataで指定した送信データを、最初に送信せずに保留し、TrapData+WaitLengthで指定したデータを受信した場合に送出します。アプリを受け側とし、特定のデータを受信した場合にのみデータ送信を行う場合に利用出来ます。
但し、このタイプのＴｒａｐが成功した場合、SO_FIFOに、送信データをセットする所で終わります。デフォルトのSerialJobでは、この後必ず出力操作を行いますが、ユーザがSerialJobを拡張して使用する場合は、必ずデータを送信する様に拡張する必要があります。
- 宣言
- class SerialControl
- SerialFunction *SFUNC ;
メンバ：SerialFunctionのインスタンス本体
- SerialControl(SerialFunction *sfc) ;
メンバ関数：コンストラクタ
→必ず、引数に、SerialFunctionのインスタンスを渡す。
- SerialControl() ;
メンバ関数：コンストラクタ
→ユーザ側で、SerialFunctionを拡張しない場合のインタフェースです。
- virtual ~SerialControl() ;
メンバ関数：デストラクタ
SerialFunctionのdeleteは、ここで行う。
- BOOL Open(const char *Cport,UINT Br) ;
メンバ関数：SerialFunctionのOpenを呼び出して、シリアルポートを開く
PDC用シリアルの為、COMポートと、ボーレートの指定のみを行えば良い。
データビットは８，ストップビットは１，パリティは偶数に固定される。
- int OpenError(void) ;
メンバ関数：SerialFunctionのOpenErrorを参照して返すインタフェース
- void Close(void) ;
メンバ関数：シリアルポートを閉じる。
- BOOL IsOpen(void) ;
メンバ関数：シリアルポートがオープン状態か否かを得る。
- BOOL ChangeBaudRate(UINT Br) ;
メンバ関数：ボーレートを変更する。
現在指定されているボーレートと同じであればなにもしない。違う場合は、一旦ポートをクローズして、再オープンする。
- int Work(void) ;
メンバ関数：SerialControlのメインルーチン
SerialFunctionのSerialJobを呼び出して動作させる。デフォルトの戻り値については、上述を参照の事
SerialJobがユーザ拡張されている場合，戻り値については、その仕様に合わせる事
- void SIFIFO_Enable(BOOL sw) ;
メンバ関数：SerialFunctionのSI_FIFOの可否をセットする。
- SIインタフェース 基本的には、SerialFunctionの機能【】内に一致する。
-
int SenseSIData(void) ; =【SenseSIData()】
int SIDataLength(void) ; =【SIDataLength()】
int GetSIData(void) ; =【GetSIData()】
void GetSIString(char *bf,int len) ;=【GetSIString()】
int GetSIString(char *bf) ; =【GetSIString()】 データ長は自動判別,取得したデータ長を返す。
int GetSIHexString(char *xbf) ; =【GetSIString()】 データ長は自動判別,データをHEX文字列にて戻す。取得したデータ長を返す。
- SOインタフェース 基本的には、SerialFunctionの機能【】内に一致する。
-
BOOL SetSOData(int a) ; =【SetSOData()】
int SetSOString(char *bf,int len) ;=【SetSOString()】
int SetSOHexString(char *xbf) ; =【SetSOString()】 HEX文字列から、データとデータ長を取得して送出する。
- TRAP利用インタフェース
基本的には、SerialFunction/SetTrapFunction()のリソース利用インタフェース(アプリの仕様に合ったものを使用すれば良い)
- BOOL SetTrap(char *sdt,int sl,char *tdt,int tl,int wtl,int tup,int rtry) ;
Reserve以外のパラメータをそのまま指定するインタフェース
※Reserveは無し
- BOOL SetTrap(char *sndhex,char *trphex,int wtl,int tmup,int rtry) ;
１の送出/トラップデータを、HEX文字列で指定するインタフェース
- BOOL SetTrap(TRAPVALUE tp) ;
TRAPVALUE構造体そのもので指定するインタフェース(Ack共用)
- BOOL SetAck(char *tdt,int tl,int wtl,char *sdt,int sl,int tup) ;
Reserve有りで、Retry無し,これ以外のパラメータをそのまま指定するインタフェース
- BOOL SetAck(char *trphex,int wtlen,char *sndhex,int tmup) ;
4.のデータ部分をHEX文字列で指定するインタフェース
- int GetTrapResult(char *gtbf,int len) ;
SerialFunctionのGetTrapResult同様
- int GetTrapResult(void) ;
TRAPの成功，失敗，無効の結果のみを得ます。
- int GetAckResult(char *gtbf,int len) ;
GetTrapResultのAck用インタフェース
※どちらを使っても問題ありませんが、ユーザプログラムの流れを整理する理由で用意しました。
- int GetAckResult(void) ;
上記同様
- BOOL IsTrapRunning(void) ;
SerialFunctionのIsTrapRunning同様
- BOOL SetTrap(char *sdt,int sl,char *tdt,int tl,int wtl,int tup,int rtry) ;
- void LogON(BOOL sw) ;
メンバ関数：ログ機能のＯＮ/ＯＦＦを指定します。
- Log参照インタフェース 基本的には、SerialFunctionの機能【】に一致
-
int GetLogData(int *gbf,int maxlen) ;=【GetLogBuff()】
int GetLogData(void) ; =【GetLogData()】
BOOL GetLogString(char *txbf) ; =【GetLogBuff()】 文字列に変換して取得する。
- SerialFunction *SFUNC ;
- void GetRsLibVersion(char *GetBf) ;
独立関数：バージョン情報の取得
- Ｔｒａｐ
Ｔｒａｐ機能は、シリアルシーケンスの基本となる，コマンドを送出し、ある一定の時間内に、特定のデータ(ＡＣＫ)及び付随データの戻りを待つと言うやりとりを、自動で行う機能を提供します。
逆に、ある特定のデータが受信を待ち、待ち時間内に受信した場合のみデータを送出するという機能も同時に提供します。
また、SerialControlには、この機能を、効率よく利用するための拡張インタフェースを用意しているので、様々な場合に合わせた使い方が可能となります。
- 例１(※class SerialControlを、コンストラクタSerialControl()にて使用する事を前提に記述します)
例えば、ある系に於いて、モード移行要求コマンド(12 34 56)を送信し、モード移行確認アック(78 9A BC)の受信を待つという操作を行う場合、その系の動作としては、既にモード移行が為されている場合は、即座にモード移行確認アックを返信しますが、モード移行が為されていなければ、一旦リセット動作をはさみ、モード移行要求を再発行しなければ、モード移行確認アックは返信されないというケースを想定します。
この様なシーケンスを設計する場合は、Ｔｒａｐのリトライ機能を利用して，
SetTrap("123456","789ABC",0,1500,2) ;
…Trap開始時に0x12,0x34,0x56(モード移行要求コマンド)を発行し、１．５秒(1500ms)以内に、0x78,0x9A,0xBC(モード移行確認ＡＣＫ)＋０バイトの受信を待つ。
タイムアップした場合は、同じ内容を２回まで繰り返す
の様に指定し、Work()をポーリングする事により、成功／失敗を受け取る事が出来ます。
- 例２(※class SerialControlを、コンストラクタSerialControl()にて使用する事を前提に記述します)
例えば、スレーブ側の設計をする場合、マスタ側となる通信相手が、コネクトコマンド(A1 A2 A3)を送信してくるのを待ち受けており、これを受信したら、コネクトＡＣＫ(例:B1 B2 B3)を発行する様なシーケンスを設計する場合は、SetAck関数を利用して、Reserve有りでＴｒａｐ機能を利用する事が出来ます。
SetAck("A1A2A3",0,"B1B2B3",10000) ;
…Trap開始から、１０秒(10000ms)以内に、コネクト(A1 A2 A3)＋０バイトを受信したら、コネクトアック(B1 B2 B3)を送信する。
の様に指定し、Work()をポーリングする事により、成功／失敗を受け取る事が出来ます。
API側のシリアル出力バッファがオーバーフローする場合の保留処理
→現行は、FIFOバッファを増やす事で暫定対応出来る。
V0.18.10までに対応完→CommSerial,SerialFunction,SerialControl,DataFIFO
通信エラーの通知方法未定
V0.19.10までに対応完→SerialFunction,SerialControl(ParityエラーのみLogに格納,他のエラーについては、ひとまとめでエラー通知されるので、必要があればその都度SerialControl->SFUNC->GetError()を呼び出す)