TWELITE PAL のパケットデータの表示を行います。

TWELITE PALの親機用ファームウェア(App_PAL-Parent-BLUE.binまたはApp_PAL-Parent-RED.bin)をTWELITE DIPにあらかじめ書き込んでおきます。

M5Stack側のTWELITE DIPは、以下のような接続をしておきます。

                      TWELITE DIP
                 -01:GND        VCC:28-------M5 3V3
                 -02:D14         D3:27-
  M5 GPIO16-------03:D7          D2:26-
                 -04:D5          D1:25-
                 -05:D18         A2:24-
                 -06:C           D0:23-
                 -07:M           A1:22-
                 -08:D19        RST:21-
                 -09:D4         D17:20-
  M5 GPIO17-------10:D6         D15:19-
                 -11:D8         D16:18-
                 -12:D9         D11:17-
                 -13:D10        D13:16-
  M5 GND----------14:GND        D12:15-

setup()

Serial2.setRxBufferSize(512);
Serial2.begin(115200, SERIAL_8N1, 16, 17);

シリアルポートの初期化を行っています。

setup_screen();

LCDスクリーンの初期化を行います。処理の内容はscreen.cにあり、ターミナル画面の初期設定を行います。

pkt_data.init_screen(fmt_title);

パケットデータの管理クラスの初期化を行います。

loop()

check_for_serial();

シリアルポートの入力チェックを行います。入力したデータを the_input_uart キューにいったん投入します。

process_input();

シリアルポートから入力データを処理します。ここではパーサーに文字列を投入します。パーサーによりシリアル電文が解釈できた場合は、update_screen()を呼び出しターミナル画面に文字を更新します。

check_for_refresh();

LCD画面上のターミナル画面領域を書き換えます。処理の内容はscreen.cにあります。

pkt_data

入力データの管理と表示を行う関数です。

このクラスでは、パケットデータに含まれる送信元論理IDごとのspTwePacketデータを保存しています。新しいデータを受信したら都度更新します。

画面表示は論理ID１から順に、最後のデータまで１行ずつ表示します。１画面に収まらない場合は、次のページに表示します。

init_screen(), reinit_screen()

void init_screen(const char *fmt_status) 
void reinit_screen()

init_screen()は初回の初期化を行います。fmt_statusは上部タイトルエリアへの出力文字を指定します。

フォント変更などで画面サイズに変化があった場合はreinit_screen()を呼び出します。

add_entry()

bool add_entry(spTwePacket spobj)

受信パケットデータを登録します。内部的にはIDに対応したspTwePacketの配列に値を入れます。

next_page(), prev_page(), set_page()

void next_page()
void prev_page()
void set_page(int entry)

ページ設定を行います。画面の更新をするため、直後にupdate_term()を呼び出します。

set_page()はentryに対応する論理IDが含まれるページに移動します。

update_status()

void update_status()

上部タイトルエリアの文字列を再設定します。

update_term()

void update_term()
void update_term(spTwePacket pal_upd, bool update_all)

ターミナル画面の表示文字列の更新を行います。

パラメータなしで呼び出すか、update_all=trueで呼び出すと、ターミナル全体の再描画を行います。

pal_updを指定しupdate_all=falseの場合は、pal_updの表示行のみを更新します。

ソフトウェアのライセンス

本パッケージ内で、ライセンス上特別な記述のないものは、モノワイヤレスオープンソースソフトウェア使用許諾契約書を適用します。詳細はパッケージ付属の文書を参照してください。

本ソフトウェアについては、モノワイヤレス株式会社が正式にサポートを行うものではありません。お問い合わせにはご回答できない場合もございます。予めご了承ください。

不具合などのご報告に対してモノワイヤレス株式会社は、修正や改善をお約束するものではありません。

また導入パッケージなどお客様の環境に依存して動作しない場合もございます。

/* Copyright (C) 2020 Mono Wireless Inc. All Rights Reserved.  *
 * Released under MW-OSSLA-*J,*E (MONO WIRELESS OPEN SOURCE    *
 * SOFTWARE LICENSE AGREEMENT).                                */

MW-OSSLA 概要

• 無保証です

• MW-OSSLA下で改変や再配布が可能です

• 商用利用を目的としない場合は、モノワイヤレス株式会社の製品を利用しない場合であっても、本ソフトウェアを利用することができます

• 商用利用を目的とする場合は、モノワイヤレスソフトウェア使用許諾契約書(MW-SLA)を添付したソースコードを配布し、ML-SLA下のソフトウェアを利用してください

  • MW-OSSLA下のソフトウェアに対し、MW-SLAを添付してソフトウェアを配布することが出来ます

    • 公開したり当社への連絡の必要はありませんが、手続きとして一旦MW-SLAを添付したソフトウェアとして配布してください

  • MW-SLAを添付したソフトウェアは、商用・非商用にかかわりなく、モノワイヤレス株式会社の製品上で利用しなければなりません

本ドキュメントの利用について

• 本ドキュメントは無保証です

• 本ドキュメントの著作権はモノワイヤレス株式会社が有します

• 本ドキュメントはライブラリの一部として取り扱い、MW-OSSLA下で取り扱われます

0.4.2 - 2020-02-17

https://github.com/monowireless/mwm5/releases/tag/0.4.2

初期バージョン

本ライブラリMWM5は、M5StackとTWELITE をシリアル(UART)接続して、M5Stack上でTWELITEを利用することを目的としています。

• TWELITEシリアルデータ形式のパーサーライブラリ

• M5Stack上でターミナル画面描画を行うライブラリ

以下の環境で開発しています。

動作等の不都合がある場合は、下記の環境を参考にしてください。

TWELITE DIPとの接続例です。シリアルポート(UART)のTX,RXのみのシンプルな接続です。

開発環境は以下のリンクを参照ください。

M5Stack Library -

最初に上記ライブラリに含まれるサンプルスケッチをビルド、書き込みを行ってください。

MWM5ライブラリのインストール

MWM5ライブラリは で配布しています。ソースファイル一式をダウンロードしてください。本ドキュメント記載時点に一致するバージョンはに記載があります。

