HRSLIB 2.1
easy H8 RS-232C LIBrary by I.N. 2011/6/15
更新履歴
2011/06/15 ver.2.1 送信リングバッファ処理の改良 HRS_Send()
2008/10/07 ver.2.0 送信もリングバッファ仕様とした
2007/02/28 ver.1.0 初版


1.はじめに
 CPUボード H8/3069F + YellowIDE でRS-232Cシリアル通信プログラムを
作成するための関数ライブラリです.
 H8/3069F以外のH8(CPU)でも使える可能性はありますが未確認です.
 動作確認は 秋月電子AKI-H8/3069F + イエローソフトYellowIDE 6.5 で行いました.


2.特長

 リングバッファ構造の受信バッファがあり,受信割り込みによって受信データは
バックグラウンドで自動的に受信バッファへ格納されます.
 受信データが来る瞬間にメインプログラムで他の作業を実行していてもデータを
取りこぼすことがありません.
 ただし,受信バッファが一杯になった後に受信したデータはすべて無視(破棄)
されますので,受信バッファが一杯になる前にデータを読み出すようにしてください.

 リングバッファ構造の送信バッファがあり,送信ではデータはいったん送信バッファへ
格納されます.送信バッファへデータの格納が終わると,送信関数の制御はすぐに戻って
くるのでメインプログラムでは次の他の処理を行うことができます.
 送信割り込みによって送信バッファ内のデータはバックグラウンドで自動的に送信されます.
 送信バッファが一杯になった状態で送信関数を実行するとデータはすべて無視(破棄)され
ますので,送信バッファに空きがあることを確認してから送信するようにしてください.


3.使用方法とサンプル

3.1 使用方法

 プログラムの先頭で以下のようにインクルードしてください.
 #include <3069s.h>
 #include "hrslib.h"

 また,YellowIDEのプロジェクトの設定(YCオプション)で
  /p メンバを境界を考慮して可能な限り詰めて配置する
  /b ビットフィールドを上位ビットから割り付ける
にチェックを入れておいてください.

 さらに,YellowIDEのプロジェクトの設定(割り込み)で
 ベクタ番号:52 関数名:HRS_eri0 言語:C
 ベクタ番号:53 関数名:HRS_rxi0 言語:C
 ベクタ番号:54 関数名:HRS_txi0 言語:C
 ベクタ番号:56 関数名:HRS_eri1 言語:C
 ベクタ番号:57 関数名:HRS_rxi1 言語:C
 ベクタ番号:58 関数名:HRS_txi1 言語:C
 ベクタ番号:60 関数名:HRS_eri2 言語:C
 ベクタ番号:61 関数名:HRS_rxi2 言語:C
 ベクタ番号:62 関数名:HRS_txi2 言語:C
を登録しておいてください.
(SCIの使わないチャンネルがある場合,そのチャンネルに対応する
割り込みベクタについては,登録を省略しても構いません)

 <注意>
 HRS_Open()によってオープンした後は,メインプログラム内で
 割り込み禁止 _di(); を実行しないようにしてください.
 _di(); を実行するとデータの送受信ができなくなります.

3.2 サンプル
// H8/3069F用RS-232C通信ライブラリHRSLIB.Hを使ったサンプル
// 受信した文字をそのまま送信する

#include <3069s.h>
#include "hrslib.h"

void main(void)
{
        char buf[32];
        int n;

        HRS_Open(1);

        HRS_Sends(1,"Hello!\r\n");

        for(;;){
                n=HRS_CheckRecv(1);     //受信データの確認

                //もし1文字でも受信データがあれば以下の処理をする
                if(n){
                        n=HRS_Recv(1,buf,n);   //データの受信

                        while(HRS_CheckSend(1)<n);     //送信バッファの確認

                        HRS_Send(1,buf,n);     //データの送信
                }

                //...
                //この間,別の作業をしてもかまわない.
                //...
        }
}

4.設定の変更

4.1 送受信バッファのサイズ変更
 バッファのサイズのデフォルト値は,送信・受信・いずれのチャンネルも32[バイト]ですが,
下記のようにして変更できます.デフォルト値より大きくすることも小さくすることもできます.
バッファのサイズの最小値は 1 です.大きくすれば,それだけRAMを食います.
SCIの各チャンネルごとに異なるバッファサイズを指定できます.
また,受信と送信で異なるバッファサイズを指定できます.

//受信バッファのサイズ変更
#define HRS_RECVBUFFERSIZE0 20
#define HRS_RECVBUFFERSIZE1 64
#define HRS_RECVBUFFERSIZE2 10
//送信バッファのサイズ変更
#define HRS_SENDBUFFERSIZE0 10
#define HRS_SENDBUFFERSIZE1 100
#define HRS_SENDBUFFERSIZE2 20

#include "hrslib.h"

4.2 ボーレートの変更
 ボーレートの初期値は38,400 bps(厳密には39062.5 bps)ですが,
下記のようにすると変更できます.(SCI0/1/2で異なるボーレートを設定可能)

