1 / 12

Getting started

Environment

環境

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

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

Building

ビルド（コンパイル）について

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 のパッケージをダウンロードして利用します。

macOS 10.15 (Catalina) では、clangを用いることも可能です。オプションOSX_COMPILERTYPE=clangを追加してmakeしてください。

※ C++17 の filesystem ライブラリがバージョン依存になります。10.15以前ではビルドできず、またビルドしたバイナリを10.14以前で動作させることもできません。

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

プロジェクト MWM5.sln を開きます。
Sketch＞TWELITE_Stage をスタートアッププロジェクトにします。必須ではありませんが、デバッガを起動する際などにこのプロジェクトが選択されます。
Debug/Release のいずれかを選択します。
32bit/64bit のいずれかを選択します。
Sketch＞TWELITE_Stage を右クリックしてビルドを選択します。
実行形式は msc\Release msc\Debug などのディレクトリに格納されます。

macOS, Linux, Windows (MingW64)

コマンドプロンプト、シェルを開きます。
make, gcc-9, g++-9 が動作することを確認します。
{ソースコードを展開したディレクトリ}/examples/{ビルドしたいプロジェクト:例 TWELITE_Stage}/build に移動します。
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ディレクトリを指定する。

Hardware

ハードウェア接続

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 の資料も参考の上、十分注意して行ってください。

例： M5Stack faces の GPIO05 ピンは、キーパッドの割り込みピン（出力）が接続されているため、M5Stack側で出力制御を行うことはできません（故障の原因になりえます）。TWELITE STAGEアプリケーションでは、キーパッドに対応するI2Cデバイスを検出した場合は、出力制御しないようにしています。

[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 無線マイコンモジュールが安定稼働することを保証するものではありません。

Examples

サンプルコード

AppTwelite_Recv

標準アプリケーション

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

M5stickに接続する前に書き込んだTWELITE DIPが無線パケットを受信してデータを出力するかPCで確認しておいてください。

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

PAL_Recv

TWELITE PAL

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

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

M5Stackに接続する前に書き込んだTWELITE DIPが無線パケットを受信してデータを出力するかPCで確認しておいてください。

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

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

Examples (console)

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

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

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

glancer_con

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

glancerは「glance（一目する）人」の意味の英単語です。

ファイル構成

プロジェクトフォルダ

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

上記で必要なファイル等は本ドキュメントと相違ある場合もあります。問題があればビルド時にエラーが表示されますので、エラーファイルに記述される"～not found"といったメッセージを頼りに足りないファイルをコピーしてください。

ビルド

ビルドに必要な定義

ビルド方法(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...となります。

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

ソースコードの構造

解説 Parser についても参照ください。

ヘッダ部

#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の磁気センサーの状態を得ています。

Using Library

ライブラリの使用

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

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

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

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

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

Parser

シリアル電文パーサーの利用例

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

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

アスキー形式

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

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

:00A01301FF123456B1[CR][LF]

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

:00A01301FF123456X

定義

AsciiParser の使用方法

オブジェクトの生成

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

ASCII形式では実際のバイト数の約２倍の書式になります。例えば書式が200バイトの系列の場合は、実データは約100バイトになります。

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

バイト列の解釈

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

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

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

データ列の取り出し

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

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列挙体で定義されています。

PALパケットの解釈

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

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

Terminal

ターミナル(コンソール）クラスの利用例

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

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

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

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

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

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

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

glancer_con

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

glancerは「glance（一目する）人」の意味の英単語です。

ファイル構成

プロジェクトフォルダ

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

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

ソースコードの構造

解説 Parser についても参照ください。

ヘッダ部

#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パーサーに投入します。

	if (parse_ascii) {

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

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

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

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

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

パケット種別が得られたら、パケット種別ごとの表示関数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特有のデータにアクセスできません。

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

auto&& pal = refTwePacketPal(pkt);

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

if (pal.is_PalEvent()) {

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の磁気センサーの状態を得ています。

Parser

シリアル電文パーサーの利用例

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

アスキー形式

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

:00A01301FF123456B1[CR][LF]

:00A01301FF123456X

定義

AsciiParser の使用方法

オブジェクトの生成

// serial parser
AsciiParser parse_ascii(256);

ASCII形式では実際のバイト数の約２倍の書式になります。例えば書式が200バイトの系列の場合は、実データは約100バイトになります。

無線パケットの最大格納バイト数が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()はの参照型を戻します。

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

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書式での出力

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]"

通常は、解釈用のParserオブジェクトと出力用のParserオブジェクトは別々に用意します。

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

パケットの生成

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
}

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

オブジェクトは参照カウンタにより管理されていて、所有者が0になれば破棄されます。

解釈されたパケットの種別は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;
	}

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

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

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

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)のオブジェクトを生成しています。ここではオープンクローズに応じた分岐にを読み出しています。