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)

Raspberry Pi 3B

Raspberry Pi では /dev/srial0 (TWELITE STAGEのマニュアル参照) を選択した場合（raspi-config などの設定等により異なる場合があります）、以下の配線にてシリアルポートの経由でTWELITE無線マイコンとのUART接続を行います。

 [TWELITE]               [RaspberryPi]
  GND  ------------------ Gound (#6,#9,#14,#20,#25,#30,#34,#39のいずれか)
  TXD(DIO6,DIP#10) ------ GPIO15/UART0 RXD (#10)
  PRG(SPIMISO,DIP#7) ---- GPIO23 (#16)
  RXD(DIO7,DIP#3) ------- GPIO14/UART0 TXD (#8)
  RST(RESETN,DIP#21) ---- GPIO22 (#15)
  VCC  ------------------ 3V3 (#1,#17のいずれか)
  SET(DIO12,DIP#15) ----- GPIO12 (#32)

• TWELITE, RaspberryPi ともに製造元のマニュアルを参照ください。

• DIP# は TWELITE DIP のピン番号です。

• 上記配線は TWELITE 無線マイコンモジュールが安定稼働することを保証するものではありません。

1.0.8 - 2021-09-09 (MWSDK2021_09)

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

ライブラリ

汎用ライブラリとしての変更点を記載します。TWELITE_StageについてはTWELITE STAGEアプリを参照してください。

[1.0.8]

• ボーレート設定のためのインタフェースを追加 (set_baud_app())

• sdl_main.c でメインループの終了時に１秒後にスレッドから_exit()を強制するようにした

• 環境変数の内部設定を強化 (ビルド実行のためのMWSDKのディレクトリなど)

• TWELITE_Stage 関連の機能修正

[1.0.6]

• RaspberryPi 用のビルド整備を行った

[1.0.5]

• シリアルポートについて raspberry pi では /dev/serial0 を利用できるようにした

• シリアルポートのボーレートを 115200bps から変更できるようにした

• シリアルポートについて専用設定していないFTDIデバイス(FT232,FT230)を開けるようにした

• シリアルポートについて Windows の COM ポートを調べる手続き(_query_extra_device_info()を追加した

1.0.3 - 2020-12-03 (MWSDK2020_12)

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

TWELITE STAGE アプリの変更点

https://stage.twelite.info/v/1.0/changes

ライブラリ

汎用ライブラリとしての変更点を記載します。TWELITE_StageについてはTWELITE STAGEアプリを参照してください。

[1.0.3]

• Apple Silicon 対応

  • osx/sersrv_ftdiを作成、シリアルポートの入出力を標準入出力経由で行う。FTDI D2XX arm64用ライブラリが現時点で存在しないため、このコマンドをx86_64としてビルドしTWELITE_Stageアプリケーションから開くようにした

  • TweCmdPipeInOut(twe_file.cpp, hpp)クラスの追加。コマンドの標準入出力を処理する

• Windows, macOS の SDL2 ライブラリをビルド。バージョン2.0.12、スタティックライブラリのみ

[1.0.2]

• シリアルポートの再オープン処理をファームウェア書き換え前などに挿入しするため Serial2.reopen() を追加

• ファームウェア書き換え時のベリファイに対応(twe_firmprog.cpp, hpp)

[1.0.0]

• TWELITE CUE 対応

• Windows はスタティックリンクに対応

• Raspberry Pi3B の暫定対応

• シリアルポート関連のソースの整理 (src/gen/serial_???)

• パーサーのコード整理を実施 (src/twe_fmt???)

• ITerm::move_cursorの戻り値をITerm&とした。

• ITerm& ITerm::operator() (int x, int y)の追加。カーソル移動を容易に。

[0.9.10]

• make_full_path() のパラメータに const_char* を許容するようにした

• TweCwdでサンプル等のワークスペース(Act_samples, Wkt_TweAppsなど)のサーチパスを 1. 起動時のCWD

  1. 実行形式格納場所 3. MWSDK/.. 4. MWSDK とした。

0.9.8 - 2020-10-08

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

TWELITE STAGE アプリ (example/TWELITE_Stage)

• ビューア一覧表示に[ｳｪﾌﾞ]ボタンを追加し、関連サイトを開く機能を追加

• ビューア＞コマンダーの追加

  • 標準アプリ 0x80 コマンド

  • NOTICE PALのLED制御 (App_Wingsにコマンドを送付)

• ビューア＞PALビューアのNOTICE PAL対応。

• Actエクストラのメニューを追加

  • Act_samplesより高度なもの

  • 外部のオープンソースライブラリ（センサー手続きなど）を利用したもの

• マウスによる操作を拡大 (リスト、ボタン、タブ)

  • マウス移動でフォーカス、左クリックで確定、右クリックは[ESC]キー入力

• 画面表示負荷の低減

  • アプリケーションがバックグラウンドの時はスクリーンセーバーを無効にした

  • アプリケーションがバックグラウンドの時は、描画回数を減らして CPU 負荷を減らした

• ビルドプロジェクト(Act, TWE_Apps, Actエクストラ)の一覧の機能強化

  • 項目選択時に下部に概要を表示 (000desc.txtを読み込む。TWE_Descクラスにより処理)

  • プロジェクトフォルダを開く（またはVSCodeで開く)機能

  • 関連ウェブサイトを開く機能

  • ALt+Shift+m mwxライブラリ、Alt+Shift+t twesettingsライブラリを開く機能

  • ビルドメニュー中で選択中のフォルダやビルドエラーファイルを開けるようにした。

• ログ（シリアルポート入出力）機能の追加

  • (Alt/Cmd+L)でログの開始・終了

  • ログファイルを {TWELITE_Stage 実行形式のあるディレクトリ}/log に格納

  • ファイル名は twestage_{日付-時刻}.log

  • Shift+Alt/Cmd+L でログファイルディレクトリを開く

• その他、変更・修正など

  • シリアル(FTDI)デバイス名、IDの表示方法を変更

  • App_UARTでインタラクティブモードに遷移しなかった問題を修正

  • ディレクトリドロップ時の挙動を変更した (これまではバイナリ書き込みになる場合があったが、メニュー遷移とした)

  • ターミナル長押し時[C]でリセットに加え、画面クリアするようにした。

ライブラリ

• NOTICE PALへの対応 (パーサー)

• パーサーを標準入出力で動作できるようにビルド定義やソースを調整 (examples_con/glancer)

• ITermの機能追加、不具合修正

  • すでに文字列が表示されている部分にダブルバイト文字を上書きしたとき、上書きした以降の表示が左右にズレていたが、完全ではないながらズレを抑制するコードを追加

  • ITerm::clear_line() を追加。行表示を抹消と、空白で埋める（表示は変わらないが

    空白データが行末まで追加される）

  • ITerm::move_cursor()を追加。エスケースシーケンスの記述が煩雑であったため。

• GUI関連クラスの追加

  • TWE_Widget : ウィジェットの基底クラス

  • TWE_WidSet_Buttons : 複数ボタンの一括管理

  • TWE_WidSet_Tabs : タブ選択

  • TWE_Buttons : ボタンクラス

  • TWE_ListView : リスト、機能拡張

    • ステータスラインを設定できるように（最終行をページ番号とページ移動用のボタンとした）

    • listViewでエントリ数がページ行数の整数倍の時の振る舞いの不具合対応

• その他変更、修正など

  • the_app.set_nextapp() を廃止し the_app.exit() に統合

  • the_keyboard.peek_a_byte() を追加

  • アプリハンドラーのデータコンテキストを APP_HNDLR_DC, APP_HNDLR::use() を追加

    • アプリハンドラーを用いる場合、サブアプリのデストラクタで APP_HNDLR::on_close() を呼ぶように変更。

  • SimpleBuffer<uint8_t>::c_str() を uint8_t* ではなく const char* 型を戻すメンバ関数として再定義

  • SimpleBuffer<wchar_t>(const wchar_t (&)[N]) のコンストラクタに不具合があった

  • 文字列比較 beginsWith(), beginsWith_NoCase()を追加

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

初期バージョン

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

TWELITE_Stage アプリは examples/TWELITE_Stage にあります。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ディレクトリを指定する。

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

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

MWM5ライブラリには、シリアル入出力、画面出力など多岐にわたるコードが含まれます。ここでは、コマンドライン(コンソール)画面上で動作標準入出力のみを用いる単純なサンプルについて解説します。

サンプルはexamples_con/以下に格納します。

• : App_Wings（または各アプリのUART出力)を解釈して、各パケットメッセージの概要を表示します。

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

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

setup()

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

loop()

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

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

update_screen()

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

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

本パッケージ内で、ライセンス上特別な記述のないものは、を適用します。詳細はパッケージ付属の文書を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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";
    }

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

      [IParser]
          ↑
     [AsciiParser]

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

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

#include <mwm5.h>
#include <M5Stack.h>

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

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

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

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

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

App_Wings（または各アプリのUART出力)を解釈して、各パケットメッセージの概要を表示します。

ファイル構成

プロジェクトフォルダ

examples/glancer      --- Makefile
msc/MSC_glancer_con   --- VC++ Project 定義

プロジェクトフォルダのソースコードはglancer.cppのみです。残りの必要なコードはsrc/..を参照します。

他のプロジェクトなどに移植する場合

MWM5ライブラリ全てのファイルは必要ありません。以下に必要なファイルを列挙します。

twe_fmt.cpp
twe_fmt_actstd.cpp
twe_fmt_appio.cpp
twe_fmt_apptag.cpp
twe_fmt_appuart.cpp
twe_fmt_common.cpp
twe_fmt_pal.cpp
twe_fmt_twelite.cpp
twe_sercmd.cpp
twe_sercmd_ascii.cpp
twe_utils_crc8.cpp

twe_common.hpp
twe_fmt.hpp
twe_fmt_actstd.hpp
twe_fmt_appio.hpp
twe_fmt_apptag.hpp
twe_fmt_appuart.hpp
twe_fmt_common.hpp
twe_fmt_pal.hpp
twe_fmt_twelite.hpp
twe_sercmd.hpp
twe_sercmd_ascii.hpp
twe_stream.hpp
twe_utils.hpp
twe_utils_crc8.hpp
twe_utils_fixedque.hpp
twe_utils_simplebuffer.hpp

ビルド

ビルドに必要な定義

ビルド方法(VC++, Windows)

examples/glancer_con というプロジェクト定義がありますので、こちらをビルドしてください。

ビルド方法 (Makefile, gcc)

make (GNU) と g++ (gcc より) が必要です。事前にインストールを済ませてください。

Makefileを確認してください。以下の定義は必要に応じて書き換えます。

makeコマンドを実行します。

millis()の実装

#if defined(_MSC_VER) || defined(__MINGW32__)
#include "windows.h"
# pragma comment(lib, "secur32.lib")
# pragma comment(lib, "winmm.lib")
# pragma comment(lib, "dmoguids.lib")
# pragma comment(lib, "wmcodecdspuuid.lib")
# pragma comment(lib, "msdmo.lib")
# pragma comment(lib, "Strmiids.lib")
#elif defined(__APPLE__) || defined(__linux)
#include <sys/time.h>
#endif

uint32_t millis() {
#if defined(_MSC_VER) || defined(__MINGW32__)
	return (uint32_t)timeGetTime();
#elif defined(__APPLE__) || defined(__linux)
	timeval time;
	gettimeofday(&time, NULL);
	long ms = (time.tv_sec * 1000) + (time.tv_usec / 1000);
	return (uint32_t)ms;
#else
	# warning "no millis() implementation."
	return 0;
#endif
}

実行例

:78811501C98201015A000391000C2E00810301FFFFFFFFFB
PKT:Typ=1:Lq=201:Ad=0x8201015a(0x78):Vmv=3118:Tms=2656:App_Twelite:DI1..4=LHHH:AI1..4=(0028,----,----,----)
:78A0028201015AFFFFFFFFA8000700112233AABBCCC6
PKT:Typ=4:Lq=168:Ad=0x8201015a(0x78):Vmv=0000:Tms=5430:App_UARTMSG=0x00112233aabbcc
:8000000084811F810EFF6D04808205113008020AEB11300102035A0501000209E3010200020E3A02030004000001BE6C00
PKT:Typ=2:Lq=132:Ad=0x810eff6d(0x04):Vmv=2795:Tms=3904:PAL_AMB:TEMP=25.31:HUMD=36:LUMI=446

標準入力(通常の１バイト入力を用いているため改行が入力されるまでは入力文字列は評価されません)にアスキー形式のUARTメッセージを入力します。出力はPKT...となります。

先頭の項目について解説します。

ソースコードの構造

ヘッダ部

#include <iostream>
#include <iomanip> 
#include <string>

#include "twe_common.hpp"
#include "twe_sercmd_ascii.hpp"
#include "twe_fmt.hpp"

using namespace TWE;
using namespace TWEUTILS;
using namespace TWESERCMD;
using namespace TWEFMT;

AsciiParser parse_ascii(256);

必要な標準ライブラリヘッダとMWM5ライブラリヘッダを読み込みます。

MWM5ライブラリでは細かく名前空間が使用されていますが、利用時には煩雑ですのですべてusing namespaceにより省略可能とします。

AsciiParserのクラスインスタンスを生成しておきます。

メインループ

int c;
while ((c = std::cin.get()) >= 0) {
	if (c == '\r' || c == '\n') {
		parse_ascii << char_t(0x0d); // always 0x0d (this parser does not check the following 0x0a)
	}
	else {
		parse_ascii << char_t(c);
	}

	if (parse_ascii) {
		std::cout << "PKT";
		auto&& payl = parse_ascii.get_payload(); // payload data array
		auto&& pkt = newTwePacket(payl);         // packet object (contains minimum information)
		auto&& typ = identify_packet_type(pkt);  // packet type
		std::cout << ":Typ=" << int(typ);

		if (typ != E_PKT::PKT_ERROR) {
		   // ... display common packet info 
		}
		
		// display each packet information
		switch (typ) {
			case E_PKT::PKT_PAL: print_pal(pkt); break;
			case E_PKT::PKT_ACT_STD: print_act(pkt); break;
			case E_PKT::PKT_TWELITE: print_app_twelite(pkt); break;
			case E_PKT::PKT_APPIO: print_app_io(pkt); break;
			case E_PKT::PKT_APPUART: print_app_uart(pkt); break;
			case E_PKT::PKT_APPTAG: print_app_tag(pkt); break;
			default: print_unknown(payl); // e.g. UART message of App_Twelite, App_UART(simple format), or corrupted.
		}
  }
}

このサンプルでは標準入力から１バイトずつ入力(std::cin::get())して、これをASCIIパーサーに投入します。

標準入力ではシステムによって改行コードが異なりますが、ここでは'r'または'\n'のいずれが来ても'\r'を投入するようにしています。本パーサーは末尾の'\r'のみを評価するためです。

	if (parse_ascii) {

投入後書式が完了した場合はparse_asciiはtrueを戻します。ここでデータを解釈します。

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

ASCIIパーサーにより得られたバイト列は.get_payload()メソッドにより配列SmplBuf_Byte型として取り出すことが出来ます。

このサンプルでは得られたバイト列を解釈して、どの種別のUARTメッセージなのか、何が格納されているのかを取り出せるようにします。

バイト列を解釈する手続きはnewTwePacket()にバイト列paylを与えます。戻り値としてクラスオブジェクトpktを生成します。このオブジェクトはspTwePacket型の（メモリ管理を行う）スマートオブジェクトで、TwePacket型のオブジェクトを格納します。

auto&& typ = identify_packet_type(pkt);  // packet type

実際にはpktは種別に応じたTwePacket型の派生クラスのインスタンスが格納されています。この派生クラスの種別を確認するのがidentify_pkt_type()で、パケット種別としてE_PKT型の値を返します。

パケット種別が得られたら、パケット種別ごとの表示関数print_???(spTwePacket)を呼び出しています。

ここから先はパケット種別ごとに手続きが違います。以下にApp_Tweliteの解釈例、App_PALの解釈例を示します。

print_app_twelite()

void print_app_twelite(spTwePacket pkt) {
	auto&& atw = refTwePacketTwelite(pkt);
	std::cout << ":DI1..4="
			<< char(atw.DI1 ? 'L' : 'H') 
			<< char(atw.DI2 ? 'L' : 'H')
			<< char(atw.DI3 ? 'L' : 'H')
			<< char(atw.DI4 ? 'L' : 'H');
	...

App_Twelite の UARTメッセージの解釈を行います。まずspTwePacket型のままでは、App_Twelite特有のデータにアクセスできません。

まずrefTwePacketTwelite()を呼びます。戻り値はTwePacketTweliteの参照型です。App_TweliteのUARTメッセージを解釈した特有のデータが含まれます。例えば.DI1はDI1のHigh/Low状態を示します。

print_pal()

void print_pal(spTwePacket pkt) {
	auto&& pal = refTwePacketPal(pkt);
	PalEvent ev;

	// acquire event data.
	if (pal.has_PalEvent()) {
		ev = pal.get_PalEvent();
	}

	switch(pal.get_PalDataType()) {
		case E_PAL_DATA_TYPE::EVENT_ONLY: 
		  /* イベントのみが含まれるパケットの場合 */ break;

		case E_PAL_DATA_TYPE::MAG_STD:
			/* MAG PAL の表示コード */ break;
		
		case E_PAL_DATA_TYPE::MOT_STD:
			/* MOT PAL の表示コード */ break;
		
		case E_PAL_DATA_TYPE::AMB_STD:
			/* AMB PAL の表示コード */ break;
			
		case E_PAL_DATA_TYPE::EX_CUE_STD:
			/* TWELITE CUE のメッセージ */ break;		
	}

TWELITE PALのUARTメッセージを解釈します。TWELITE PALは接続される基板によって異なるUARTメッセージが出力されます。このためデータ取得も一旦PALとして解釈してから、さらに個別のPAL基板のデータを取り出します。

auto&& pal = refTwePacketPal(pkt);

最初にPAL共通データをrefTwePacketPal()により取り出します。

if (pal.is_PalEvent()) {

最初にパケットにイベントが含まれるかどうかの判定を行います。イベントパケットは例えば通知(NOTICE)PALの加速度センサーが静止状態から加速度を検出した（タップ）といった現象をイベント番号として伝えるものです。イベントパケットにも様々なデータが付加されますが、通常はイベント番号を参照します。

switch(pal.get_PalDataType()) {

パケットの種別を.get_PalDataType()により判定します。

case E_PAL_DATA_TYPE::MAG_STD:
{
			PalMag mag = pal.get_PalMag();
			std::cout << ":STAT=" << int(mag.u8MagStat);
			...

PAL基板の種別がわかったら、PAL基板の種別に応じた手続き(.get_PalMag()など)により、PAL基板特有のデータが含まれるクラスオブジェクトを得ます。

上記の例では開閉センサーPALの磁気センサーの状態を得ています。

アプリケーションはsetup(),loop()の２つの関数で記述されますが、例えば１画面ごとに大きく振る舞いが違うもの（ここではサブアプリと呼びます）を複数定義して、メニューで切り替えるといった動作を行う場合は、そのままsetup(),loop()内に記述しては煩雑になります。また変数についても管理する必要があります。

setup(), loop(), 関連する変数の切り替えを簡素化するためMWM5ライブラリでは以下の2つの仕組みを実装しています。

• サブアプリ : setup(), loop(), 関連変数をクラスとしてまとめ、切り替える

• アプリハンドラ: サブアプリ内で setup(), loop() を切り替える

サブアプリ

#include <mwm5.h>

// サブアプリ１
class App_Foo : public class APP_DEF {
public:
  void setup() { ... }
  void loop() { ... }
}

// サブアプリ２
class App_Bar : public class APP_DEF {
public:
  void setup() { ... }
  void loop() { ... }
}

// サブアプリ切り替え関数
static int s_change_app(
              TWE::APP_MGR& the_app, int n_appsel
            , int prev_app, int exit_id) {
    if (n_appsel == 1) the_app.new_app<App_Foo>();
    else if (n_appsel == 2) the_app.new_app<App_Bar>();
    else n_appsel = 0;
    
    return n_appsel;
}

// setup
void setup() {
    the_app.setup(s_change_app); // サブアプリ切り替え関数の登録
    the_app.new_app<App_Foo>(); // 最初に起動するサブアプリ
}

// loop()
void loop() {
  	the_app.loop(); // 必須の呼び出し
}

上記例は説明に必要な最小限のコードのみを記述します。APP_DEFを継承したApp_Foo,App_Barが、２種類のサブアプリの定義となり、各々がsetup(),loop()メンバー関数を定義しています。実際には振る舞いごとに必要なメンバー変数やその他メンバー関数が定義されます。サブアプリの登録や切り替えはライブラリ定義のクラスオブジェクトthe_appに対して操作を行います。s_change_app()関数はサブアプリを切り替える要求（サブアプリ終了時など）に対して、実際の切り替え部を実装していて、この関数をsetup()中で呼び出すthe_app.setup()のパラメータとして渡しておきます。loop()中にはthe_app.loop()を記述しておきます。

サブアプリの定義

class App_Foo : public class APP_DEF {
public:
  void setup() { ... }
  void loop() { ... }
}

void setup()とvoid loop()を記述しておきます。setup()はサブアプリが初期化されるときに1度だけ呼び出されます。loop()はthe_app.loop()関数中で呼び出されます。

サブアプリの切り替え

// APP_MGR内のtypedef
typedef int (*PF_CHANGE_APP)(
    THE_APP_MGR& the_app,
    int n_appsel,
    int prev_app,
    int exit_id);

// 例: App_Foo と App_Bar で切り替える
int s_change_app(
              TWE::APP_MGR& the_app, int n_appsel
            , int prev_app, int exit_id) {
    if (n_appsel == 1 || n_appsel == -1)
        the_app.new_app<App_Foo>();
    else if (n_appsel == 2)
        the_app.new_app<App_Bar>();
    else n_appsel = 0;
    
    return n_appsel;
}

実行中のサブアプリが終了する場合に呼び出されます。サブアプリは1以上のIDにより種別を管理し、切り替えのために関数int (*)(THE_APP_MGR&, int, int, int)を実装しておきます。

パラメータn_appselには、切り替えたいアプリケーションのIDが渡されます。パラメータはthe_app.exit()で指定した値です。-1が渡された場合は、デフォルトのサブアプリに切り替えるよう記述しておきます。

• パラメータprev_appには、直前のサブアプリIDです。直前が無ければ0となります。

• パラメータexit_idは、サブアプリがthe_app.exit()で指定した値です。

サブアプリ切り替え関数内部ではthe_app.new_app<T>()（Tは次に生成するサブアプリのクラス）を呼び出しています。この呼び出しによりクラスTのオブジェクトが生成され、同時にこれまで動作していたサブアプリのオブジェクトは破棄されます。

the_app.new_app<T>()

template <class T, class... Args>
void APP_MGR::new_app(Args&&... args)

// setup 例
void setup() {
    the_app.setup(s_change_app);
    the_app.new_app<App_Foo>(); // 最初に起動するサブアプリ
}

// サブアプリ切り替え関数例
static int s_change_app(
              TWE::APP_MGR& the_app, int n_appsel
            , int prev_app, int exit_id) {
    if (n_appsel == 1 || n_appsel == -1)
        the_app.new_app<App_Bar>();
    }
}

setup()とサブアプリ切り替え関数内で呼び出し、サブアプリのオブジェクトを生成し、同時に現在のサブアプリを破棄します。

• テンプレートパラメータTはサブアプリ定義クラスでAPP_DEFを継承している必要があります。

• テンプレートパラメータargsは、コンストラクタに渡されるパラメータです。オブジェクトはnew T(std::forward(args)...)で生成されます。サブアプリがパラメータを指定しないデフォルトコンストラクタで構築される場合は何も指定しません。パラメータを指定する場合はサブアプリのコンストラクタの定義が必要です（例えばApp_Foo::App_Bar(int)を定義しておいてthe_app.new_app<App_Bar>(exit_id)）。

the_app.exit()

void APP_MGR::exit(int exit_code, int next_app = NEXT_APP_DEFAULT)

// loop() の呼び出し階層
loop() // 大本のloop()
  the_app.loop() // APP_MGRのloop()
  
    App_Foo::loop() // サブアプリのloop()
      ...
      if (..) { // 何かの条件でサブアプリを終了する
        the_app.exit(0);
        return; // 通常はここでreturn
      }
    // App_Foo::loop()が終了した
    
    // exit がコールされていた場合は、
    // サブアプリ切り替え関数を呼び出し、
    // 次のサブアプリに切り替える。
  }
}

サブアプリのloop()内で呼び出し、loop()を抜けた直後にサブアプリを切り替えます。

上記の例のように大本のloop()からはthe_app.loop()が呼び出され、さらにサブアプリのloop()が呼び出されます。サブアプリのloop()中でthe_app.exit()が呼び出されると、the_app.loop()内でアプリケーションの切り替えが行われます。実際に切り替えているのはユーザが定義するサブアプリ切り替え関数です。

• パラメータexit_codeは、サブアプリの終了コードを指定します。任意の数を指定できます。

• パラメータnext_appは、次のサブアプリを明示的に指定する意味合いの識別子です。-1はデフォルトのサブアプリ、0は切り替えを行わない、1以上が次のサブアプリの識別子と意味付けをしています。

the_app.query_appobj()

APP_DEF* APP_MGR::query_appobj() // the_app.qurery_appobj()

// サブアプリ定義クラス内で利用
void APPDEF::set_appobj(void* p)
void* APPDEF::get_appobj()

// サブアプリ例
class App_Foo {
  TWETerm_M5_Console _scr;
public:
  App_Foo : _scr(..) {
    // 共通オブジェクトの登録
    set_appobj((void*)static_cast<ITerm*>(&_scr));
  }
  void setup();
  void loop();
};

// 大本のloop()
void loop() {
  ..
  // APPDEFオブジェクトの取得
  if (auto p = the_app.query_appobj()) {
    // 登録されたvoid*をITerm*へ強制キャスト
    if (ITerm* ptrm = reinterpret_cast<ITerm*>(p->get_appobj())) {
      ... // ptrm を用いた操作
    }
  }
}

大本のloop()からthe_appで生成したサブアプリのクラスオブジェクトを参照し、さらにサブアプリが指定したvoid*型のポインタデータを取得します。

例えば、サブアプリ構築時に共通のクラスオブジェクトを持っていて（例えばメイン画面となるターミナル画面）、大本のloop()から共通のオブジェクトにアクセスします（例えばメイン画面上の文字列を取得）。

アプリハンドラ

アプリハンドラAPP_HNDLRは、サブアプリ中での簡易的なsetup(),loop()処理の切り替えを行います。例えば、リスト一覧→リスト選択後、エラーといった複数の画面を切り替えるような動作です。

サブアプリの実装ではAPPDEFを継承しましたが、さらにAPP_HNDLR<S>（Sはサブアプリクラスを指定します）を継承します。サブアプリ中に処理関数（アプリハンドラ）を実装し、アプリハンドラを切り替えます。

class App_Foo : public APPDEF, public APP_HNDLR<App_Foo> {
  // アプリハンドラ１
	void hndr_scr_def(event_type ev, arg_type arg = 0) {
		switch (ev) {
			case EV_SETUP:
			  // setup()に相当、最初に1回だけ呼ばれる
			break;
			case EV_LOOP:
			  // loop()に相当
        if (..) { // ある条件で次のアプリハンドラに遷移したい
          // アプリハンドラ切り替え
          APP_HNDLR::new_hndlr(&App_Foo::hndlr_scr_next);
          return; // 通常はここでreturn
        }
			break;
			case EV_EXIT;
			  // 終了時＝アプリハンドラ切り替え時に呼び出される
			break;
	}
	
	// ハンドラ２
	void hndlr_scr_next(event_type ev, arg_type arg = 0) {
	  ..
	}
	
public:
  ~App_Foo() { 
    APP_HNDLR::on_close();
  }
  void setup() {
    ...
    
    // 最初のアプリハンドラを登録する
    APP_HNDLR::new_hndlr(&App_Commander::hndr_screen_simple);
  }
  
  void loop() {
    // 必須呼び出し
    APP_HNDLR::loop();
    ...
  }
};

上記がアプリハンドラを用いたときのソース構造の例です。

hndr_scr_def()とhndr_scr_next()がアプリハンドラ関数です。パラメータとしてevとargが与えられ、evはEV_SETUP,EV_LOOP,EV_EXITのいずれかになり、setup(),loop()と終了処理に対応します。

アプリハンドラ関数

// APP_HNDLR<T>内のtypedef
typedef void (T::* tpf_func_handler)(event_type ev, arg_type evarg)

アプリハンドラ関数はsetup(),loop()に相当する処理を行います。加えてハンドラが切り替えられる、つまり現在登録されているハンドラが終了するときの処理を記述できます。

class App_Foo : public APP_DEF, public APP_HNDLR<App_Foo> {
  ..
	void hndr_scr_def(event_type ev, arg_type arg = 0) {
		switch (ev) {
			case EV_SETUP:
			  // setup()に相当、最初に1回だけ呼ばれる
			break;
			case EV_LOOP:
			  // loop()に相当
        if (..) { // ある条件で次のアプリハンドラに遷移したい
          // アプリハンドラ切り替え
          APP_HNDLR::new_hndlr(&App_Foo::hndlr_scr_next);
          return; // 通常はここでreturn
        }
			break;
			case EV_EXIT;
			  // 終了時＝アプリハンドラ切り替え時に呼び出される
			  // 注: サブアプリのデストラクタで APPHNDLR::on_close() を
			  //     記述してください
			break;
	}
};

パラメータevに対応した処理を記述します。

パラメータargは、APP_HNDLR::new_hnbdlr()やAPP_HNDLR::loop()でパラメータが与えられたときに、値が格納されます。

APP_HNDLR::new_hndlr()

void APP_HNDLR::new_hndlr(tpf_func_handler hnd_next, arg_type arg = 0)

アプリハンドラを初回生成する（サブアプリクラスのsetup()）、またはアプリハンドラ内から次のアプリハンドラへ切り替えます。

• パラメータhnd_nextはアプリハンドラ関数（メンバー関数のポインタ）を指定します。

• パラメータargはアプリハンドラ関数のEV_SETUP呼び出し時のパラメータを指定します。（EV_SETUPによる初期化時の処理を分岐したいときに利用します）

APP_HNDLR::loop()

void APP_HNDLR::loop(arg_type arg = 0)

サブアプリのloop()から毎回呼び出します。

• パラメータargを指定するとアプリハンドラにその値が渡されます。

APP_HNDLR::on_close()

void APP_HNDLR::on_close()

サブアプリのデストラクタから呼び出すようにしてください。

この記述を省略した場合、サブアプリのオブジェクトが破棄されるときに、アプリハンドラも破棄されますが EX_EXIT メッセージが呼び出されません。

アプリハンドラごとの独自データ

アプリハンドラは、サブアプリ内でsetup(),loop()コンテキスト切り替えの仕組みで、サブアプリ下でのメンバー関数の実行という携帯です。そのため、アクセスできるデータはサブアプリのメンバー変数となります。

ここでは、アプリハンドラ独自のデータを保持するクラスを追加します。

データを格納するクラスの準備

APPHNDLR_DCを継承したクラスを準備します。このクラスにはアプリハンドラ内で使用するデータやメンバー関数を定義します。以下の例ではDC_MyAppHndlrというクラスを定義しています。

/// APPHNDLR_DCを継承したデータ格納クラスの定義 
// publicアクセスで良いのでclassではなくstructで定義しています
struct DC_MyAppHndlr : public APPHNDLR_DC {
  static const int CLS_ID = 0;
	int get_class_id() { return CLS_ID; }
	
	MySubApp &app;
	
	// メンバ変数と操作関数
  int data1;
  void incr() { data1++ }
  
  // サブアプリ内のthe_screenに対する操作
  void display() { app.the_screen << data1; }
  
  // コンストラクタ
  DC_MyAppHndlr(MySubApp& app_) : 
              app(app_) // サブアプリオブジェクトを保存
            , APPHNDLR_DC(CLS_ID) // APPHNDLR_DCの初期化
            , data1(0) // メンバ変数の初期化
            {}
}

以下の定義を行う必要があります。

• static const int CLS_ID : データ格納クラス種別を識別するための個別のIDです。

• int get_class_id() : CLS_IDを戻すメンバ関数です。

• コンストラクタ : サブアプリクラスオブジェクトをパラメータとします。このオブジェクトは上記の例ではappに保存しDC_MyAppHndlrからサブアプリにアクセスする目的で利用します。

• 継承したAPPHNDLR_DCをAPPHNDLR_DC(CLS_ID)として初期化します。

サブアプリでのfriend宣言

DC_MyAppHndlrはサブアプリのメンバー変数や関数にアクセスすることも多いためfriend宣言しておきます。もちろん一般のクラス設計のようにpublicインタフェースを用意してカプセル化してもよいのですが、この場合、カプセル化の利点があまりなく記述が煩雑になるためです。

struct DC_My_AppHndlr;

//サブアプリ定義
class MySubApp : public TWE::APP_DEF, public APP_HNDLR<MySubApp> {
  ..
  
  void hndr_MyApp(event_type ev, arg_type arg = 0); // アプリハンドラ関数
  frined struct DC_MyAppHndlr; // friend宣言
}

アプリハンドラ内での利用

アプリハンドラではAPP_HNDLR::use<>()を用いてデータオブジェクトを取得します。オブジェクトの生成・破棄は暗黙に行われます。別のアプリハンドラに切り替えられたときにデータオブジェクトが破棄されます。

void MySubApp::hndr_MyApp(event_type ev, arg_type arg) {
  auto&& dc = APP_HNDLR::use<DC_My_AppHndlr>();
  
  switch(ev) {
  case EV_SETUP:
    ...
  break;
  
  case EV_LOOP:
    if (..) dc.incr();
  break;
  
  case EV_EXIT:
  break;
  }
}

上記の例では、アプリハンドラ関数の最初でdcを取得しています。初回呼び出しにオブジェクトが生成され、それ以降は生成されたオブジェクトを参照します。

あとは生成されたdcオブジェクトを操作します。

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

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(" "); }

ASCII書式での出力

Parserオブジェクトにデータ列が格納されている場合、>>演算子を用いることで書式をシリアルポート(Serial)やターミナル(ITerm)などに出力することが出来ます。

inline void IParser::operator >> (TWE::IStreamOut& fo_putchar)

// パーサーオブジェクトの宣言
AsciiParser o_parser(128);

// コード例 
auto&& b = o_parser.get_payload(); // SmplBuf_Byte&としてデータ列を参照
b.clear();
b << 0x00;
b << 0x11;
b << 0x22;
b << 0x33;

// ターミナルへ出力(ITerm)
o_parser >> the_screen; // the_screen はターミナル(ITerm)
//  -> :001122339A[改行]

// バッファーへ出力
SmplBuf_ByteSL<128> b1;
o_parser >> b1;
//  -> ":001122339A[CR][LF]"

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

パケットの生成

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);
	PalEvent ev;

	// acquire event data.
	if (pal.has_PalEvent()) {
		ev = pal.get_PalEvent();
	}

	switch(pal.get_PalDataType()) {
	case E_PAL_DATA_TYPE::EVENT_ONLY: 
			break;
	
	case E_PAL_DATA_TYPE::MAG_STD:
			break;
	
	case E_PAL_DATA_TYPE::AMB_STD:
			break;
	
	case E_PAL_DATA_TYPE::EX_CUE_STD:
			break;
	}

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

PALのパケット書式は様々な派生があります。

解釈時にまずイベントデータがあるかどうか取り出します。イベントが含まれるパケットはpal.has_PalEvent()により判定できます。イベントのみ受信できれば良い場合はpal.get_PalEvent()で得られたイベントデータを参照して終了です。

ｲﾍﾞﾝﾄ以外の情報が欲しい場合は、一旦pal.get_PalDataType()を用いてパケットのデータ構造を特定します。特定したデータ構造に応じたデータ取得を行います。

case E_PAL_DATA_TYPE::MAG_STD:
  {
    // generate pal board specific data structure.
		PalMag mag = pal.get_PalMag();
		switch(mag.u8MagStat) {
		case 0: /* no magnet */ break;
		case 1: /* N Pole */ break;
		case 2: /* S Pole */ break;
		}
  }
  break;

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

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

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

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

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

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

メソッド

TwePacket() - コンストラクタ

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

~TwePacket() - デストラクタ

get_type()

parse()

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

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

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

メソッド

AsciiParser() - コンストラクタ

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

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

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

_u8Parse()

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

_vOutput()

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

s_Output(), vPutByte()

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

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

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

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

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

メソッド

Parse(), operator << ()

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

state()

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

operator bool(), is_complete()

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

length()

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

operator[]()

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

get_payload()

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

set_payload()

パーサーオブジェクトを用いて出力を構築する際に、データ列をコピーします。コピー元はSmplBuf_Byteデータ構造またはuint8_t*型の先頭と終端+1ポインタの組み合わせです。

reinit()

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

operator << ()

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

メソッド

_u8Parse()

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

_vOutput()

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

状態