//SCI0/SCI1/SCI2 を 9600 bpsにする場合
#define HRS_BRR0 80
#define HRS_BRR1 80
#define HRS_BRR2 80
#include "hrslib.h"

上記の値はCPUのクロックが25.0MHzの場合です.

なお,クロックが25.0MHzの場合,BRR値は次のようになります.
6 => 111607.1[bps] (115200に対し-3.12%)
12 => 60096.2[bps] (57600に対し+4.33%)
13 => 55803.6[bps] (57600に対し-3.12%)
19 => 39062.5[bps] (38400に対し+1.73%)
40 => 19054.9[bps] (19200に対し-0.76%)
80 => 9645.1[bps] (9600に対し+0.47%)

誤差が大きなボーレート設定において,連続した大量のデータを送受信しようと
する場合,誤差が累積して,誤通信(文字化け)が発生する可能性があります.


5.関数リファレンス

================全体に関するもの================

--------------------------------------------------------
int HRS_Open(int n);
--------------------------------------------------------
説明
 シリアル通信(RS-232C)のポートをオープンします.最初に必要です.
 通信設定は,ボーレート38400bps,スタートビット1bit,ストップビット1bit,パリティなし,
 キャラクタ長8bit,XON/XOFFなしです.
 オープンに成功すると,HRS_Close() でクローズするまで HRSLIB の各関数が使用可能となります.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
戻り値
 0 正常終了(オープンできた)
 1 エラー(すでにオープンされている)
使用例
 HRS_Open(1);


--------------------------------------------------------
int HRS_Close(int n);
--------------------------------------------------------
説明
 シリアル通信ポートをクローズします.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
戻り値
 0 正常終了(クローズできた)
 1 エラー(ポートがオープンされていない)
使用例
 HRS_Close(1);


================送信に関するもの================

--------------------------------------------------------
int HRS_Send(int n, unsigned char *buf, int size);
--------------------------------------------------------
説明
 データの送信を行います.
 送信バッファへデータの格納が終わると制御はすぐに戻ってきます.
 (実際のデータ送信はただちに実行されますが,送信バッファが空で
 ない場合,バッファにたまっているデータの送信が優先されます)
 送信バッファからあふれたデータは無視(破棄)されます.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
 buf:送信データが格納されている領域の先頭アドレス(ポインタ)
 size:送信データのサイズ(単位:バイト)
戻り値
 送信バッファへ格納されたデータのバイト数(単位:バイト)
 (オープンされていないとき,この関数は 0 を返します.)
使用例
 char buf[32];
 HRS_Send(1,buf,32);


--------------------------------------------------------
int HRS_CheckSend(int n);
--------------------------------------------------------
説明
 送信バッファの空きサイズをバイト単位で返します.
 データを送信するときは,この関数でバッファの空きを確認してから
 送信するようにすると,データの送信洩れがありません.
 送信バッファのサイズより大きな値を返すことはありません.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
戻り値
 送信バッファの空きサイズ(単位:バイト)
使用例
 int n;
 char buf[32];
 while(HRS_CheckSend(1)<n);
 HRS_Send(1,buf,n);


--------------------------------------------------------
int HRS_ClearSend(int n);
--------------------------------------------------------
説明
 送信バッファをクリアします.
 バッファに残っている送信前のデータはすべて破棄され送信されません.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
戻り値
 0 正常終了
 1 エラー(オープンされていない)
使用例
 HRS_ClearSend(1);


--------------------------------------------------------
int HRS_Putc(int n, int c);
--------------------------------------------------------
説明
 1バイト送信します.
 送信バッファへデータの格納が終わると制御はすぐに戻ってきます.
 (実際のデータ送信はただちに実行されますが,送信バッファが空で
 ない場合,バッファにたまっているデータの送信が優先されます)
 送信バッファからあふれたデータは無視(破棄)されます.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
 c:送信データ(下位8ビットのみ有効)[0〜255] 
戻り値
 送信バッファへ格納されたデータのバイト数(単位:バイト)[0 or 1]
 (オープンされていないとき,この関数は 0 を返します.)
使用例
 HRS_Putc(1, 'A');


--------------------------------------------------------
int HRS_Puts(int n, unsigned char *s);
--------------------------------------------------------
説明
 文字列を送信します.
 文字列の終端コード(\0)は改行文字(\n)へ変換して送信されます.
 送信バッファへデータの格納が終わると制御はすぐに戻ってきます.
 (実際のデータ送信はただちに実行されますが,送信バッファが空で
 ない場合,バッファにたまっているデータの送信が優先されます)
 送信バッファからあふれたデータは無視(破棄)されます.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
 s:送信される文字列が格納してある領域の先頭アドレス(ポインタ)
戻り値
 送信バッファへ格納されたデータのバイト数(単位:バイト)(最後の改行も含む)
 (オープンされていないとき,この関数は 0 を返します.)
使用例
 char *s="ABC";
 HRS_Puts(1, s);
 HRS_Puts(1, "Hello");