変更履歴にある zip ファイルをダウンロードして、開発環境の指定するlibraryディレクトリに展開するか、開発環境の「zip形式のライブラリのインストール」を行ってください。アンインストールはライブラリディレクトリを削除します。

TWELITE 無線マイコンから UART (シリアルポート)経由での電文書式を解釈します。電文書式は、可読性・エラー検出などを目的として、伝送したいデータ列に対して所定の変換を行います。

ここではアスキー形式の解釈を行うAsciiParserについて解説します。

アスキー形式

アスキー形式は、バイナリで構成されたデータ列を文字列で表現する方法です。TWELITE無線マイコンでは最も良く用いられる形式です。

例えばバイト列で 00A01301FF123456 をアスキー形式で表現すると、以下のようになります。先頭は : で B1 がチェックサム、終端は [CR:0x0d][LF:0x0a] となります。

:00A01301FF123456B1[CR][LF]

終端のチェックサムを省略できます。チェックサムからCRLFの系列をXに置き換えます。文字化けによる誤ったデータ系列には弱くなりますが、実験などでデータを送付したいときに便利です。

:00A01301FF123456X

定義

AsciiParser の使用方法

オブジェクトの生成

// serial parser
AsciiParser parse_ascii(256);

上記の例では parser_ascii というオブジェクトを内部バッファ256バイトで生成しています。このバッファサイズは、書式の解釈後に必要なバイト数です。

無線パケットの最大格納バイト数が100バイト強であるため、この例では余裕をもって256バイトのバッファとしています。

バイト列の解釈

このAsciiParserは１バイトずつの処理を行います。シリアルポートからは１バイトずつデータが到着するためです。

while (Serial.available()) {
		int c = Serial.read();
		parse_ascii << char_t(c);
		
		if (parse_ascii) {
		 		// completed!
		}
}

上記例では、シリアルポートから１バイト読み出してはparse_acsiiに１バイトずつ<<演算子を用いて読み込ませています。

直後のif(pars_ascii)での判定は、アスキー形式の系列が正しく解釈できたかどうかを判定しています。

データ列の取り出し

if (parse_ascii) {
    auto&& p = parse_ascii.get_payload();
}

解釈済みの系列はget_payload()メソッドにて取得できます。get_payload()はSmplBuf_Byteの参照型を戻します。

以下のように配列にアクセスできます。

auto&& p = parse_ascii.get_payload();

if (p[0] == 0x80) { ... } // 最初の要素
int len = p.length();     // 要素数
for (auto&& x : p) {      // 各要素にアクセス
  Serial.print(x, HEX);
  Serial.print(" "); }

データ列の識別と対応オブジェクトの取得

パケットの生成

auto&& pkt = newTwePacket(parse_ascii.get_payload());

E_PKT pkt_typ = identify_packet_type(pkt);

if (pkt_typ == E_PKT::PKT_PAL) {
  // TWELITE PAL (App_PAL)
} else {
  // unknown packet type
}

newTwePacket()は入力されたデータ系列を解釈して、spTwePacket型のオブジェクトを生成します。このオブジェクトはTwePacket型のデータを格納するスマートポインタstd::shared_ptrで、メモリ管理を簡素化することができます。

パケット種別はE_PKT列挙体で定義されています。ここではTWELITE PALの出力形式PKT_PALの解釈を行います。

解釈されたパケットの種別はidentify_packet_type()により判別します。パケット種別はE_PKT列挙体で定義されています。

PALパケットの解釈

if (pkt == E_PKT::PKT_PAL) {
    auto&& pal = refTwePacketPal(pkt);
    
    if (pal.u8palpcb == E_PAL_PCB::MAG) {
      // for MAG
    } else
    if (pal.u8palpcb == E_PAL_PCB::AMB) {
      // for AMB
    }
}

解釈したパケットがE_PKT::PKT_PALと判定された場合は、refTwePacketPal()によりTwePacketPal型として参照できます。上記コード例ではユニバーサル参照auto&&を用いて型名を推測させています。

PALボード種別解釈

if (pal.u8palpcb == E_PAL_PCB::MAG) {
    PalMag mag = pal.get_PalMag();
    
    if (mag.u8MagStat == 0) {
       // closed
    } else {
       // opened
    }
}

PALのボード種別に応じたオブジェクトを生成して、ボード種別特有のデータにアクセスすることが出来ます。

上記の例では、MAG(OPEN-CLOSE SENSE PAL)のオブジェクトmagを生成しています。ここではオープンクローズに応じた分岐にmag.u8MagStatを読み出しています。

書式パーサーは、IParserを基底クラスとして、書式ごとに派生クラスを実装します。

      [IParser]
          ↑
     [AsciiParser]

パーサーは、シリアルポートのように１バイトずつ入力されるデバイスを想定し、１バイト単位での解釈を行い、都度状態を遷移する状態遷移マシンとして実装されます。

ソースコード上でライブラリを使用するには #include <mwm5.h> をソースコード上に記述します。

#include <mwm5.h>

#include <Arduino.h>
#include <M5Stack.h>

• Arduino.h, M5Stack.h は mwm5.hより後でインクルードしてください。

• mwm5.hにはusing namespaceを用いて、ライブラリ中の名前空間を可視にし省略できる宣言が含まれています。これら名前空間を明示的に記述したい場合は替わりに#include <twelite.hpp>を記述してください。

ここでは、以下の解説が含まれます。

• パーサーライブラリの使用方法

• ターミナルライブラリの使用方法

M5stackの320x200ドット液晶に固定幅ターミナルウインドウを表示します。

以下は画面出力の例です。

#include <mwm5.h>

#include <Arduino.h>
#include <M5Stack.h>

// ターミナルオブジェクトの生成
TWETerm_M5_Console the_screen(
    64, 20,
    { 0, 16, 320, 192 }, M5);

