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

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

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

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

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

/* 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を添付したソフトウェアは、商用・非商用にかかわりなく、モノワイヤレス株式会社の製品上で利用しなければなりません

• src/twesettings には MW-SLA と MW-OSSLA のデュアルライセンスが適用されます。

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

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

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

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

0.8.9 - 2020-05-29

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

• ウインドウアイコンの追加

• BINファイル一覧画面での最大リスト数の制約を緩和 (win/linux/mac)

• Glancerビューアの追加

• 解説文面等の調整

• コンソール画面の描画の調整

• ファーム書き込み後の移動先画面(インタラクティブモードかターミナルか）の設定が動作していなかった

• Alt(or Cmd)+W の割り当てを変更

• その他不具合の修正

0.8.6 - 2020-04-27

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

• TWELITE STAGE (MWSDK) 2020-04 linux版に収録

0.8.5 - 2020-04-24

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

• TWELITE STAGE (MWSDK) 2020-04 に収録

• TWELITE STAGE アプリを追加

• Windows10, macOS, Linux 用のビルド対応

• 設定ライブラリ twesettings を追加

0.4.2 - 2020-02-17

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

初期バージョン

Windows, macOS, Linux

MONOSTICK または TWELITE-R と TWELITE モジュールを接続し、必要に応じて各OS向けのデバイスドライバの設定を行います。

参考: TWELITE STAGE の解説

ESP32 (M5Stack)

TWELITE DIPとの接続例です。シリアルポート(UART)のTX,RXのみのシンプルな接続です。この接続では TWELITE 上のファームウェアの書き込みなどが行えません。

[M5Stack 15P]

    GPIO03
    GPIO01
    GPIO16 --- TWELITE DIO6/UART0 TX (TWELITE DIP #10)
    GPIO17 --- TWELITE DIO7/UART0 RX (TWELITE DIP #3)
    GPIO02
    GPIO05
    GPIO25
    GPIO26
    GPIO35
    GPIO36
       RST
       BAT
       3V3 --- TWELITE VCC (TWELITE DIP #28)
        5V
       GND --- TWELITE GND (TWELITE DIP #1,14)

以下の配線をすることで PGM/RESET/SET ピンが接続されます。TWELITE STAGEアプリケーションを利用する場合は、下記の配線を行ってください。

[M5Stack 15P]

    GPIO03
    GPIO01
    GPIO16 --- TWELITE DIO6/UART0 TX (TWELITE DIP #10)
    GPIO17 --- TWELITE DIO7/UART0 RX (TWELITE DIP #3)
    GPIO02 --- TWELITE PGM   (TWELITE DIP #7)
    GPIO05 --- TWELITE DIO12 (TWELITE DIP #15)
    GPIO25
    GPIO26 --- TWELITE RESET (TWELITE DIP #21)
    GPIO35
    GPIO36
       RST
       BAT
       3V3 --- TWELITE VCC (TWELITE DIP #28)
        5V
       GND --- TWELITE GND (TWELITE DIP #1,14)

ESP32(M5Stack)

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

M5Stack Library - https://github.com/m5stack/M5Stack

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

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

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

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

外部ライブラリ

• PS2Keyboard - http://www.pjrc.com/teensy/td_libs_PS2Keyboard.html esp32/PS2Keyboard.7z をライブラリディレクトリに展開してください。ビルド時に必要になります。 PS2Keyboard プロジェクトの成果物に対して 1) 日本語レイアウトのキーボード対応 2) カーソルキー等の取り扱いの微調整を実施しています。修正内容はソースコードを参照ください。

Windows10

Windows10ではVisual Studio 2019でビルドを行っています。また MingW32 用のビルド定義も含めています。

MingW64

以下が必要になります。

• make

• gcc9 (gcc-9, g++-9)

macOS

以下が必要になります。

• make XCodeに付随します。OS バージョンにもよりますが、ターミナルで make と入力すればインストーラーが起動します。

• gcc9 (gcc-9, g++-9) homebrew のパッケージをダウンロードして利用します。

Linux

以下が必要になります。

• gcc9 (gcc-9, g++-9)

• SDL2 開発者向けライブラリ (libsdl2-dev) SDL2 のライブラリやヘッダファイルは、ソースパッケージに添付していますが、依存ライブラリのリンクに必要です。

ビルド方法

M5Stack

以下を参考にしてください。

M5Stack Library - https://github.com/m5stack/M5Stack

Windows Visual Studio

1. プロジェクト MWM5.sln を開きます。

2. Sketch＞TWELITE_Stage をスタートアッププロジェクトにします。 必須ではありませんが、デバッガを起動する際などにこのプロジェクトが選択されます。

3. Debug/Release のいずれかを選択します。

4. 32bit/64bit のいずれかを選択します。

5. Sketch＞TWELITE_Stage を右クリックしてビルドを選択します。

6. 実行形式は msc\Release msc\Debug などのディレクトリに格納されます。

macOS, Linux, Windows (MingW64)

1. コマンドプロンプト、シェルを開きます。

2. make, gcc-9, g++-9 が動作することを確認します。

3. {ソースコードを展開したディレクトリ}/examples/{ビルドしたいプロジェクト:例 TWELITE_Stage}/build に移動します。

4. make を実行します。

make オプション

make ファイルについて

make のルール本体は {ソースコードを展開したディレクトリ}/mkfiles 以下に格納しています。

デバッグについて

VSCode用のTWELITE STAGE 用のデバッガ起動定義(.vscode/launch.json)を含めています。環境に合わせて利用ください。

参考OS X用の定義

{
    "name": "(lldb/mac) TWELITE_Stage",
    "type": "cppdbg",
    "request": "launch",
    "program": "${workspaceFolder}/examples/TWELITE_Stage/build/TWELITE_Stage-debug.command",
    "args": [],
    "stopAtEntry": true,
    // "cwd": "${workspaceFolder}",
    "cwd": "${workspaceFolder}/../MWSDK",
    "environment": [],
    "externalConsole": false,
    "MIMode": "lldb"
}

• stopAtEntryは、main()の先頭で停止する設定で false でも構わない。

• externalConsoleは、falseでないと起動しない。

• cwdは、TWELITE STAGEの場合 MWSDKディレクトリを指定する。

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の値を読み出して、これに対応して画面を更新します。

本ライブラリMWM5は、M5StackとTWELITE をシリアル(UART)接続して、M5Stack上でTWELITEを利用することを目的としています。またライブラリを活用した TWELITE STAGE (開発環境) のソースコードも含まれています。

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

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

• Windows/Linux/macOS向けウインドウ描画ライブラリ

• TWELITE STAGE (TWELITE 開発・評価環境)

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の表示行のみを更新します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

メソッド

Parse(), operator << ()

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

state()

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

operator bool(), is_complete()

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

length()

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

operator[]()

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

get_payload()

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

reinit()

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

operator << ()

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

メソッド

_u8Parse()

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

_vOutput()

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

状態

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

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

アスキー形式

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

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

:00A01301FF123456B1[CR][LF]

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

:00A01301FF123456X

定義

AsciiParser の使用方法

オブジェクトの生成

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

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

バイト列の解釈

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

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

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

データ列の取り出し

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

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

パケットの生成

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

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

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

PALパケットの解釈

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

PALボード種別解釈

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

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

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

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

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

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

パケットデータはTwePacketクラスで表現されます。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] ←(生成)- newTwePacket()
          ◆ 
          ｜(shared_ptr)
          ｜
      [TwePacket]    [DataPal]
              ↑        ↑
            [TwePacketPal] -(生成)-> [PalAmb], [PalMot], ...

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

struct _pkt_hist {
	spTwePacket _pkt[16]; // パケットの履歴
	int _i;

	_pkt_hist() : _i(-1), _pkt{} {}
	void add_entry(spTwePacket p) { _pkt[++_i & 0xF] = p; }
	spTwePacket get_entry(int i) { return _pkt[(i + _i) & 0xF]; }
} pkt_hist;

void loop() {
  spTwePacket pkt, pkt_last;
  
  // 新たなパケットオブジェクト
  pkt = newTwePacket(p, len);
  pkt_hist.add_entry(pkt); // 履歴に保存する

  // ひとつ前のパケットオブジェクト
  pkt_last = pkt_hist.get_entry(-1);
}

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

メソッド

AsciiParser() - コンストラクタ

AsciiParser(size_t maxbuffsiz)
AsciiParser(SmplBuf_Byte& bobj)

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

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

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

_u8Parse()

uint8_t AsciiParser::_u8Parse(char_t u8byte)

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

_vOutput()

void AsciiParser::_vOutput(TWEUTILS::SmplBuf_Byte& bobj, TWE::IStreamOut& p)

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

s_Output(), vPutByte()

static void vPutByte(uint8_t u8byte, uint8_t* pu8lrc, TWE::IStreamOut& p)
static void s_vOutput(TWEUTILS::SmplBuf_Byte& bobj, TWE::IStreamOut& p)

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

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

パケットデータのバイト列を入力として、パケット種別の判定と、種別に応じた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です。

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

E_PKT identify_packet_type(uint8_t* p, uint8_t u8len)
E_PKT identify_packet_type(SmplBuf_Byte& sbuff)

E_PKT identify_packet_type(spTwePacket& sp)

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

class TwePacket;
typedef std::shared_ptr<TwePacket> spTwePacket;

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

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

メソッド

TwePacket() - コンストラクタ

TwePacket(E_PKT ptyp = E_PKT::PKT_ERROR)

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

~TwePacket() - デストラクタ

virtual ~TwePacket()

get_type()

E_PKT get_type()

パケットの種別をE_PKT型で返します。

parse()

virtual E_PKT parse(uint8_t* p, uint8_t u8len)

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

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

戻り値は E_PKT型 で、成功時は解釈されたパケット種別を、エラー時に E_PKT::PKT_ERROR を返します。

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

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

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

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

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

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

spTwePacketからの参照

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

実行例

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

TwePacketTweliteのデータ部分。

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

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

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

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

spTwePacketからの参照

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

実行例

ジェネレータ関数

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

get_PalMag()

get_PalAmb()

get_PalMot()

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

	struct PalBase {
		uint32_t u32StoredMask;
		uint16_t u16Volt;
	};

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

struct PalMot : public PalBase {
	const uint8_t U8VARS_CT = 17; // センサー数
	const uint32_t STORE_COMP_MASK = 3; // 電圧と加速度サンプル１あればコンプとする

	uint8_t u8samples; // 格納サンプル数
	int16_t i16X[16];  // X軸 (ミリG)
	int16_t i16Y[16];  // Y軸
	int16_t i16Z[16];  // Z軸
};

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

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

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

    [IStreamOut]
         ↑
      [ITerm]
         ↑
 [TWETerm_M5_Console]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• ターミナル画面上の文字列を管理するクラスや関数をまとめた TWETERM

• フォントの管理と描画に関連するクラスや関数をまとめた TWEFONT

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

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

メソッド（ユーザ利用）

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 で "娯" という文字です。データ配列の対応する番地を参照すれば、この字形データが格納されています。

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

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

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

TermAttr() - コンストラクタ

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

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

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

• 以下の論理和

  • TERM_BOLD

  • TERM_REVERSE

  • 文字色のいずれか

  • 背景色のいずれか

GChar::tAttr 定数

色設定以外の属性

文字色

背景色

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

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

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

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 フォントに割り当てられます。

フォント情報の取得

ターミナルでの使用

フォントの描画について

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

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

メソッド

TWETerm_M5_Console - コンストラクタ

にdrawAreaと_M5のパラメータが追加されています。

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

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

例：

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

メソッド

refresh()

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

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

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

set_font()

フォントを指定します。

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

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

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

font_width(), font_height(), font_id()

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

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

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

set_color()

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

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

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

set_color_table()

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

例

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

ユーティリティ関数

color565()

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

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

メソッド

ITerm() - コンストラクタ

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

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

~ITrem() - デストラクタ

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

clear(), home(), clear_screen()

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

refresh(), force_refresh()

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

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

write()

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

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

get_height(), get_width()

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

operator <<

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

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