--------------------------------------------------------
int HRS_Sends(int n, unsigned char *s);
--------------------------------------------------------
説明
 文字列を送信します.
 文字列の終端コード(\0)の直前文字までを送信し,終端コードは送信しません.
 送信バッファへデータの格納が終わると制御はすぐに戻ってきます.
 (実際のデータ送信はただちに実行されますが,送信バッファが空で
 ない場合,バッファにたまっているデータの送信が優先されます)
 送信バッファからあふれたデータは無視(破棄)されます.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
 s:送信される文字列が格納してある領域の先頭アドレス(ポインタ)
戻り値
 送信バッファへ格納されたデータのバイト数(単位:バイト)
 (オープンされていないとき,この関数は 0 を返します.)
使用例
 char *s="ABC";
 HRS_Sends(1, s);
 HRS_Sends(1, "Hello\r\n");


--------------------------------------------------------
int HRS_Printf(int n, char *format [, argument]...);
--------------------------------------------------------
説明
  (注意)この関数を使うとプログラムのサイズが大きくなります.
 書式付き文字列を送信します.
 使える書式は,一般的な printf() と同じです.制御文字や漢字もそのまま送信されます.
 文字列の終端コード(\0)は改行文字(\n)へ変換して送信されます.
 送信バッファへデータの格納が終わると制御はすぐに戻ってきます.
 (実際のデータ送信はただちに実行されますが,送信バッファが空で
 ない場合,バッファにたまっているデータの送信が優先されます)
 送信バッファからあふれたデータは無視(破棄)されます.
<補足>
 一回に送信できる文字数は256バイトです.このデフォルト値を変更するには
 #define HRS_PRINTF_BUFFERSIZE 1024(←1024バイトに変更する例) を
 #include "hrslib.h"より前に記述してください.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
 format:書式付き文字列へのポインタ
 argument...:引数(必要に応じて)
戻り値
 送信バッファへ格納されたデータのバイト数(単位:バイト)(最後の改行も含む)
 (オープンされていないとき,この関数は 0 を返します.)
使用例
 HRS_Printf(1, "a=%03d",a);


================受信に関するもの================

--------------------------------------------------------
int HRS_Recv(int n, unsigned char *buf, int size);
--------------------------------------------------------
説明
 受信バッファからデータを読み取ります.
(注意)
 指定されたデータ数よりも受信バッファのデータ数が少ない場合,
 バッファ内のデータがなくなった時点で制御が戻ってきます.
 指定された数のデータが来るまで待つことはしません.
 この関数は実際に読み込んだデータの数を返します.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
 buf:受信データを格納する領域の先頭アドレス(ポインタ)
 size:受信データ数(単位:バイト)
戻り値
 受信できたデータ数(単位:バイト)
 (オープンされていないとき,この関数は 0 を返します.)
使用例
 char buf[32];
 int n;
 n=HRS_Recv(1,buf,32);


--------------------------------------------------------
int HRS_CheckRecv(int n);
--------------------------------------------------------
説明
 受信バッファにたまっているデータの数(単位:バイト)を返します.
 受信バッファのサイズより大きな値を返すことはありません.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
戻り値
 受信バッファ内のデータ数(単位:バイト)
使用例
 int n;
 char buf[32];
 n=HRS_CheckRecv(1);
 HRS_Recv(1,buf,n);


--------------------------------------------------------
int HRS_ClearRecv(int n);
--------------------------------------------------------
説明
 受信バッファをクリアします.
 バッファにたまっている読み取り前のデータはすべて破棄されます.

引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
戻り値
 0 正常終了
 1 エラー(オープンされていない)
使用例
 HRS_ClearRecv(1);


--------------------------------------------------------
int HRS_Getc(int n);
--------------------------------------------------------
説明
 受信バッファから1バイト読み取り,その値を返します.
 もしバッファにデータがない等の理由で受信できなかった場合は-1を返します.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
戻り値
 受信データ[0〜255]または-1
使用例
 int c;
 c=HRS_Getc(1);
 if (c<0) ...


--------------------------------------------------------
int HRS_Gets(int n, unsigned char *s);
--------------------------------------------------------
説明
 受信バッファから文字列を読み取ります.
 最初に改行または終端コード(\r or \n or \0)が来るまで受信し,
 その改行または終端コードは\0に置き換えて格納されます.
 最初の改行または終端コードが来るまで制御は戻ってきません.
引数
 n:ポート番号 [0〜2] (SCI0〜SCI2に対応します)
 s:受信した文字列を格納する領域の先頭アドレス(ポインタ)
  格納領域 s のサイズを超える場合もチェックされないので注意してください.
戻り値
 受信できた文字列のバイト数(改行または終端コードを含む)
使用例
 char buf[100];
 HRS_Gets(1,buf);


ダウンロード

 hrslib.h ファイル hrslib.h がZIP圧縮してあります.

 旧バージョンのページ → HRSLIB ver.1.0


1つ上へ戻る