void setup() {
    // begin M5
    M5.begin(true, false, true, false);  // LCD, SD, Serial, I2C

    // create font as #10 (東雲フォント16)
    createFontShinonome16(10, 0, 0);
    
    the_screen.set_font(10);     // set font #10
		the_screen.set_color(ALMOST_WHITE, M5.Lcd.color565(90, 0, 50);
		                             // set color (fg, bg)
		the_screen.set_cursor(2);    // 0: no 1: curosr 2: blink cursor
		the_screen.force_refresh();  // repaint now.
		
		// initial message
		the_screen << "the_screen:" << crlf;
}

void loop() {
    // refresh screen
    static uint32_t t_last;
    uint32_t t_now = millis();
    
    if (t_now - t_last > 32) {
        the_screen.refresh();
        t_last = t_now;
    }
    
    // press A button
    if (M5.BtnA.wasReleased()) {
        the_screen << "hello world!" << crlf;
    }
    if (M5.BtnB.wasReleased()) {
        // force clear with whole redraw.
        the_screen.clear_screen();
    }
    if (M5.BtnC.wasReleased()) {
        // clear screen and set cursor home.
        the_screen << "\033[2J\[033H";
    }
}

まずターミナルオブジェクトを生成します。ここでは最大64カラム、最大20行、左上から (0,16)の位置に(320,192)サイズの領域とします。

// ターミナルオブジェクトの生成
TWETerm_M5_Console the_screen(
    64, 20,
    { 0, 16, 320, 192 }, M5);

次に「東雲フォント16ドット」をフォントID=10で生成しています。フォントを管理するオブジェクトはライブラリ内部で生成・管理されます。

void setup() {
  ...
  // create font as #10 (東雲フォント16)
  createFontShinonome16(10, 0, 0);

ターミナルにフォントなどを基本的な設定を行います。フォントを先ほどのフォントID=10として指定し、フォントの文字色と背景色を指定します。カーソルを2(ブリンク表示)とします。最後にforece_refresh()にて初期描画を行います。

void setup() {
  ...
  the_screen.set_font(10);     // set font #10
  the_screen.set_color(ALMOST_WHITE, color565(90, 0, 50);
                               // set color (fg, bg)
  the_screen.set_cursor(2);    // 0: no 1: curosr 2: blink cursor
  the_screen.force_refresh();  // repaint now.

setup()が終了したらloop()での周期実行中に、一定時間ごとに画面の描画を行います。ここでは32ms以上経過したら再描画するようにしています。

void loop() {
    // refresh screen
    static uint32_t t_last;
    uint32_t t_now = millis();
    
    if (t_now - t_last > 32) {
        the_screen.refresh(); // 再描画！
        t_last = t_now;
    }

以下の例ではボ タン Aでは"hello world!" + 改行の出力、ボタンBでは画面のクリア、ボタンCも同様に画面のクリア（エスケープシーケンスによる）を行います。

void loop() {
    ... 
    
    // press A button
    if (M5.BtnA.wasReleased()) {
        the_screen << "hello world!" << crlf;
    }
    if (M5.BtnB.wasReleased()) {
        // force clear with whole redraw.
        the_screen.clear_screen();
    }
    if (M5.BtnC.wasReleased()) {
        // clear screen and set cursor home.
        the_screen << "\033[2J\[033H";
    }

パーサーオブジェクトに１バイトずつ電文を投入することで、電文系列を解釈する状態遷移マシンです。

メソッド

Parse(), operator << ()

IParser& Parse(uint8_t u8b)
IParser& operator << (char_t c)

パーサーに１バイト入力します。入力のたびにパーサーの状態が変化し、パーサーの解釈が完了するとstate()がE_TWESERCMD_COMPLETEに変化し解釈完了状態となります。

state()

uint8_t state()

パーサーの状態を取得します。

operator bool(), is_complete()

operator bool()
bool is_complete()

パーサーの状態がE_TWESERCMD_COMPLETEの場合trueになります。

length()

uint16_t length()

パーサーで解釈済みのバイト列のデータ長を返します。

operator[]()

uint8_t operator[](int i)

パーサーの解釈済みのバイト列にアクセスします。

get_payload()

SmplBuf_Byte& get_payload()

パーサーの解釈済みのバイト列を格納した配列クラスSmplBuf_Byteを参照します。

reinit()

virtual void reinit()

パーサーの解釈途中の内容を破棄し、新たな解釈を始めます。

operator << ()

IStreamOut& operator << (TWE::IStreamOut& lhs, IParser& rhs)
IStreamOut& operator << (TWETERM::ITerm& lhs, IParser& rhs)

IStreamOutをベースクラスにもつストリームオブジェクトに、書式出力します。

メソッド

_u8Parse()

virtual uint8_t _u8Parse(char_t u8b) = 0

１バイト入力して解釈を進める仮想関数です。派生クラスにより実装されます。

_vOutput()

virtual inline void _vOutput(SmplBuf_Byte& bobj, IStreamOut& p) = 0

バイト配列bobjに格納されるバイト列に対応する書式をストリームpに出力する仮想関数です。派生クラスにより実装されます。

状態

TWELITE DIPに工場出荷時に書き込まれている標準アプリ(App_Twelite)のシリアルメッセージを解釈してLCD画面上に表示します。

M5Stack側のTWELITE DIPは、以下のような接続をしておきます。以下の配線はTWELITE DIPを親機設定(M1=GND)とした配線をしています。AI1-4はアナログポートがオープンになり不定な入力を防ぐためです(App_TweliteではVCCレベルを入力した場合、そのポートを未使用とする意味を持たせています）

                          TWELITE DIP
                 -01:GND              VCC:28-------M5 3V3
                 -02:D14(SCL)    (M3 ) D3:27-
  M5 GPIO16-------03:D7 (RX )    (M2 ) D2:26-
                 -04:D5 (Pw1)    (AI4) D1:25----VCC
                 -05:D18(DO1)    (AI3) A2:24----VCC
                 -06:C  (Pw2)    (AI2) D0:23----VCC
                 -07:M  (Pw3)    (AI1) A1:22----VCC
                 -08:D19(DO2)         RST:21-
                 -09:D4 (DO3)    (BPS)D17:20-
  M5 GPIO17-------10:D6 (TX )    (SDA)D15:19-
                 -11:D8 (Pw4)    (DI4)D16:18-
                 -12:D9 (DO4)    (DI3)D11:17-
           GND----13:D10(M1 )    (DI2)D13:16-
  M5 GND----------14:GND         (DI1)D12:15-

setup()

Serial2.setRxBufferSize(512);
Serial2.begin(115200, SERIAL_8N1, 16, 17);

シリアルポートの初期化を行っています。

setup_screen();

LCDスクリーンの初期化を行います。処理の内容はscreen.cにあり、ターミナル画面の初期設定を行います。

loop()

check_for_serial();

シリアルポートの入力チェックを行います。入力したデータを the_input_uart キューにいったん投入します。

process_input();

シリアルポートから入力データを処理します。ここではパーサーに文字列を投入します。パーサーによりシリアル電文が解釈できた場合は、update_screen()を呼び出しターミナル画面に文字を更新します。

check_for_refresh();

LCD画面上のターミナル画面領域を書き換えます。処理の内容はscreen.cにあります。

update_screen()

受信したパケットデータを読み取り、画面表示を更新します。

  trm << "\033[H"; // カーソルホーム
...
		if (b) trm << "\033[1;1H" // カーソルを１行目に移動
			"\033[1;30;45mﾀｲﾑCT\033[0m" "  " // ボールド、文字色、背景色設定
			"\033[1;30;45mId#\033[0m" " "
			"\033[1;30;45mｼﾘｱﾙ番号\033[0m";
		if (b) trm << "\033[3;1H" // カーソルを３行目に移動
			"\033[1;30;45m D1 \033[0m"
			" \033[1;30;45m D2 \033[0m"
			" \033[1;30;45m D3 \033[0m"
			" \033[1;30;45m D4 \033[0m";

この関数内ではエスケープシーケンスを用いて画面の表示位置などを制御しています。

		TwePacketTwelite& x = refTwePacketTwelite(spLastPacket);
		if (c) trm << "\033[2;1H"
		   << printfmt("%5d  %3d %8X", 
		      x.u16timestamp, x.u8addr_src, x.u32addr_src);
		if (c) trm << "\033[4;1H " 
			<< (x.DI1 ? "\033[31m" "●" : "\033[35m" "〇") << "\033[0m   "
			<< (x.DI2 ? "\033[32m" "●" : "\033[35m" "〇") << "\033[0m   "
			<< (x.DI3 ? "\033[33m" "●" : "\033[35m" "〇") << "\033[0m   "
			<< (x.DI4 ? "\033[34m" "●" : "\033[35m" "〇") << "\033[0m";

パケットデータはspLastPacketに格納されています。これの内容を紐解くにはretTwePacketTwelite()を呼び出します。xの値を読み出して、これに対応して画面を更新します。

パーサーは、シリアルポートからの電文を解釈し、その内容を読み取ります。

• - 電文形式を解釈します

• - 解釈した電文の内容を読み取ります

パケットデータは種別によってデータ構造が違いますが、様々な種類のパケットを一元管理するための基底クラスです。

spTwePacket はメモリ管理のためのスマートポインタです。std::shared_ptrを用いています。

TwePacketクラスは、パケットデータのパケット種別の管理を行います。また、パケットデータの解釈を行うための仮想関数parse()メソッドを定義しています。パケット特有のデータ構造に基づく解釈やデータの保存等の取り扱いは、派生クラスに実装します。

メソッド

TwePacket() - コンストラクタ

デフォルトでは、未解釈状態として E_PKT::PKT_ERROR で初期化します。

~TwePacket() - デストラクタ

get_type()

parse()

パケットデータのバイト列を与えて、パケットデータを解釈する。

派生クラスで、そのパケットに対応するデータ構造を解釈するための実装を行います。

書式を解釈して得られたデータ列は、受信したパケット情報が含まれます。ここでは、このデータ列のことをパケットデータと呼びます。

パケットデータはクラスで表現されます。TwePacketクラスのデータを解釈することで、その種別を判定し、各アプリケーションや接続ハードウェアに応じたデータ構造となります。TwePacketクラスは基底クラスでさらにパケット種別ごとの派生クラスとなります。

このオブジェクトは無線パケットのデータ量に準じたメモリ領域を消費し、また、アプリケーションでは多数のパケットを保持することも考えられます。メモリ管理を簡略化するためTwePacketをスマートポインタstd:shared_ptr<TwePacket>にて管理します。このスマートポインタをspTwePacketにtypedefしています。

以下に、TWELITE PALのパケットデータの場合のクラス関係を示します。TwePacketPalの基底クラスの一つDataPalはTWELITE PAL特有のデータを格納しています。TWELITE PALには、さらに接続されるセンサーパルによって格納すべきデータが異なります。TwePacketPalからさらにPalAmbやPalMotを生成します。例えばPalAmbには温室センサーの値や照度センサーの値が格納されます。このTwePacketPalをスマートポインタspTwePacketという形に生成するのがnewTwePacket()です。

spTwePacket型はスマートポインタですので、オブジェクトのコピー渡しによる記述を行うことで、コピーのオーバーヘッドを最小にしつつ、メモリーの管理を自動化できます。以下の例はパケットの履歴を管理する単純なクラスです。

アスキー書式の解釈を行うパーサーですが、TWESYS::TimeOutクラスをベースクラスに持つことで、タイムアウト処理を行っています。

メソッド

AsciiParser() - コンストラクタ

パーサーオブジェクトを生成します。

生成時のパラメータにmaxbuffsizを与えると、maxbuffsizをバッファサイズとして動的にメモリ確保して、パーサーを初期化します。

あらかじめ生成されたSmplBuf_Byte配列bobjを参照して、パーサーを初期化することもできます。

_u8Parse()

アスキー書式の解釈アルゴリズムを実装します。バイトの入力のたびにタイムアウトのチェックを行います。

_vOutput()

書式出力を行います。s_Output()メソッドを呼び出します。

s_Output(), vPutByte()

vPutByte()は、ストリームに対して与えられたバイトu8byteをアスキー２文字で出力します。例えば0x9Aであれば"9A"という２バイト文字になります。

s_vOutput()は、ストリームに対して、与えられたバイト配列SmplBuf_Byteのバイト列をアスキー形式で出力します。

パケットデータのバイト列を入力として、パケットの種別を判定します。また既に生成済みのオブジェクトの種別を返します。戻り値はです。

以下のパケットに対応します。

TwePacketTweliteのデータ部分。

struct DataTwelite {
		//送信元のシリアル#
		uint32_t u32addr_src;
		
		// 送信元の論理ID
		uint8_t u8addr_src;

		// 宛先の論理ID
		uint8_t u8addr_dst;

		// 送信時のタイムスタンプ
		uint16_t u16timestamp;

		// 低レイテンシ送信時のフラグ
		bool b_lowlatency_tx;

		// リピート中継回数
		uint16_t u8rpt_cnt;

		// LQI値
		uint16_t u8lqi;

		// DIの状態 (true がアクティブ Lo,GND)
		bool DI1, DI2, DI3, DI4;
		// DIの状態ビットマップ (LSBから順にDI1,2,3,4)
		uint8_t DI_mask;

		// DIアクティブならtrue (過去にアクティブになったことがある)
		bool DI1_active, DI2_active, DI3_active, DI4_active;
		// DIのアクティブビットマップ(LSBから順にDI1,2,3,4)
		uint8_t DI_active_mask;

		// モジュールの電源電圧[mV]
		uint16_t u16Volt;

		// AD値 [mV]
		uint16_t u16Adc1, u16Adc2, u16Adc3, u16Adc4;
		// ADがアクティブ（有効）なら 1 になるビットマップ (LSBから順にAD1,2,3,4)
		uint8_t Adc_active_mask;
};

本関数はspTwePacketオブジェクトをTwePacket&として参照します。

TwePacket& refTwePacket(spTwePacket& p)

//例
  auto&& pkt = newTwePacket(p, len); // パケットの生成
  
  if (refTwePacket(pkt).get_type() == E_PKT::PKT_TWELITE) {
    // App_Twelite の処理
  }

パケットデータのバイト列を入力として、パケット種別の判定と、種別に応じたspTwePacketオブジェクトを生成します。

spTwePacket newTwePacket(
		uint8_t* p,
		uint8_t u8len,
		E_PKT eType = E_PKT::PKT_ERROR)

spTwePacket newTwePacket(
		TWEUTILS::SmplBuf_Byte& sbuff,
		E_PKT eType = E_PKT::PKT_ERROR)

事前にidentify_packet_type()を用いてパケットの種別E_PKTが特定できている場合はeTypeを与えます。

戻り値はspTwePacketです。

TwePacketTweliteクラスは、標準アプリApp_Tweliteの0x81コマンドを解釈したものです。

class TwePacketTwelite : public TwePacket, public DataTwelite { ... };

パケットデータ内の諸情報はparse()実行後にDataTweliteに格納されます。

spTwePacketからの参照

TwePacketTwelite& refTwePacketTwelite(spTwePacket& p)

spTwePacketオブジェクトからTwePacketTweliteオブジェクトを参照します。spTwePacketにTwePacketTwelite以外が格納されている場合は、未解釈のオブジェクトを戻します。

実行例

if (parse_ascii) { // アスキー形式のパーサーの解釈完了
  if (identify_packet_type(parse_ascii.get_payload()) == E_PKT::PKT_TWELITE) {
    auto&& pkt = newTwePacket(parse_ascii.get_payload(), E_PKT::PKT_TWELITE);
    
    if (pkt == E_PKT::PKT_TWELITE) { // パケット解釈成功時
      auto&& x = refTwePacketTwelite(pkt);
      
  		the_screen // LCDスクリーン上のターミナルに情報を表示
  				<< printfmt(":Lq=%d:Ad=%08X", x.u8lqi, x.u32addr_src)
  				<< printfmt(":ID=%02X", x.u8addr_src)
  				<< printfmt(":DI=%04b", x.DI_mask)
  				;
    }
  }
}

PALは接続されるセンサーなどによってパケットデータ構造が異なりますが、DataPalでは共通部のデータ構造を保持します。

struct DataPal {
	uint8_t u8lqi;        // LQI値

	uint32_t u32addr_rpt; // 中継器のアドレス

	uint32_t u32addr_src; // 送信元のアドレス
	uint8_t u8addr_src;   // 送信元の論理アドレス

	uint16_t u16seq;      // シーケンス番号

	E_PAL_PCB u8palpcb;		// PAL基板の種別
	uint8_t u8palpcb_rev;	// PAL基板のレビジョン
	uint8_t u8sensors;		// データに含まれるセンサーデータの数 (MSB=1はエラー)
	uint8_t u8snsdatalen; // センサーデータ長(バイト数), MSB=1は動的確保

	uint8_t au8snsdata[32]; // センサーデータ（解釈前の生データ）
	std::unique_ptr<uint8_t[]> uptr_snsdata; // センサーデータ（動的確保）
};

PALのパケットデータ構造は大まかに２つのブロックからなり、全てのPAL共通部と個別のデータ部になります。個別のデータ部は、パケットの解釈を行わずそのまま格納しています。取り扱いを単純化するため32バイトを超えるデータは動的に確保するuptr_snsdataに格納します。

個別のデータ部は、PalBaseをベースクラスに持つ構造体に格納されます。この構造体は、TwePacketPalに定義されるジェネレータ関数により生成されます。

TwePacketPalクラスは、TWELITE PALのパケットデータを解釈したものです。このクラスはTWELITE PAL（センサーデータなど上り方向）共通に取り扱います。

class TwePacketPal : public TwePacket, public DataPal { ... };

PAL共通データはDataPalに定義されています。

PALの各センサー基板特有のデータを取り出すためのジェネレータ関数を用意しています。

spTwePacketからの参照

TwePacketPal& refTwePacketPal(spTwePacket& p)

spTwePacketオブジェクトからTwePacketPalオブジェクトを参照します。spTwePacketにTwePacketPal以外が格納されている場合は、未解釈のオブジェクトを戻します。

実行例

if (parse_ascii) { // アスキー形式のパーサーの解釈完了
  if (identify_packet_type(parse_ascii.get_payload()) == E_PKT::PKT_PAL) {
    auto&& pkt = newTwePacket(parse_ascii.get_payload(), E_PKT::PKT_PAL);
    
    if (pkt == E_PKT::PKT_PAL) { // パケット解釈成功時
      auto&& pal = refTwePacketPal(pkt);
      
      // 開閉センサーパル
      if (pal.u8palpcb == E_PAL_PCB::MAG) {
        PalMag mag = pal.get_PalMag();
        if (mag.u8MagStat == 0) {
          // OPEN
        } else {
          // CLOSE
        }
      }
    }
  }
}

ジェネレータ関数

センサーPALの各種データを取り出すためのジェネレータ関数です。

get_PalMag()

PalMag get_PalMag()

開閉センサーパルのデータPalMagを取り出します。

get_PalAmb()

PalAmb get_PalAmb()

環境センサーパルのデータPalAmbを取り出します。

get_PalMot()

PalMot get_PalMot()

動作センサーパルのデータPalMotを取り出します。

本ライブラリのターミナル（コンソール）は、文字列ベースの画面を構成することを目的としてます。

以下に設計時の考慮事項を記載します。

• 固定幅の画面構成を行うこと

• 日本語の表示が可能であること

• ソースコード中に直接日本語文字列を含められるようにすること

  • UTF-8でソースコードを記述する前提とする

  • 内部処理をUnicodeとすること

  • UTF-8デコードが出来るようにすること

• 旧来のキャラクター型のインタフェースを実装できるよう、いくつかのエスケープシーケンスを実装しておくこと

  • ただしANSIエスケープシーケンスの完全な互換性を目的とはしない

• 文字色、背景色、太字といった表示属性に対応すること

• カーソルを表示・非表示にできること

• 画面の順方向のスクロールに対応すること

• カラム数を超えて文字列を出力した場合は、折り返しを行えること

  • 右端カラムへの文字出力を行った場合、その時点では折り返しを行わないようにすること

    • 上記を実装は、折り返し処理の実装より優先すること

• 複数のターミナル表示を画面上に同時に表示できること

• 毎回全画面書き換えといったような描画パフォーマンスの悪い実装でないこと

  • 変更がある行のみを書き換える行単位の描画を行うようにした

• フォントを選択できること

  • 配布可能なフォントをライブラリ内に同梱しておくこと

  • より大きな文字を表示するため、倍角表示に対応すること

本ライブラリのターミナルは、大まかに分けて２要素から構成されます。

PALの各センサーのデータ構造体はすべてPalBaseを継承します。センサーデータの格納状況u32StoredMaskとモジュール電源電圧u16Voltの情報が含まれます。

派生構造体に定義されるSTORE_COMP_MASKとu32StoreMaskが一致すれば、全てのセンサーのデータが適切に解釈され、格納されていることになります。

※ 各サンプルの連続性を確認するには、パケットのシーケンス番号の抜けが無いことを確認してください。

下記のPAL基板に対応します。

namesace TWETERMはターミナル（コンソール）画面を実装するためのクラスや関数などをまとめています。

基本的なクラス構造は以下のようになっています。クラスITermではターミナルの文字列バッファとその処理、TWETerm_M5_ConsoleクラスはITermの文字列描画部分を実装したものです。IStreamOutはITerm派生クラスオブジェクトが文字列をターミナルに投入するための基本的な手続きを提供しています。

    [IStreamOut]
         ↑
      [ITerm]
         ↑
 [TWETerm_M5_Console]

ITerm型のターミナルオブジェクトに対して、<<演算子を用いてターミナル属性を指定するヘルパークラス。

上記の例では、出力ターミナルをtrmに対して、文字色を赤で太字にしてmsgを出力し、属性をクリアします。

TermAttr() - コンストラクタ

attrをパラメータとします。attrは後述のGChar::tAttr 定数一覧で指定します。

指定は以下の組み合わせになります。

• TERM_ATTR_OFF (すべての属性のクリア)

• 以下の論理和

  • TERM_BOLD

  • TERM_REVERSE

  • 文字色のいずれか

  • 背景色のいずれか

GChar::tAttr 定数

色設定以外の属性

文字色

背景色

M5Stack の 320x240 LCD 用のターミナルの実装です。ITermを実装しています。

本クラスはnamespace TWEARD内に定義されます。

メソッド

TWETerm_M5_Console - コンストラクタ

TWETerm_M5_Console(
			uint8_t u8c, uint8_t u8l,
			Rect drawArea, M5Stack& _M5)

TWETerm_M5_Console(
			uint8_t u8c, uint8_t u8l,
			TWETERM::SimpBuf_GChar* pAryLines, TWETERM::GChar* pBuff,
			Rect drawArea, M5Stack& _M5)

ITermのコンストラクタにdrawAreaと_M5のパラメータが追加されています。

drawAreaは、LCD内のターミナル描画エリアを決めます。Rect構造体で指定しx,y,w,hを指定します。(x,y)は領域の左上の座標、(w,h)は領域の幅と高さです。

_M5は、M5Stackのグローバルインスタンス M5を指定します。

例：

TWETerm_M5_Console the_screen(64, 20, { 0, 16, 320, 192 }, M5);

カラム最大値を64、行数の最大値を20、左上座標を (0, 16)、領域サイズを (320, 192) として the_screen オブジェクトを構築します。

メソッド

refresh()

ITerm::refresh()の実装です。この関数により画面の描画を行います。loop()関数内で定期的に呼び出します。

本実装では、パフォーマンスの向上のため、原則として描画変更の必要にある行のみを上書きします。画面全領域を再描画したい場合はforce_refresh()メソッドを呼び出します。

以下の例では32msごとに描画を行います。

void loop() {
		static uint32_t u32mills;

		uint32_t u32now = millis();
		if (u32now - u32mills > 32) {
			the_screen.refresh();

			u32mills = u32now;
		}
}

set_font()

void set_font(uint8_t u8id, uint8_t u8col_request = 0, uint8_t u8row_request = 0)

フォントを指定します。

u8idはフォントIDを指定します。

u8col_requestは、設定したいカラム数を指定します。指定した数値が領域サイズに対して大きい場合は指定領域に入るように値が丸められます。0を指定した場合は、領域サイズから計算できる最大のカラム数に設定されます。

u8row_requestは、設定したい行数を指定します。指定した数値が領域サイズに対して大きい場合は指定領域に入るように値が丸められます。0を指定した場合は、領域サイズから計算できる最大の行数に設定されます。

font_width(), font_height(), font_id()

uint8_t font_id()
uint8_t font_width()
uint8_t font_height()

font_id()は、指定したフォントのIDを返します。

font_width()は、指定したフォントの幅をピクセル数で返します。ダブル幅のピクセル数は、この値の２倍になります。

font_height()は、指定したフォントの高さをピクセル数で返します。

set_color()

void set_color(uint16_t color, uint16_t bgcolor = 0)

ターミナルの文字色と背景色を指定します。

colorは文字色を指定します。

bgcolorは背景色を指定します。

uint16_t c = color565(255, 127, 0); // R:255, G:127, B:0

set_color_table()

void set_color_table(const uint16_t* ptbl)

ターミナルで使用できる８色のテーブルを指定します。ptblはuint16_t型の配列で８つの要素が必要です。

例

static const uint16_t COLTBL_MAIN[8] = {
	BLACK,
	RED,
	GREEN,
	YELLOW,
	color565(127, 127, 255), // BLUE,
	color565(255, 0, 142), // MAGENTA,
	CYAN,
	ALMOST_WHITE
};

the_screen.set_color_table(COLTBL_MAIN);

上記の例では青とマゼンダの色調を変えたテーブルを指定し、ターミナルオブジェクト the_screenに指定しています。

ユーティリティ関数

color565()

constexpr uint16_t color565(uint8_t r, uint8_t g, uint8_t b)

r, g, b を指定して、565形式の色コードを生成します。

ターミナル（コンソール）の基底クラスで、画面上の文字列を管理する。このクラスは、実際の画面描画についての手続きは含まれず、このクラスを継承したサブクラスによって画面描画を実装します。

メソッド

ITerm() - コンストラクタ

ITerm(uint8_t u8c, uint8_t u8l)
ITerm(uint8_t u8c, uint8_t u8l, SimpBuf_GChar* pAryLines, GChar* pBuff)

カラム数u8cと行数u8lを指定して、ターミナルを構築する。カラム数と行数はターミナルで管理できる最大の値を指定する。ターミナルのサイズ変更を行った場合でも各々の最大の値を超える変更は行われない。

pAryLinesとpBuffを指定する場合は、ITerm内でのメモリ確保は行われず、外部で確保済みの配列を利用する。

// 静的メモリ確保例
const uint8_t U8COL = 64;
const uint8_t U8LINE = 20;
static TWETERM::GChar screen_buf[U8COL * U8LINE];   // pBuff
static TWETERM::SimpBuf_GChar screen_lines[U8LINE]; // pAryLines

~ITrem() - デストラクタ

virtual ~ITerm()

動的にメモリを確保した場合は、そのメモリ領域を破棄します。

clear(), home(), clear_screen()

void clear()
void home()
void clear_screen()

clear()は画面バッファのクリア、home()はカーソル位置をホームポジションに移動、clear_screen()は両者を実行します。

refresh(), force_refresh()

virtual void refresh() = 0
void force_refresh()

サブクラスにより実装される画面更新描画のためのメソッドです。描画方法は２種類あり、メンバー変数u32Dirtyに定義されるビットマスクに対応した行のみを再描画するものと、force_refresh()メソッドによる画面全体を再描画するものがあります。

画面全体の再描画では、いったん背景を背景色で塗りつぶしてから再描画します。初回の描画ではforce_refresh()を行うようにしてください。

write()

ITerm& write(wchar_t c)
ITerm& write(char_t c)

ターミナルに１文字書き出します。カーソル位置に文字を書き出します。16bit wchar_t型のUnicodeを渡します。

char_t (char) 型のパラメータを渡した場合は、入力をUTF-8として取り扱います。例えば0x7F までのASCII文字はそのままwrite(wchar_t)が呼び出され、３バイトのUTF-8エンコードされた日本語文字は、連続して３バイトを投入した時点でwrite(wchar_t)が呼び出されます。

get_height(), get_width()

uint8_t get_height() // 行数
uint8_t get_width()  // カラム数

ターミナルの行数、カラム数を返す。

operator <<

ITerm& operator << (const char *s)
TWE::IStreamOut& operator << (TWE::IStreamSpecial& sc)
TWE::IStreamOut& operator << (ITerm& t, char_t c)
TWE::IStreamOut& operator << (ITerm& t, wchar_t c)
TWE::IStreamOut& operator << (ITerm& t, int i)
TWE::IStreamOut& operator << (ITerm& t, TermAttr a)
TWE::IStreamOut& operator << (TWE::IStreamOut& t, TermAttr a)

<<演算子を用いてターミナルに文字列を書き出します。

メソッド (サブクラス実装用)

エスケープシーケンスは ESC 文字 '\033' で始まり何文字かで完結する制御コードです。

本ライブラリが動作するプログラム上や、シリアルポートの先にあるマイコンから制御文字をターミナルに投入することで、様々な画面制御（画面のクリア、カーソルの移動、色などの表示属性の変更）を行うことが出来ます。

以下に対応するエスケープシーケンスを記述します。表中の ESC はエスケープ文字 '\033'、イタリックの n や m は数字の入力です。

フォントジェネレータ関数は、収録フォントごとに定義されています。関数パラメータは共通で、以下のようになります。

上記は東雲フォント16ドット版（常用漢字収録）のジェネレータの例です。

idは、ユーザが指定するフォントID。

line_spaceはフォントの行間スペースをピクセル数で指定します。

char_spaceは文字間スペースでピクセルで指定します。文字間スペースはシングル幅のフォントの指定です。ダブル幅のフォントの場合は倍になります。

u32Optは、フォントのオプションを指定します。オプションはU32_OPT_FONT_TATEBAIとU32_OPT_FONT_YOKOBAIがあり、論理和で指定します。

フォントジェネレータの戻り値はFontDef&になっています。この戻り値はライブラリ内部のフォント管理テーブルに生成されたオブジェクトへの参照です。既に登録済みのIDであるばあいは、そのIDに対して上書きを行います。登録できなかった場合は.is_default()メソッドがtrueになるデフォルトフォントが返されます。

フォントをスクリーン上に描画します。

以下の例では、Bボタンを押すたびに、事前に生成したフォントID=10のフォントを用いて固定の文字列を描画します。

関数定義

fontを用い、左上座標(x,y)に、文字色fg、背景色bg、オプションoptで文字を描画します。

uint16_t cをパラメターとして与えた場合は、Unicode c に対応する文字を１文字描画します。

const char *sをパラメータとして与えた場合は、sをUTF-8としてデコードし、文字列として出力します。

const uint16_t* sをパラメータとして与えた場合は、Unicode文字列として描画します。

optはオプションのビットマップです。以下の指定が可能です。

• 0x01 - 太字指定

• 0x02 - カーソルの描画

戻り値は、描画が行われればX(幅)方向に描画したピクセル数を返し、エラーなどが発生したときは0を返します。

実装について

実装時では以下のM5StackのAPIを利用しています。

• M5.Lcd.startWrite()

• M5.Lcd.setWindow()

• M5.Lcd.endWrite()

• tft_Write_16()

によりフォント生成したクラスオブジェクトを参照します。

関数定義

idにはフォント生成時に指定したフォントIDを指定します。

戻り値は で、ライブラリ内のフォント管理配列内に格納されたオブジェクトへの参照です。

idに0を指定すると、フォントID=0のデフォルトフォントを戻します。存在しないIDを指定した場合も、どうようにデフォルトフォントを戻します。FontDefオブジェクトがデフォルトフォントかどうかはメソッド.is_default()により判定できます。

フォント定義と関連する手続きをまとめたクラスです。

このクラスオブジェクトはフォントジェネレータによりライブラリ内部で生成・管理され、ユーザがコンストラクタを用いて直接オブジェクトを生成することはありません。

メソッド（ユーザ利用）

get_width()

パラメータを省略した場合は、フォントのシングル幅文字の幅を返します。この値にはフォント生成時に指定した文字間スペースも含まれます。

wcを指定した場合は、Unicode wcに対応するフォントの幅を返します。日本語などダブル幅のフォントの場合は、シングル幅の２倍の値が戻ります。

get_height()

フォントの高さを返します。この値にはフォント生成時に指定した行間スペースも含まれます。

is_default()

デフォルトフォントのオブジェクトである場合 true を返します。

get_font_code()

フォントIDを取得します。

メソッド（内部利用）

find_font_index()

Unicode c に対応する、ダブル幅フォント定義配列インデックスを検索します。

戻り値は、字形データが存在する場合は、インデックス配列のインデックス（データ配列のインデックスが計算できる）、存在しない場合は-1を返します。

フォント定義は、インデックス配列、データ配列の２つから構成されます。インデックス配列の各値は昇順に並んだ Unicode になっていて、データ配列のインデックスに対応しています。

以下の例ではインデックス配列の IDX=829 が U+5a2f で "娯" という文字です。データ配列の対応する番地を参照すれば、この字形データが格納されています。

インデックス配列内の値は昇順に並ぶよう構成した目的は、本関数で実装されている二分探索を利用するためです。

本クラスは namespace TWE 内に定義されています。

出力ストリームの基底クラスで、以下のメソッドが定義されており、１バイトの出力、改行文字など特殊クラスを受け付けるためのメソッドが定義されています。

operator () はchar_t型の１文字を出力するための仮想関数です。write_w()はwchar_t型の出力に対応します。

ストリームへの出力は<<演算子を用います。最終的には上記の出力用の関数が呼び出されます。

以下の例はITermクラスでの実装例です。

operator <<

operator << の右オペランドとして以下の型に対応します。

IStreamSpecial

特殊な文字列などを指定するためのオブジェクトを定義するための基底クラスです。

派生クラスとして CR LF (0x0d 0x0a) を出力する IStream_endl が定義されています。

オブジェクトcrlfは以下のように使用します。

namespace TWEFONT には、フォントの定義やフォント描画のための手続きをまとめています。

フォントの生成

フォントはFontDefクラスにより管理されます。フォントごとに用意されるFontDefクラスオブジェクトのジェネレータ関数により生成され、ライブラリ内部で生成時に指定したフォントIDと紐づけて管理されます。フォントは最大７つまで定義できます。フォント作成時に字間・行間・倍角を指定することができます。同じフォントに対して複数のフォントIDの登録が可能です。

下記の例では、フォントID 10 に16ドットの東雲フォント（縦倍角・横倍角指定）を、フォントIDを11に同じフォントですが倍角指定なし、行間を１ピクセルとしたフォント定義を行います。

コンパイル時に、ジェネレータ関数createFont???()を呼び出されたフォントのデータがリンクされます。

フォントデータについて

本ライブラリには、作者が事実上パブリックドメイン（著作権等取扱はソースヘッダに含まれるクレジットを参照ください）を宣言しているフォントをいくつか含めています。

本ライブラリに含めるにあたって、以下の調整を行っています。

• 大本がBDF形式を変換し、描画ルーチンに適したデータ構造とした

• これらフォントをUnicodeとして取り扱うための参照テーブルを用意した

• latin1補助文字 U+00A0～u+00FFについて、フォント定義があるものについては収録した

• JIS X201 半角カナ U+FF61～U+FF9F について、フォント定義があるものについては収録した

• 常用漢字（2645 文字）のフォントデータと、全収録（東雲フォントのみ、一部未収録字形があります）を用意した

東雲フォント (12,14,16ドット)

12,14,16ドット版をライブラリに含めています。

常用漢字のみのジェネレータ (createFontShinonome12(), createFontShinonome12() , createFontShinonome16())または、全収録のジェネレータ (createFontShinonome12_full()) ,createFontShinonome14_full() ,createFontShinonome16_full() )を呼び出します。

MP+フォント (10ドット, 12ドット)

ジェネレータ createFontMP10()または createFontMP12() を呼び出します。

8x6 LCD フォント

ジェネレータ createFontLcd8x6() を呼び出します。

latin拡張文字や日本語フォントは含まれません。

このフォントはいずれかのジェネレータ関数createFont???()が呼び出されたときに、デフォルトとしてフォントID=0に登録されます。

フォントIDについて

フォントIDは作成したフォントごとに割り当てられます。

IDは 0..32 の値を指定可能ですが、ユーザが登録できるのは 1..32 で最大７フォント登録できます。

ID=0 のフォントは 8x6 LCD フォントに割り当てられます。

フォント情報の取得

ターミナルでの使用

フォントの描画について