ライブラリの使用
ソースコード上でライブラリを使用するには #include <mwm5.h>
をソースコード上に記述します。
Arduino.h, M5Stack.h は mwm5.hより後でインクルードしてください。
mwm5.hにはusing namespace
を用いて、ライブラリ中の名前空間を可視にし省略できる宣言が含まれています。これら名前空間を明示的に記述したい場合は替わりに#include <twelite.hpp>
を記述してください。
ここでは、以下の解説が含まれます。
シリアル電文パーサーの利用例
TWELITE 無線マイコンから UART (シリアルポート)経由での電文書式を解釈します。電文書式は、可読性・エラー検出などを目的として、伝送したいデータ列に対して所定の変換を行います。
ここではアスキー形式の解釈を行うAsciiParser
について解説します。
アスキー形式は、バイナリで構成されたデータ列を文字列で表現する方法です。TWELITE無線マイコンでは最も良く用いられる形式です。
例えばバイト列で 00A01301FF123456
をアスキー形式で表現すると、以下のようになります。先頭は :
で B1
がチェックサム、終端は [CR:0x0d][LF:0x0a]
となります。
:00A01301FF123456B1[CR][LF]
終端のチェックサムを省略できます。チェックサムからCRLFの系列をX
に置き換えます。文字化けによる誤ったデータ系列には弱くなりますが、実験などでデータを送付したいときに便利です。
:00A01301FF123456X
上記の例では parser_ascii
というオブジェクトを内部バッファ256バイトで生成しています。このバッファサイズは、書式の解釈後に必要なバイト数です。
ASCII形式では実際のバイト数の約2倍の書式になります。例えば書式が200バイトの系列の場合は、実データは約100バイトになります。
無線パケットの最大格納バイト数が100バイト強であるため、この例では余裕をもって256バイトのバッファとしています。
このAsciiParserは1バイトずつの処理を行います。シリアルポートからは1バイトずつデータが到着するためです。
上記例では、シリアルポートから1バイト読み出してはparse_acsii
に1バイトずつ<<演算子を用いて読み込ませています。
直後のif(pars_ascii)
での判定は、アスキー形式の系列が正しく解釈できたかどうかを判定しています。
以下のように配列にアクセスできます。
Parser
オブジェクトにデータ列が格納されている場合、>>
演算子を用いることで書式をシリアルポート(Serial
)やターミナル(ITerm
)などに出力することが出来ます。
通常は、解釈用のParser
オブジェクトと出力用のParser
オブジェクトは別々に用意します。
解釈用のオブジェクトはシリアル入力など都度処理が行われます。このオブジェクトを一時的なデータ出力の目的で使用すると、解釈中の内部データが破壊されます。
newTwePacket()
は入力されたデータ系列を解釈して、spTwePacket
型のオブジェクトを生成します。このオブジェクトはTwePacket
型のデータを格納するスマートポインタstd::shared_ptr
で、メモリ管理を簡素化することができます。
パケット種別はE_PKT
列挙体で定義されています。ここではTWELITE PALの出力形式PKT_PAL
の解釈を行います。
std::shared_ptr
の利用は、パケット情報を他にコピーして利用する場合を想定しています。例えば履歴配列に保存して、過去の情報を参照するような場合です。
オブジェクトは参照カウンタにより管理されていて、所有者が0になれば破棄されます。
解釈されたパケットの種別はidentify_packet_type()
により判別します。パケット種別はE_PKT
列挙体で定義されています。
解釈したパケットがE_PKT::PKT_PAL
と判定された場合は、refTwePacketPal()
によりTwePacketPal
型として参照できます。上記コード例ではユニバーサル参照auto&&
を用いて型名を推測させています。
PALのパケット書式は様々な派生があります。
ターミナル(コンソール)クラスの利用例
M5stackの320x200ドット液晶に固定幅ターミナルウインドウを表示します。
以下は画面出力の例です。
まずターミナルオブジェクトを生成します。ここでは最大64カラム、最大20行、左上から (0,16)の位置に(320,192)サイズの領域とします。
次に「東雲フォント16ドット」をフォントID=10で生成しています。フォントを管理するオブジェクトはライブラリ内部で生成・管理されます。
ターミナルにフォントなどを基本的な設定を行います。フォントを先ほどのフォントID=10として指定し、フォントの文字色と背景色を指定します。カーソルを2(ブリンク表示)とします。最後にforece_refresh()
にて初期描画を行います。
setup()
が終了したらloop()
での周期実行中に、一定時間ごとに画面の描画を行います。ここでは32ms以上経過したら再描画するようにしています。
以下の例ではボ タン Aでは"hello world!" + 改行の出力、ボタンBでは画面のクリア、ボタンCも同様に画面のクリア(エスケープシーケンスによる)を行います。
解釈済みの系列はget_payload()
メソッドにて取得できます。get_payload()
はの参照型を戻します。
解釈時にまずイベントデータがあるかどうか取り出します。イベントが含まれるパケットはにより判定できます。イベントのみ受信できれば良い場合はで得られたイベントデータを参照して終了です。
イベント以外の情報が欲しい場合は、一旦を用いてパケットのデータ構造を特定します。特定したデータ構造に応じたデータ取得を行います。
上記の例では、MAG(OPEN-CLOSE SENSE PAL)のオブジェクトを生成しています。ここではオープンクローズに応じた分岐にを読み出しています。
====== | 元データのバイト数 | バイト数 | 解説 |
ヘッダ | 1 |
|
データ部 | N | 2N | 元データの各バイトをアスキー文字列2文字(A-F は大文字)で表現します。
例えば 0x1F は |
チェックサム | 2 | データ部の各バイトの和を8ビット幅で計算し2の補数をとります。つまりデータ部の各バイトの総和+チェックサムバイトを8ビット幅で計算すると0になります。
チェックサムバイトをアスキー文字列2文字で表現します。
例えば |
フッタ | 2 | [CR] (0x0D) [LF] (0x0A) を指定する。 |