保証・ライセンス

本パッケージ内で、ライセンス上特別な記述のないものは、モノワイヤレスソフトウェア使用許諾契約書(MW-SLA)を適用します。

本ドキュメントについても、本ライブラリパッケージ部の一部としてMW-SLA下の取り扱いとします。

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

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

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

/* Copyright (C) 2019-2022 Mono Wireless Inc. All Rights Reserved.
   Released under MW-SLA-*J,*E (MONO WIRELESS SOFTWARE LICENSE
   AGREEMENT) */

MWX ライブラリは、TWELITE モジュールのプログラムをより容易にかつ拡張性を高めるために設計されています。これまでMWSDKで利用していた TWENET C ライブラリを基本とし、MWXライブラリはアプリケーション開発層のライブラリとして開発しております。

   Act (USER APPs)... 
+-----------------------+
| MWX C++ LIB           |
+---------------+       |
| TWENET C LIB  |       |
+------------+----------+
| MAC LAYER  | AHI APIs |
+-----------------------+
| TWELITE HARDWARE      |
+-----------------------+

MWX ライブラリの名称は Mono Wireless C++ Library for TWELITE です。MW は MonoWireless から、また C++ -> CXX -> double X -> WX。この MW と WX を重ねて MWX になりました。

このライブラリを用いて記述したコードを「アクト(act)」と呼びます。

表記等について

本解説での表記について記載します。

auto&&

ユニバーサル参照と呼ばれ、標準ライブラリなどで良く用いられます。当ライブラリでもほとんどの場合auto&& と記載します。

#include <algorithm>
int v[] = { 1, 3, -1, 5, 10 };
auto&& result = std::minmax_element(std::begin(v), std::end(v));
Serial << "min=" << int(result.first)
       << ",max=" << int(result.second);

名前空間について

namespace, inline namespace, using を用いて、名前の再定義などを行っています。解説中でも一部省略して記載しています。

制限事項 (TWENET)

MWXライブラリは、下層に位置する各ライブラリ・機能（TWNET Cライブラリでの機能、また半導体ベンダが提供するマイコン・ペリフェラル機能、IEEE802.15.4の機能）について、その全てに対応する目的では開発しておりません。

制限事項 (C++の利用)

MWXライブラリはC++言語で記述されておりアクトの記述においても C++ での記述を行うことになります。しかしながらC++言語であってもすべての機能が使えるわけではありません。特に以下の点に注意してください。

• new, new[] 演算子でのメモリ確保は行えますが、確保したメモリを破棄することはできません。C++ライブラリで動的メモリ確保をするものは殆どが事実上利用不可能です。

• グローバルオブジェクトのコンストラクタが呼び出されません。 参考：必要な場合は、初期化関数(setup()) で new ((void*)&obj_global) class_foo(); のように初期化することでコンストラクタの呼び出しを含めた初期化を行えます。

• 例外 exceptionが使用できません。

• 仮想関数 virtual が使用できません。

• 上記の制約があるためSTLなどC++標準ライブラリの一部のみの利用となります。

※ 当社で把握しているものについての記載です。

ライブラリのソースコードについて

ソースコードは以下から参照できます。

• {MWSDKインストールフォルダ}/TWENET/current/src/mwx

• https://github.com/monowireless/mwx

本資料で利用する用語について補足します。

一般的な用語

SDK (TWELITE SDK, MWSDK)

ソフトウェア開発環境

IEEE802.15.4

TWELITE無線モジュールが利用する無線規格です。MWXライブラリを使用する限り、無線規格の詳細を意識する必要はありません。

パケット

無線通信における最小の通信単位です。

最大量は通信方式や通信時の設定によって変わりますが、MWXライブラリ標準の通信<NWK_SIMPLE>では、ユーザが１パケットで送信できるデータ量は９０バイトです。

ペイロード

「貨物」といった意味合いですが、無線パケットに含まれるデータ本体のことをいいます。

ノード

「点・節」といった意味合いですが、無線ネットワーク内の無線局のことを言います。

MWXライブラリ特有の用語

アクト

本ライブラリを用いて作成したプログラム。そのソースコードまたは動作するプログラムのことを言います。

ビヘイビア

アクトの中でも特にイベント形式のプログラム。そのソースコードまたは動作するプログラムのことを言います。

ビヘイビアは１つのクラス定義による記述で、TWENETからのコールバック関数やイベントや割り込み処理を記述しひとまとめにしています。MWXライブラリでは以下の３種類のビヘイビアがあります。

• アプリケーションビヘイビア：イベントドリブンでのアプリケーション記述を行い、ユーザが定義するクラス。

• ボードビヘイビア：TWELITE無線モジュールを実装するボードの機能利用を簡素化するためのクラス。

• ネットワークビヘイビア：無線ネットワークの手続きを簡素化するためのクラス。

ビヘイビア名は < > で括って表記します。例えばシンプル中継ネットワークのビヘイビア名は <NWK_SIMPLE> です。

クラスオブジェクト

本ライブラリの解説では、ライブラリで最初からグローバル宣言されたオブジェクトをクラスオブジェクトと呼称します。Serial, Wire などです。これらクラスオブジェクトは手続きなしまたは開始手続きを行うことで利用できます。

メモリを比較的多く消費するクラスオブジェクトは、初期化手続きの際(.setup()または.begin()メソッド)に初期化パラメータに沿ったメモリを確保します。

C++に関する用語

C++

C++言語のこと。

C++11

C++規格のバージョンの一つ。2011年式のC++といった意味合いで、2011年にISOで規格化されています。直前のC++03から大きく機能拡張されています。C++14, C++17といったより新しいバージョンがあります。

クラス

あるデータに注目して、その手続きをひとまとめにしたもの。構造体に、その構造体を取り扱うための手続きが含まれています。実際にはもっと深い話題に発展しますが、専門書を参考にしてください。

C++においては、キーワードの structと classは本質的には同じもので、いずれのキーワードで宣言してもクラスとなります。

struct myhello {
  int _i;
  void say_hello() { printf("hello %d\n", _i); }
};

上記のクラス定義をC言語でも行った場合、例えば以下のようになります。

typedef struct _c_myhello {
  int _i;
  void (*pf_say_hello)(struct _c_myhello *);
} c_myhello;

void say_hello(c_myhello*p) { p->pf_say_hello(); }
void init_c_my_hello(c_myhello*p) {
  p->pf_say_hello = say_hello;
}

ラッパークラス

既存のC言語のライブラリやその内部の構造体などをクラスに包含し、C++特有の機能性を追加するなどして、利用の便を図ったものです。解説中でも「～構造体をラップした」といった記述をする場合があります。

メソッド・メンバー関数

クラスに定義される関数で、クラスに紐付いています。

struct myhello {
  int _i;
  void say_hello() { printf("hello %d\n", _i); } //メソッド
};

オブジェクト（インスタンス）

クラスを実体化（メモリ確保）したもの。

void func() {
    myhello obj_hello; // obj_helloがmyhelloクラスのオブジェクト
    obj_hello._i = 10;
    obj_hello.say_hello();
}

本解説ではオブジェクトとインスタンスは同じ意味合いとして取り扱っています。

コンストラクタ

オブジェクト生成時の初期化手続き。

struct myhello {
  int _i;
  void say_hello() { printf("hello %d\n", _i); }
  
  myhello(int i = 0) : _i(i) {} // コンストラクタ
};

void my_main() {
  myhello helo(10); // ここでコンストラクタが呼び出され_i=10にセットされる
}

デストラクタ

コンストラクタと対になってオブジェクトが破棄されるときの手続きです。

struct myhello {
  int _i;
  void say_hello() { printf("hello! %d\n", _i); }
  
  myhello(int i = 0) : _i(i) {} // コンストラクタ
  ~myhello() {
    printf("good bye! %d\n", _i);
  } //デストラクタ
};

抽象クラス

C++では仮想クラスによりポリモーフィズム（多態性）を実現します。具体的にはvirtualキーワードで指定た純粋仮想関数を定義したクラスです。

struct Base {
  virtual void say_hello() = 0;
};

struct DeriveEng : public Base {
  void say_hello() { printf("Hello!"); }
};

struct DeriveJpn : public Base {
  void say_hello() { printf("Kontiwa!"); }
};

スコープ

C/C++言語では { } で括った範囲と考えてください。この中で生成したオブジェクトは、スコープから出るときに破棄されます。この時デストラクタが呼び出されます。

以下は、明示的にスコープを設定したものです。helo2は8行目まで実行された時点で破棄され、デストラクタが呼び出されます。

void my_main() {
  myhello helo1(1);
  helo1.say_hello();
  
  {
    myhello helo2(2);
    helo2.say_hello();
  }
}

// hello! 1
// hello! 2
// good bye! 2
// good bye! 1

MWXライブラリでは以下のような記法を用いています。ここではif文の条件判定式内で宣言（C89といった旧いC言語ではこういった場所での宣言はできません）されたオブジェクトの有効期間は、if文の{}内になります。

struct myhello {
  int _i;
  void say_hello() { printf("hello! %d\n", _i); }
  operator bool() { return true; } // if()での判定用の演算子
  
  myhello(int i = 0) : _i(i) {} // コンストラクタ
  ~myhello() { printf("good bye! %d\n", _i); } // コンストラクタ
};

// myhello オブジェクトを生成する関数 (ジェネレータ)
myhello gen_greeting() { return my_hello(); }

void my_main() {
  if (myhello x = gen_greeting()) {
    // myhelloのオブジェクト x は if文中有効
    x.say_hello();
  }
  // if 分を抜けるときにオブジェクトxは破棄される
}

例えば二線シリアルバスなど、開始と終了の手続きがあって、その間だけオブジェクトによってバスを操作するような手続きです。オブジェクトの生成後、バスの接続が適切であればif文のtrue節が実行され、生成したオブジェクトによってバスの書き込みまたは読み出しを行います。バスの読み書き操作が終了したらif文を脱出し、この時デストラクタが呼び出され、バスの利用終了手続きが行われます。

const uint8_t DEV_ADDR = 0x70;
if (auto&& wrt = Wire.get_writer(DEV_ADDR)) { //バスの初期化、接続判定
	wrt(SHTC3_TRIG_H); // 書き出し
	wrt(SHTC3_TRIG_L);
} // バスの利用終了手続き

名前空間 (namespace)

定義名の重複を避けるためC++では名前空間が積極的に用いられます。名前空間にある定義にアクセスするには::を用います。

namespace MY_NAME { // 名前空間の宣言
  const uint8_t MYVAL1 = 0x00;
}

...
void my_main() {
  uint8_t i = MY_NAME::MYVAL1; // MY_NAME の参照
}

テンプレート (template)

テンプレートはC言語のマクロを拡張したものと考えてください。

template <typename T, int N>
class myary {
  T _buf[N];
public:
  myary() : _buf{} {}
  T operator [] (int i) { return _buf[i % N]; }
};

myary<int, 10> a1; // int 型で要素数10の配列
myary<char, 128> a2; // char 型の要素数128の配列

この例では、簡単な配列を定義しています。TとNはテンプレートのパラメータで、Tは型名をNは数値を指定し、T型で要素数Nの配列クラスを定義しています。

nullptr

C++11ではNULLポインタをnullptrと記述するようになりました。

参照型

C++では、参照型を利用できます。これはポインタによるアクセスに似ていますが、必ずオブジェクトを参照しなければならないという制約があります。

以下のような参照渡しのパラメータを持つ関数ではiの値をincr()内で書き換えることが出来ます。

void incr(int& lhs, int rhs) { lhs += rhs; }

void my_main() {
  int i = 10; j = 20;
  incr(i, j);
}

テンプレートの解説例ですがoperator[]の戻り型をT&に変更しています。こうすることでa[0]=1のように配列内部のデータに対して直接代入操作ができるようになります。

template <typename T, int N>
class myary {
  T _buf[N];
public:
  myary() : _buf{} {}
  T& operator [] (int i) { return _buf[i % N]; }
};

myary<int, 10> a1;
void my_main() {
  a1[0] = 1;
  a1[1] = 2;
}

型推論

C++11 では型推論のautoキーワードが導入されています。これはコンパイラが初期化の記述からそのオブジェクトの型を推論するため、具体的な型名の記述を省略できます。これはtemplateを用いたクラス名が非常に長くなるような場合に効果的です。

解説中では多くの場合ユニバーサル参照と呼ばれるauto&&を用いています。ユニバーサル参照については、ここでは参照渡しの場合も意識せずに記述できるものと考えてください。

auto&& p = std::make_pair("HELLO", 5);
       // const char* と int のペア std::pair

コンテナ

配列など特定のデータ型のオブジェクトを複数個格納するためのクラスをコンテナと呼びます。テンプレートの例で挙げたmyaryのような配列クラスもコンテナと呼んでいます。

イテレータ, .begin(), .end()

C言語で言うところのポインタ（もちろんC++でも同じようにポインタは使えます）を拡張した概念です。C言語のポインタは、メモリが連続した要素を先頭から末尾まで連続的にアクセスする手段と考えることが出来ます。FIFOキューを考えてみます。もっとも単純なキューの実装はリングバッファによるものですが、メモリーの連続性はありません。こういったデータ構造であっても、イテレータを用いるとポインタと同じように記述できます。

イテレータを取得するため.begin(),.end() のメソッドが用いられます。コンテナの先頭を指すイテレータを.begin()で取得します。末尾の次を指すイテレータを.end()で取得します。末尾ではなく、末尾の次である理由にはforやwhile文のループ記述の明快さ、コンテナに格納される要素数が0の場合の取り扱いが挙げられます。

my_queue que; // my_queue はキューのクラス

auto&& p = que.begin();
auto&& e = que.end();

while(p != e) {
  some_process(*p);
  ++p;
}

上記では、queの各要素について、イテレータpを用いて各要素にsome_process()を適用しています。pは++演算子によって次の要素を指すイテレータとしてインクリメントしています。本来ポインタでは記述できないデータ構造を持つコンテナであっても、このようにポインタを用いた処理と同じような処理が出来ます。

.end()が末尾の次を示すため、while文の終了判定は(p != e)のように簡潔です。キューに要素がない場合は.begin()は.end()と同じイテレータを返します。（何も格納されていない要素のイテレータの次ですから、最初に格納すべき領域を示すイテレータと考えればよいでしょう）

メモリ上で連続したコンテナの場合、通常、そのイテレータは通常のポインタとなります。その操作時に大きなオーバーヘッドにはならないことが期待できます。

C++標準ライブラリ

C++の標準ライブラリにはSTL(Standard Template Library)が含まれます。MWXライブラリでの一部を利用しています。

アルゴリズム

例えば最大や最小値を求めるといった処理をC言語では型に応じて別々に記述していました。こういったコードは型の部分だけ違って他は同じといったものも少なくありません。C++ではtemplateやイテレータなどを用いて、こういった処理を型に依存せず記述することができます。これをアルゴリズムと呼んでいます。

// 任意のイテレータをパラメータとし最大値を持つイテレータを戻す
template <class Iter>
Iter find_max(Iter b, Iter e) {
  Iter m = b; ++b;
  while(b != e) {
    if (*b > *m) { m = b; }
    ++b;
  }
  return m;
}

例えば上記のように最大値を求めるアルゴリズムです。このアルゴリズムは型に依存しません。(ジェネリックプログラミングと呼ばれます）

#include <algorithm>

auto&& minmax = std::minmax_element( // 最大最小を得るアルゴリズム
  que.begin(), que.end());

auto&& min_val = *minmax.first;
auto&& max_val = *minmax.second;

ここではqueのイテレータを指定し、その最大と最小を得るアルゴリズムstd::minmax_elenetを適用しています。std::minmax_elemetはC++標準ライブラリ内に定義されています。その戻り値は任意の２つの値を組み合わせるstd::pairです。このアルゴリズムは、イテレータの示す要素同士で<,>,==といった演算子での比較が出来れば最大と最小を計算してくれます。戻り型もイテレータの型から導かれます。

MWXライブラリを用いてアプリケーションを記述するには以下が必要です。

• MWSDK(ソフトウェア開発環境)

• 開発用エディタ(Microsoft社のVisualStudio Codeを紹介します)

Windows

コンパイラのツールチェインなどは比較的環境への依存度が低いため、多くの環境で動作することが期待できますが、現在サポート中のWindows10,11バージョンを推奨します。動作環境の差異により動作しないような場合は、当社で確認している環境を参考に別途環境を用意してください。

以下、開発で使用しているバージョンを挙げます。

• Windows11 21H2 (Visual Studio 2019)

• FTDI社のドライバが動作していること (MONOSTICK, TWELITE Rを動作させるため)

コンパイラのツールチェインなどは比較的環境への依存度が低いため、多くの環境で動作することが期待できますが、現在サポート中のディストリビューションを推奨します。動作環境の差異により動作しないような場合は、当社で確認している環境を参考に別途環境を用意してください。

以下、開発で使用しているバージョンを挙げます。

• Ubuntu 18.04 LTS 64bit

• Ubuntu 20.04 LTS 64bit

＊32bitのシステムはサポートしません。

macOS

コンパイラのツールチェインなどは比較的環境への依存度が低いため、多くの環境で動作することが期待できますが、現在サポート中のディストリビューションを推奨します。動作環境の差異により動作しないような場合は、当社で確認している環境を参考に別途環境を用意してください。

以下、開発で使用しているバージョンを挙げます。

• macOS 10.14.6 (Mojave Intel)

• macOS 12.4 (Monterey Apple Silicon)

Visual Studio Code など開発環境について

開発環境を動作させるための環境や使用方法については、その開発元やコミュニティの情報を参照ください。

ビルド環境による差異

更新方法

TWELITE STAGE の配布パッケージリリース後の修正・追加分などはGitHubレポジトリに格納しております。必要に応じて配布パッケージの位置を差し替えて利用いただくようお願いいたします。

MWSDKの他の更新が必要になる場合があります。更新時のリリース記述を参照してください。MWSDKの更新についてはこちらを参照ください。

MWXライブラリコードの更新方法

ライブラリのソースコードは GitHub (https://github.com/monowireless/mwx)にて公開しています。ライブラリのソースコードの差し替えは、以下の手順で行ってください。

1. 各リリースのリンクよりGitのクローンを行うか zip 形式でソースコードをダウンロードします。

2. 以下のフォルダの内容を差し替えます。

.../MWSTAGE/              --- TWELITE STAGE 配布フォルダ
        .../MWSDK         --- MWSDKフォルダ
              .../TWENET/current/src/mwx <--　このフォルダを差し替える

リリース前の更新

https://github.com/monowireless/mwx/wiki

リリース前の更新については上記に掲載する場合があります。

0.2.0 - 2022-03-01

• ヒープ領域へのメモリ確保を行う Wire オブジェクトを変更した。

• utils.hでの名前の衝突を避けるため、関数名をG_OCTET()からG_BYTE()に変更した。

• attachIntDio()において、vAHI_DioInterruptEnable()の順番を変更した。

• ユニバーサルレシーバ (NWK_LAYERED, NWK_SIMPLE またはネットワークレスパケットを同一実行コードで受信する) をサポートするために the_twelite.network2 を追加した。

• NWK_LAYERED を追加 (現時点では親機受信のみ対応)

• MWXの初期化時にアプリケーションのバージョンを設定する MWX_Set_Usder_App_Ver() 関数を導入した。

• mwx::pnew() を追加し配置newの記述を簡素化した。

• EASTLのサポート追加

  • EASTL用のnew[]演算子の追加

• MWXのソースコードのほとんどをプリコンパイルし、コンパイルの高速化を図った。

• 修正されました。DIOイベントが無関係なポートに引き渡されていたのを修正。

0.1.9 - 2021-12-15

主な改定内容

• TWELITE ARIA向けのボードサポート BRD_ARIA とセンサー定義 SHT4x を追加

• インタラクティブモード中で Serialクラスオブジェクトを用いた出力を可能とする内部手続きを追加 (Serial._force_Serial_out_during_intaractive_mode())

0.1.8 - 2021-09-09

主な改定内容

• Serial1のポート、代替ポートの定義が適切でなかった

• Serial(UART0)のボーレートを変更できるようにした

• 受信パケット(on_rx_packet())、送信完了(on_tx_comp())を知らせるイベントコールバックを追加

  • コールバック関数の定義をしなければ従前の手続きも利用可能

• <STG_STD>インタラクティブモード設定の定義ID間違いや一部デフォルト値の変更など

• <STG_STD>インタラクティブモード設定でAppIDに加えて、チャネルと論理デバイスIDのデフォルト値を変更できるようにした

• the_twelite と <NWK_SIMPLE> オブジェクトの設定を、一部の設定についてインタラクティブモード<STG_STD> オブジェクトで行えるようにした

• <NWK_SIMPLE>で再送回数のデフォルト値を設定できるようにした

• <STG_STD> インタラクティブモードの画面が出ている間はアプリケーションからのSerial(UART0)の入出力を行わないようにした

• CUE::PIN_SET, PAL???"":PIN_SETを追加 (PIN_BTNはボタンのないCUEでPIN_BTNを用いるのは不自然であるため)

• random()の名前空間をmwx::に移動 (グローバル名にエリアス)

• MONOSTICKのウォッチドッグ設定を32ms単位で行うようにした

• BRD_TWELITEを用いスリープを行うと、復帰時にピンが正しく初期化されなかった

0.1.7 - 2020-12-03

主な改定内容

• TWELITE CUE のボードビヘイビア(https://mwx.twelite.info/v/v0.1.7/boards/cue)を追加。

• NWK_SIMPLE 利用時に NWK_SIMPLE 形式でない他のパケット（ネットワーク利用無し）を受信する方法を追加。NWK_SIMPLE::receive_nwkless_pkt()を追加してNWK_SIMPLEを初期化する。 このパケット情報を用いる場合は .get_psRxDataApp() による TWENET C ライブラリ層の構造体、および .get_payload() により得られるデータ配列のみを利用してください。受信パケット(auto&& rx = the_twelite.receiver.read())の他のメソッドから得られる情報は不定です。

• get_stream_helper() コードのリファインと読み書き位置のAPIの整備。

• EEPROMクラスオブジェクトを追加 (https://mwx.twelite.info/v/v0.1.7/api-reference/predefined_objs/eeprom)

  • サンプル (https://github.com/monowireless/Act_samples/tree/master/Unit_EEPROM)

• smplbuf::get_stream_helper()の不具合修正

• pktparserクラスを追加しました (https://mwx.twelite.info/v/v0.1.7/api-reference/classes/pktparser)

  • サンプル (https://github.com/monowireless/Act_samples/tree/master/Unit_PktParser)

• serparser/pktparser を他のプラットフォームでビルドできるようサンプルを用意しました (https://github.com/monowireless/mwx/tree/master/stdio)

0.1.6 - 2020-10-09

主な改定内容

• 商・余を計算する div100() をSerial等へ出力できるようにした

• smplbuf<> 配列クラスの実装変更。消費メモリの削減などを目的としてmwx::streamの継承をやめ、別途継承クラスとヘルパークラス定義した

• mwx_printf() mwx_snprintf() の関数を追加した

• the_twelite.stop_watchdog(), the_twelite.restart_watchdog() を追加した

• mwx::stream のメンテナンス: operator bool() の廃止。読み出しタイムアウトの設定で 0xff を指定した場合(.set_timeout(0xff))タイムアウトを無効に。その他 << 演算子の定義を追加。

• NOTICE PAL / PCA9632 のサポートを追加 (解説 https://mwx.twelite.info/v/latest/boards/pal/pal_notice, サンプル https://github.com/monowireless/Act_samples/tree/master/Unit_using_PAL_NOTICE)

• 除算を行わない 8bit と 0..1000 間のスケール関数を追加。

• 10,100,1000による除算（商と余を同時に計算） div10(), div100(), div1000() を追加。値域を制限し乗算とビットシフトを中心に構成。

• 暗号化パケットの対応メソッドを追加

  • packet_rx::is_secure_pkt() : 受信パケットが暗号化されているかどうかの判定

  • STG_STD::u8encmode() : インタラクティブモードでの暗号化設定を取得

  • STG_STD::pu8enckeystr() : インタラクティブモードでの暗号化鍵バイト列の取得

• Serial1: デフォルトのポートは半導体の仕様では I2C と重複する DIO14,15 だが、通常 I2C に割り当てられるため DIO11(TxD), DIO9(RxD) とした。

• Serial: ボーレートの指定で /100 が発生するが、主要なボーレートについてこの計算を省略するようにした。

• Serial: available(), read() を外部で実施するための代理関数の保持を void* のみとし、仕様メモリを 8bytes 削減。

• typedef boolean の追加

• ネットワーク: 暗号化の対応を追加。

  • 暗号化を有効にするには NWK_SIMPLE::secure_pkt(const uint8_t*, bool = false) を設定追加する。１番目のパラメータは暗号キー、２番目を true にすると、平文のパケットも受信する。

    コピー

    auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
    nwk << NWK_SIMPLE::logical_id(0xFE) // set Logical ID. (0xFE means a child device with no ID)
        << NWK_SIMPLE::secure_pkt((const uint8_t*)"0123456789ABCDEF");
        ;

• SHT3xとBME280のセンサーサポート追加

• センサー: レガシーコード（Cライブラリのラッパクラス）で、設定パラメータや状態をやり取りするための仕掛けを追加した。

• センサー: SHT3x, BME280では I2C アドレスを指定可能とした。

• 設定: hide_items() を追加。不要な設定項目を削除可能。

• 設定: H/W UTIL メニューを追加。DIの状態表示、I2Cのプローブ、PAL EEPROM内容の表示。

• 設定: 暗号化関連のメニューの追加

• I2C関連の修正(TwoWireクラスを用いて実装されたコードとの親和性を向上するための修正）

  • requestFrom(false) の処理時に NO_STOP メッセージの送信コードが無かったため処理が正常に行われなかった。

  • TwoWire のクラス名エリアスを追加した。

  • begin() 処理で、多重初期化しないようにした。

  • setClock() メソッドを追加（ただしダミー関数で何もしない）

  • WIRE_CONF::WIRE_???KHZ を追加。バスクロックの主要な設定値を追加した。

0.1.5 - 2020-08-05

一括ダウンロード

MWSDK2020_08_UNOFFICIAL (README.md)

主な改定内容

• 設定ビヘイビア（インタラクティブモード機能）を追加

• チャネルマネージャ chmgr の実装

0.1.4 - 2020-07-29 (MWSDK2020_07_UNOFFICIAL)

一括ダウンロード

MWSDK2020_07_UNOFFICIAL (README.md)

主な改定内容

• delayMilliseconds() の追加

• digitalReadBitmap() の追加

• delay() の精度向上

• Serial1 インスタンスが定義されていない問題を修正

• Analogueの割り込みハンドラが呼び出されない問題を修正

0.1.3 - 2020-05-29

MWSDK2020_05 に対応

• 重複チェッカ duplicate_checker の初期化等に不備があり期待通りの除去を行っていなかった

• format() の実装を機種依存の少ないものとした。また、引数を最大８までとした。64bit引数が含まれる場合は引数の数は制限される。

https://github.com/monowireless/mwx/releases/tag/0.1.3

0.1.2 - 2020-04-24

MWSDK2020_04 に対応

• Timer0..4の初期化の問題を修正

• mwx::format() の内部処理を変更

• インタラクティブモード対応のための実験的なコードの追加

https://github.com/monowireless/mwx/releases/tag/0.1.2

0.1.1 - 2020-02-28

パケット内の中継フラグの扱いについての問題を修正

https://github.com/monowireless/mwx/releases/tag/0.1.1

0.1.0 - 2019-12-23

初版リリース (SDL 2019/12月号収録)

https://github.com/monowireless/mwx/releases/tag/0.1.0

MWXライブラリを用いてアプリケーションを記述（本書ではアクトと呼びます）し、実行するために開発環境のセットアップが必要です。

• TWELITE STAGE SDK 動作環境

• TWELITE STAGE SDK のインストール

• アクト(Act)のビルド

• (オプション) Visual Stdio codeのインストール

• 新しいプロジェクトの作成

• Makefile

• MWX ライブラリコードの一部を他(stdio)で利用する

新しいプロジェクトの作成は、すでにあるサンプルアクトのフォルダを別の名前でコピーし、ファイル名の編集を行います。

プロジェクトのファイル構造は以下のようになっています（ここでは PingPong を例に挙げます）。

Act_samples
  +-PingPong
    +-PingPong.cpp   : アクトファイル
    +-build          : ビルドフォルダ
    +-.vscode        : VSCode 用の設定ファイル    

この PingPong フォルダを別の場所（ただしフォルダ名に日本語や空白が含まない）にコピーします。

SomeDir
  +-AlphaBravo
    +-PingPong.cpp -> AplhaBravo.cpp ※ファイル名を変更
    +-build          : ビルドフォルダ
    +-.vscode        : VSCode 用の設定ファイル

編集の必要があるのは、PingPong.cpp のファイル名です。これをフォルダ名と同じAlphaBravo.cppに変更します。

ビルド定義の編集

ビルド対象のファイルを追加する場合は build/Makefile を編集します。プロジェクト直下にある .c .cpp ファイルは自動で追加されますが、それ以外のファイルについては編集が必要です。

編集方法は Makefile の解説をご覧ください。

VSCode用の設定

VSCode を利用する場合は、必要に応じて .vscode 以下の定義を編集してください。

TWELITE STAGE SDK に含まれるサンプルの多くは、以下のようになっています。

• TWELITE STAGE SDK ライブラリのソースコードは ${env:MWSDK_TWENET_LIBSRC}/include/** ${env:MWSDK_TWENET_LIBSRC}/src/** を引用する。この環境変数 MWSDK_TWENET_LIBSRC は TWELITE STAGE アプリから VSCode でプロジェクトを開いた場合には自動で設定されます。

• ビルドタスクについては、デフォルトで -D などの追加的なオプション等は設定されていない。

MWX ライブラリは、TWELITE 無線モジュールのコード表記を簡素化することを目的としています。MWXで作成されたプログラムをアクト act と呼びます。アクトにはループによる記述と、イベントによる記述（ビヘイビア behavior と呼びます）の二種類があります。

本ページではアクトの主な特徴を紹介します。

• ループによる記述 (setup(), loop())。小規模な機能を記述するのに向いています。

#include <TWELITE>
const uint8_t PIN_LED = 5;

void setup() {
  pinMode(PIN_LED, OUTPUT);
}

void loop() {
  if (TickTimer.available()) {
    uint32 t_now = millis();
    
    // blink LED every 1024ms
    digitalWrite(PIN_LED, (t_now >> 10) & 1 ? HIGH : LOW);
  }
}	

• イベントドリブンのアプリケーション記述。各種イベント・割り込みハンドラの定義、アプリケーションの複雑な振る舞いを記述するのに向いたステートマシンをクラス内に定義して見通しの良いコードを記述できます。この記述をビヘイビアと呼びます。

// myApp.hpp
...
class myApp : MWX_APPDEFS_CRTP(myApp) {
...
  void loop() {
    // main loop
  }
  
  void receive(mwx::packet_rx& rx) {
    // on receive
  }
};

// myApp.cpp
...
MWX_DIO_EVENT(12, uint32_t arg) {
		// on event from DIO12
}

• ペリフェラルの手続きを簡素化。よく使われる UART, I2C, SPI, ADC, DIO, タイマー, パルスカウンタを取り扱うクラスオブジェクトを定義しています。

void loop() {
  while(Serial.available() { 
    auto x = Serial.read(); ... } // serial message
  if (Analogue.available() {
    auto x = Analogue.read(...); } // adc values
  if (Buttons.available() { 
    Buttons.read(...); } // DIO changes
  if (the_twelite.receiver.available()) { 
    auto&& rx = the_twelite.receiver.read(); } // on rx packet
}

• シンプルな中継ネットワークを定義。この中継ネットワークは TWELITE 標準アプリケーションと同等の実装で、個体アドレスの管理は 8bit の論理IDで行うこと、ネットワーク構築のための通信を行わないため電源投入後すぐにネットワーク宛に無線パケットを送ることができる点が特徴です。

#include <TWELITE>
#include <NWK_SIMPLE>

void setup() {
  ...
  auto&& nwksmpl = the_twelite.network.use<NWK_SIMPLE>();
	nwksmpl << NWK_SIMPLE::logical_id(0xFE) 
	           // set Logical ID. (0xFE means a child device with no ID)
	        << NWK_SIMPLE::repeat_max(3);
	           // can repeat a packet up to three times.
}

void loop() {
  ...
  vTransmit();
  ...
}

void vTransmit() {
  if (auto&& pkt =
    the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet(); 
  pkt << tx_addr(0x00)  // to parent 
	  	<< tx_retry(0x3); // set retry
	
	pack_bytes(pkt.get_payload() // prepare payload data
	    , uint8_t(0x01)
	    , uint16_t(analogRead(PIN_ANALOGUE::A1))
	    , uint16_t(analogRead_mv(PIN_ANALOGUE::VCC)));
	
	pkt.transmit(); // transmit!
}

• PAL や MONOSTICK 向けのボード定義。ボード上のセンサーなどを容易に取り扱えます。

#include <TWELITE>
#include <PAL_AMB> // include the board support of PAL_AMB

void setup() {
	auto&& brd = the_twelite.board.use<PAL_AMB>(); // use PAL AMB
	uint8_t u8dip = brd.get_DIP_SW();   // check DIP s/w status
	brd.set_led(LED_TIMER::BLINK, 100); // LED switchs on/off every 100ms
	...
	
	// start capture of sensors
	brd.sns_SHTC3.begin();
}

void loop() {
	if (TickTime.available()) { // check every ms
		auto&& brd = the_twelite.board.use<PAL_AMB>();

		if (brd.sns_LTR308ALS.available()) {
		  Serial << brd.sns_SHTC3..get_temp();
		} else {
		  // notify sensor that 1ms passed.
			brd.sns_SHTC3.process_ev(E_EVENT_TICK_TIMER);
		}
	}
}

Makefileはbuild/Makefileに格納されています。makeコマンドを実行することで、アクトをビルドするよう予め定義されています。

makeのパラメータ

TWELITE=

ビルド対象をBLUEまたはREDで指定します。TWELITE BLUEならmake TWELITE=BLUEと指定します。

all

ビルドを実行します。通常は省略してmake TWELITE=BLUEのように実行します。

clean

ビルドの中間ファイルを削除します。make TWELITE=BLUE cleanのように実行します。

cleanall

すべての中間ファイルを削除します。make cleanallのように実行します。buildフォルダのobjs_???フォルダをすべて削除するのと同じです。

USE_APPDEPS=0 または 1

1 (デフォルト) を設定すると、ファイルの依存関係をもとに、ビルドファイルを決定します。例えば、ヘッダファイルに変更があった場合に関連するソースファイルが再コンパイル対象となります。

0 では依存関係を評価しません。0 に設定した場合、矛盾ある中間ファイルが残っていても makefile がエラーになりません。

Makefile 定義

アクトの規模に応じて、また、ビヘイビアの定義をする場合には、通常はソースファイルを分割してビルドします。

ビルドファイルの一つは{プロジェクトフォルダ名.cpp}です。

他にファイルを定義する場合は、プロジェクトフォルダのbuild/Makefileを編集します。

##############################################################################
# Copyright (C) 2019 Mono Wireless Inc. All Rights Reserved.
# Released under MW-SLA-*J,*E (MONO WIRELESS SOFTWARE LICENSE
# AGREEMENT). 
##############################################################################
# USER PROJECT BUILD DEFINITION.
##############################################################################

#####################################################################
### set TWELITE model
TWELITE ?= BLUE
#TWELITE = RED

#####################################################################
### set application version (MUST SET THIS.)
VERSION_MAIN = 0
VERSION_SUB  = 1
VERSION_VAR  = 0

#####################################################################
### set an additional source file
###   the default file name is dirname.

### for C++ files compiled with g++ (must have .cpp suffix)
APPSRC_CXX += myAppBhvParent.cpp
APPSRC_CXX += myAppBhvParent-handlers.cpp
APPSRC_CXX += myAppBhvChild.cpp
APPSRC_CXX += myAppBhvChild-handlers.cpp

### for C files compiled with gcc (must have .c suffix)
#APPSRC += my_c_file.c

### Additional Src/Include Path
# if set, find source files from given dirs.
#
APP_COMMON_SRC_DIR_ADD1 = ../Parent
APP_COMMON_SRC_DIR_ADD2 = ../Child
#APP_COMMON_SRC_DIR_ADD3 = 
#APP_COMMON_SRC_DIR_ADD4 =

#####################################################################
### set misc option for compiler

### C++ flags passed to g++
# e.g. CXXFLAGS += -DMY_DEFS
#CXXFLAGS +=

### C++/C flags passed to g++/gcc
# e.g. CFLAGS += -DMY_DEFS
#CFLAGS +=

### include opts
# e.g. INCFLAGS += -I../my_common_src/
#INCFLAGS +=

### optimize flag (default is -Os, normally no need to change)
#OPTFLAG=-O2

#####################################################################
### must include mwx.mk (the makefile body part.)
MWSDK_PATH?=$(realpath $(MWSDK_ROOT))
include $(MWSDK_PATH)/MkFiles/mwx.mk
#####################################################################

上記はサンプルPAL_AMB-bihaviorでのMakefileの例です。

VERSION_???

### set application version (MUST SET THIS.)
VERSION_MAIN = 0
VERSION_SUB  = 1
VERSION_VAR  = 0

バージョン番号を指定します。ビルド結果ファイル名に反映されます。

コンパイル中は -DVERSION_MAIN=0 -DVERSION_SUB=1 -DVERSION_VAR=0のように定義として渡されます。

ソースファイルの追加

ソースファイルを追加する際に必要なのはAPPSRC_CXXとAPP_COMMON_SRC_DIR_ADD?です。

ソースファイル名をAPPSRC_CXXに追記します。このファイル名にはフォルダ名が含まれてはいけません。サブフォルダにあるものもフォルダなしで指定します（つまり同じファイル名がサブフォルダにある場合は、ビルドが失敗します）

APPSRC_CXX += myAppBhvParent.cpp
APPSRC_CXX += myAppBhvParent-handlers.cpp
APPSRC_CXX += myAppBhvChild.cpp
APPSRC_CXX += myAppBhvChild-handlers.cpp

次にソースファイルがプロジェクトフォルダ以外の場所に格納されている場合の検索パスを指定します。最大４つまで設定できます。

APP_COMMON_SRC_DIR_ADD1 = ../Parent
APP_COMMON_SRC_DIR_ADD2 = ../Child

フォルダの指定はMakefileからの相対パスになります。

コンパイル・リンカオプション

その他にもいくつかのオプションをコンパイラ・リンカに渡すことができます。

MWX ライブラリ内で用いる C++ 言語について、その仕様、制限事項、本書記載留意事項、設計メモを記載します。

設計方針について

• アプリケーションのループ記述では、一般によく用いられる API 体系に近い記述を出来ることを目的とするが、TWELITEの特性に合わせた実装とする。

• TWENET はイベントドリブンによるコード記述であり、これを扱えるようにクラス化を行う。上記クラス化によりアプリケーションのふるまいをカプセル化できるようにする。

• イベントドリブンとループの記述は共存できる形とする。

• 代表的なペリフェラルはクラス化して手続きを簡素化する。可能な限りループ記述でアクセスできるようにする。

• 当社で販売する MONOSTICK/PAL といったボードを利用する手続きをクラス化し手続きを簡素化する。（例えば外部のウォッチドッグタイマーの利用を自動化する）

• アプリケーションクラスやボードクラスは、ポリモーフィズムの考え方を導入し、統一した手続きによって利用できるようにする。（例えば、いくつかの振る舞いをするアプリケーションクラスを始動時にロードするような場合、また TWENET C ライブラリの接続部のコードを都度定義しなくてよいようにするため）。

• C++の機能については、特に制限を設けず利用する。例えば、無線パケットを取り扱うにあたり煩雑なパケット構築、分解といった代表的な手続きを簡略化する手段を提供する。

• 演算子 -> を極力使用しないようにし、原則として参照型による API とする。

C++ コンパイラについて

バージョン

gcc version 4.7.4

C++言語規格

C++11 (コンパイラ対応状況は一般の情報を参考にしてください）

• https://gcc.gnu.org/gcc-4.7/cxx0x_status.html

• https://cpprefjp.github.io/implementation-status.html

C++ の制限事項

※ 当社で把握しているものについての記載です。

• new, new[] 演算子でのメモリ確保は行えますが、確保したメモリを破棄することはできません。C++ライブラリで動的メモリ確保をするものは殆どが事実上利用不可能です。一度だけ生成してそれ以降破棄しないオブジェクトに使用しています。

• グローバルオブジェクトのコンストラクタが呼び出されません。 参考：必要な場合は、初期化関数(setup()) で new ((void*)&obj_global) class_foo(); のように初期化することでコンストラクタの呼び出しを含めた初期化を行えます。

• 例外 exceptionが使用できません。

• 仮想関数 virtualが使用できません。

設計メモ

本節ではMWXライブラリのコードを参照する際に理解の助けとなる情報を記載します。

現状の実装

限られた時間で実装を進めているため、詳細部分の整備が十分でない場合があります。例えば const に対する考慮は多くのクラスで十分なされていません。

名前空間

名前空間について、以下の方針としています。

• 定義は原則として共通の名前空間mwxに配置する。

• 名前空間の識別子なしで利用できるようにしたいが、一部の定義は識別子を必須としたい。

• クラス名については比較的長い命名とし、ユーザが利用するものは別名定義とする。

クラス・関数・定数は一部の例外を除きmwx名(正確にはinline namespace L1 で囲んだmwx::L1)の名前空間内に定義しています。inline namespaceを指定しているのは、mwx::の指定を必須とする定義と、必須としない定義を共存させるためです。

殆どの定義はusing namespaceにより名前空間名を指定しなくても良いようになっています。これらの指定はライブラリ内のusing_mwx_def.hppで行っています。

// at some header file.
namespace mwx {
  inline namespace L1 {
    class foobar {
      // class definition...
    };
  }
}

// at using_mwx_def.hpp
using namespace mwx::L1; // mwx::L1 内の定義は mwx:: なしでアクセスできる
                         // しかし mwx::L2 は mwx:: が必要。

例外的に比較的短い名前についてはmwx::crlf, mwx::flushのように指定します。これらはinline namespaceのmwx::L2の名前空間に配置されています。using namespace mwx::L2;を指定することで名前空間名の指定なしで利用できるようになります。

また、いくつかのクラス名はusing指定をしています。

MWXライブラリ内で利用するstd::make_pairをusing指定しています。

CRTP(奇妙に再帰したテンプレートパターン)

仮想関数 (virtual), 実行時型情報(RTTI) が利用できない、かつ利用できるようにしたとしても、パフォーマンス面で難があるため、これに代わる設計手法として CRTP (Curiously recurring template pattern : 奇妙に再帰したテンプレートパターン）を用いています。CRTPは、継承元の親クラスから子クラスのメソッドを呼び出すためのテンプレートパターンです。

以下の例では Base を継承した Derived クラスに interface() というインタフェースを実装する例です。BaseからはDerived::print()メソッドを呼び出しています。

template <class T>
class Base {
public:
  void intrface() {
    T* derived = static_cast<T*>(this);
    derived->prt();
  }
};

class Derived : public class Base<Derived> {
  void prt() {
     // print message here!
     my_print("foo");
  }
}

MWXライブラリで利用されている主要クラスは以下です。

• イベント処理の基本部分mwx::appdefs_crtp

• ステートマシンpublic mwx::processev_crtp

• ストリーム mwx::stream

CRTP での仮想化

CRTPクラスは、継承元のクラスはインスタンスごとに違います。このため、親クラスにキャストして、同じ仲間として取り扱うといったこともできませんし、仮想関数(virtual)やRTTI（実行時型情報）を用いたような高度なポリモーフィズムも使うことが出来ません。

以下は上述のCRTPの例を、仮想関数で実装した例です。CRTPではBase* b[2]のように同じ配列にインスタンスをまとめて管理することは、そのままではできません。

class Base {
	virtual void prt() = 0;
public:
	void intrface() { prt(); }
};

class Derived1 : public Base {
	void prt() { my_print("foo"); }
};

class Derived2 : public Base {
	void prt() { my_print("bar"); }
};

Derived1 d1;
Derived2 d2;
Base* b[2] = { &d1, &d2 };

void tst() {
	for (auto&& x : b) { x->intrface(); }
}

MWXライブラリでは、CRTP のクラスインスタンスを格納するための専用クラスを定義し、このクラスに同様のインタフェースを定義することで解決しています。以下にコード例を挙げます。

class VBase {
public:
	void* p_inst;
	void (*pf_intrface)(void* p);

public:
	void intrface() {
		if (p_inst != nullptr) {
			pf_intrface(p_inst);
		}
	}
};

template <class T>
class Base {
	friend class VBase;
	static void s_intrface(void* p) {
		T* derived = static_cast<T*>(p);
		derived->intrface();
	}
public:
	void intrface() {
		T* derived = static_cast<T*>(this);
		derived->prt();
	}
};

class Derived1 : public Base<Derived1> {
	friend class Base<Derived1>;
	void prt() { my_print("foo"); }
};

class Derived2 : public Base<Derived2> {
	friend class Base<Derived2>;
	void prt() { my_print("bar"); }
};

Derived1 d1;
Derived2 d2;

VBase b[2];

void tst() {
	b[0] = d1;
	b[1] = d2;

	for (auto&& x : b) {
		x.intrface();
	}
}

VBase クラスのメンバ変数 p_inst は、Base <T> 型のオブジェクトへのポインタを格納し、pf_intrfaceは Base<T>::s_intrface へのメンバ関数ポインタです。 Base<T>::s_intrface は、自身のオブジェクトインスタンスを引数として渡され、T型にstatic_castすることでT::intrfaceメソッドを呼び出します。

VBaseへの格納は、ここでは = 演算子のオーバーロードによって実装しています（ソース例は後述）。

上記の例ではb[0].intrface()の呼び出しを行う際には、VBase::pf_intrface関数ポインタを参照しBase<Derived1>::s_intrface()が呼び出されることになります。さらにDerived1::intrface()の呼び出しを行うことになります。この部分はコンパイラによるinline展開が期待できます。

VBase 型から元のDerived1やDerived2への変換を行うことも、強制的なキャストにより可能ですが、void*で格納されたポインタの型を直接知る方法はありません。完全に安全な方法はないものの、以下のようにクラスごとに一意のID(TYPE_ID)を設けて、キャスト実行時(get()メソッド)にIDのチェックを行うようにしています。違う型を指定して get()メソッドを呼び出したときは、エラーメッセージを表示するといった対処になります。

Base<T>型としてのポインタが格納されるとT型に正しく変換できない可能性（Tが多重継承している場合など）あるため、<type_trails>のis_base_ofによりBase<T>型の派生であることをコンパイル時に static_assertによる判定を行っています。

#include <type_trails>

class Derived1 : public Base<Derived1> {
public:
   static const uint8_t TYPE_ID = 1;
}

class Derived1 : public Base<Derived1> {
public:
   static const uint8_t TYPE_ID = 2;
}

class VBase {
  uint8_t type_id;
public:
	
	template <class T>
	void operator = (T& t) {
		static_assert(std::is_base_of<Base<T>, T>::value == true,
						"is not base of Base<T>.");

		type_id = T::TYPE_ID;
		p_inst = &t;
		pf_intrface = T::s_intrface;
	}
	
  template <class T>
  T& get() {
    static_assert(std::is_base_of<Base<T>, T>::value == true,
					  "is not base of Base<T>.");
			
		if(T::TYPE_ID == type_id) {
			return *reinterpret_cast<T*>(p_inst);
		} else {
			// panic code here!
		}
  }
}

Derived1 d1;
Derived2 d2;

VBase b[2];

void tst() {
	b[0] = d1;
	b[1] = d2;
	
  Derived1 e1 = b[0].get<Derived1>(); // OK
  Derived2 e2 = b[1].get<Derived2>(); // OK
  
  Derived2 e3 = b[1].get<Derived1>(); // PANIC!
}

new, new[] 演算子

TWELITEモジュールのマイコンには十分なメモリもなければ、高度なメモリ管理もありません。しかしマイコンのメモリマップの末尾からスタックエリアまでの領域はヒープ領域として、必要に応じて確保できる領域があります。以下にメモリマップの概要を図示します。APPがアプリケーションコードで確保されたRAM領域、HEAPはヒープ領域、STACKはスタック領域です。

|====APP====:==HEAP==..   :==STACK==|
0                                  32KB

たとえdeleteできなくてもnew演算子が有用である場面も想定されます。そのため、以下のようにnew, new[]演算子を定義しています。pvHear_Alloc()は半導体ライブラリで提供されているメモリ確保の関数で、u32HeapStart, u32HeapEndも同様です。0xdeadbeefはダミーアドレスです。beefがdeadなのは変だとかいう指摘はしないでください。

void* operator new(size_t size) noexcept {
    if (u32HeapStart + size > u32HeapEnd) {
        return (void*)0xdeadbeef;
    } else {
        void *blk = pvHeap_Alloc(NULL, size, 0);   
        return blk;
    }
}
void* operator new[](size_t size) noexcept {
    return operator new(size); }
void operator delete(void* ptr) noexcept {}
void operator delete[](void* ptr) noexcept {}

例外も使えないため失敗したときの対処はありません。また、メモリ容量を意識せず確保を続けた場合、スタック領域と干渉する可能性もあります。

コンテナクラス

MWXライブラリでは、マイコンのリソースが小さい点、メモリーの動的確保ができない点を考慮し標準ライブラリで提供されるコンテナクラスの利用はせず、シンプルなコンテナクラスを２種類定義しています。コンテナクラスにはイテレータやbegin(), end()メソッドを定義しているため、範囲for文やSTLのアルゴリズムの一部を利用できます。

smplbuf<int16_t, alloc_local<int16_t, 16>> buf;
buf.push_back(-1); // push_back() は末尾に追加
buf.push_back(2);
...
buf.push_back(10);

//範囲for文
for(auto&& x : buf) { Serial << int(x) << ',' }
//アルゴリズム std::minmax
auto&& minmax = std::minmax_element(buf.begin(), buf.end());
Serial << "Min=" << int(*minmax.first)
       << ",Max=" << int(*minmax.second);

コンテナクラスのメモリについて

コンテナクラスではメモリの確保方法をtemplate引数のパラメータとして指定します。

可変数引数

MWXライブラリでは、バイト列やビット列の操作、printf相当の処理を行う処理に可変数引数を用いています。下記の例は指定のビット位置に1をセットする処理です。

// packing bits with given arguments, which specifies bit position.
//   pack_bits(5, 0, 1) -> (b100011) bit0,1,5 are set.

// 再帰取り出しの一番最初の関数
template <typename Head>
constexpr uint32_t pack_bits(Head head) { return  1UL << head; }

// head を取り出し、残りのパラメータを再帰呼び出しにて pack_bits に転送
template <typename Head, typename... Tail>
constexpr uint32_t pack_bits(Head head, Tail&&... tail) {
  return (1UL << head) | pack_bits(std::forward<Tail>(tail)...);
}

// コンパイル後、以下の２つは同じ結果になります。
constexpr uint32_t b1 = pack_bits(1, 4, 0, 8);
// b1 and b2 are the same! 
const uint32_t b2 = (1UL << 1)|(1UL << 4)|(1UL << 0)|(1UL << 8);

この処理では template のパラメータパック (typename... の部分) で、再帰的な処理を行い引数の展開を行っています。上記の例ではconstexprの指定があるため、コンパイル時に計算が行われマクロ定義やb2のようなconst値の指定と同等の結果になります。また変数を引数として動的に計算する関数としても振る舞うこともできます。

以下の例では、expand_bytes関数により、受信パケットのデータ列からローカル変数に値を格納しています。パラメータパックを用いた場合各引数の型を把握できるため、下記のように、受信パケットのバイト列から、サイズや異なる型にあった値を格納することができます。

auto&& rx = the_twelite.receiver.read(); // 受信パケット

// 展開後のパケットの内容を格納する変数
// パケットのペイロードはバイト列で以下のように並んでいる。
//   [B0][B1][B2][B3][B4][B5][B6][B7][B8][B9][Ba][Bb]
//   <message       ><adc*  ><vcc*  ><timestamp*    >
//   * 数値型はビッグエンディアン並び
uint8_t msg[MSG_LEN];
uint16_t adcval, volt;
uint32_t timestamp;

// expand packet payload
expand_bytes(rx.get_payload().begin(), rx.get_payload().end()
		, msg       // 4bytes of msg
		, adcval    // 2bytes, A1 value [0..1023]
	  , volt      // 2bytes, Module VCC[mV]
	  , timestamp // 4bytes of timestamp
);

イテレータ

イテレータはポインタの抽象化で、例えばメモリの連続性のないようなデータ構造においても、あたかもポインタを使ったようにデータ構造にアクセスできる効果があります。

smplque<uint8_t, alloc_local<uint8_t, 5> > que;
que.push('a'); que.push('b'); que.pop(); que.push('c'); ...

auto&& p = que.begin();
auto&& e = que.end();

while(p != e) { // pがeまで進んだ＝全要素処理した
  Serial << *p;
  ++p; // イテレータのインクリメントは前置演算子を使います。
  　　　// この場合、p++ と記述すると、コンパイラによる最適化が行われる可能性は
       // 高いものの、コード上はイテレータのコピーが発生します。
}

#include <algorithm>
#include <cctype>

// ラムダ式による文字変換
std::for_each(que.begin(), que.end(), 
  [](uint8_t& x) { x = std::toupper(x); });

// 範囲for文
for (uint8_t x : que) {
  Serial << x;
}

以下の例では、通常のポインタでは連続的なアクセスができないFIFOキューのイテレータ、さらに、FIFOキューの構造体の特定メンバー(例ではX軸)のみを抽出するイテレータを利用する例です。

// XYZTの４軸構造体を要素とする要素数５のキュー
smplque<axis_xyzt, alloc_local<axis_xyzt, 5> > que;

// テスト用にデータを投入
que.push(axis_xyzt(1, 2, 3, 4));
que.push(axis_xyzt(5, 2, 3, 4));
...

// 構造体としてのイテレータを用いたアクセス
for (auto&& e : v) { Serial << int(e.x) << ','; }

// キューの中の X 軸を取り出す
auto&& vx = get_axis_x(que);
// X軸のイテレータを用いたアクセス
for (auto&& e : vx) { Serial << int(e) << ','; }

// int16_t要素のイテレータなので、STLのアルゴリズム（最大最小）が使える
auto&& minmax = std::minmax_element(vx.begin(), vx.end());

以下は smplque クラスのイテレータの実装の抜粋です。このイテレータでは、キューオブジェクトの実体と、インデックスにより管理しています。キューのメモリが不連続になる（末尾の次は先頭を指す必要があるリングバッファ構造）部分はsmplque::operator []で解決しています。オブジェクトのアドレスが一致することとインデックスが一致すればイテレータは同じものを指していることになります。

この実装部分には <iterator> が要求する typedef なども含まれ、より多くのSTLのアルゴリズムが適用できるようになります。

class iter_smplque {
	typedef smplque<T, alloc, INTCTL> BODY;

private:
	uint16_t _pos; // index
	BODY* _body;   // point to original object

public: // for <iterator>
	typedef iter_smplque self_type;
	typedef T value_type;
	typedef T& reference;
	typedef T* pointer;
	typedef std::forward_iterator_tag iterator_category;
	typedef int difference_type;

public: // pick some methods
	inline reference operator *() {
		return (*_body)[_pos];
	}
	
	inline self_type& operator ++() {
		_pos++;
		return *this;
	}
};

構造体を格納したコンテナ中の、特定構造体メンバーだけアクセスするイテレータは少々煩雑です。構造体のメンバーにアクセスするメンバー関数を予め定義しておきます。このメンバー関数をパラメータ（R& (T::*get)()）としたテンプレートを定義します。Iterはコンテナクラスのイテレータ型です。

struct axis_xyzt {
    int16_t x, y, z;
    uint16_t t;
    int16_t& get_x() { return x; }
    int16_t& get_y() { return y; }
    int16_t& get_z() { return z; }
};

template <class Iter, typename T, typename R, R& (T::*get)()>
class _iter_axis_xyzt {
    Iter _p;
    
public:
    inline self_type& operator ++() {
        _p++;
        return *this; }

    inline reference operator *() {
        return (*_p.*get)(); }
};

template <class Ixyz, class Cnt>
class _axis_xyzt_iter_gen {
    Cnt& _c;
    
public:
    _axis_xyzt_iter_gen(Cnt& c) : _c(c) {}
    Ixyz begin() { return Ixyz(_c.begin()); }
    Ixyz end() { return Ixyz(_c.end()); }
};

// 長いので using で短縮
template <typename T, int16_t& (axis_xyzt::*get)()>
using _axis_xyzt_axis_ret = _axis_xyzt_iter_gen<
    _iter_axis_xyzt<typename T::iterator, axis_xyzt, int16_t, get>, T>;

// X 軸を取り出すジェネレータ
template <typename T>
_axis_xyzt_axis_ret<T, &axis_xyzt::get_x>
get_axis_x(T& c) {
    return _axis_xyzt_axis_ret<T, &axis_xyzt::get_x>(c);
}

値にアクセスするoperator *この上述のメンバー関数を呼び出しています。（*_pはaxis_xyzt構造体で、(*_p.*get)()は、T::*getに&axis_xyzt::get_xを指定した場合_p->get_x()を呼び出します）

_axis_xyzt_iter_genクラスはbegin(), end()のみを実装し、上記のイテレータを生成します。これで範囲for文やアルゴリズムが利用できるようになります。

このクラス名は非常に長くなりソースコード中に記述するのは困難です。このクラスを生成するためのジェネレータ関数を用意します。下記の例では末尾の行の get_axis_x() です。このジェネレータ関数を用いることで冒頭のようなauto&& vx = get_axis_x(que);といった簡潔な記述になります。

また、この軸だけを抽出するイテレータは、配列型のsmplbufクラスでも同様に利用できます。

割り込み・イベント・状態ハンドラの実装

ユーザ定義クラスによりアプリケーション動作を記述するため、代表的なハンドラは必須メソッドとして定義が必要ですが、それ以外に多数ある割り込みハンドラ、イベントハンドラ、ステートマシンの状態ハンドラをすべて定義するのは煩雑です。ユーザが定義したものだけ定義され、それのみのコードが実行されるのが理想です。

class my_app_def {
public: // 必須メソッドの定義
	void network_event(twe::packet_ev_nwk& pEvNwk) {}
	void receive(twe::packet_rx& rx) {}
	void transmit_complete(twe::packet_ev_tx& pEvTx) {}
	void loop() {}
	void on_sleep(uint32_t& val) {}
	void warmboot(uint32_t& val) {}
	void wakeup(uint32_t& val) {}
	
public: // これらを必須記述とするのは煩雑
  // DIO割り込みハンドラ 20種類ある
  // DIOイベントハンドラ 20種類ある
  // タイマー割り込みハンドラ 5種類ある
  // タイマーイベントハンドラ 5種類ある
  // ...
}

MWXライブラリでは、数の多い DIO割り込みハンドラ（TWELITEハード上は単一の割り込みですが、利用しやすさのためDIO一つずつにハンドラを割り当てることにしました）などを、テンプレートによる空のハンドラーとして定義した上、ユーザ定義のメンバー関数をそのテンプレートの特殊化することにより定義する手法を採用しました。

// hpp file
class my_app_def : class app_defs<my_app_def>, ... {
  // 空のハンドラ
  template<int N> void int_dio_handler(uint32_t arg, uint8_t& handled) { ; }

  ...   
  // 12番だけ実装する
  
public:
  // TWENET から呼び出されるコールバック関数
  uint8 cbTweNet_u8HwInt(uint32 u32DeviceId, uint32 u32ItemBitmap);
};

// cpp file
template <>
void my_app_def::int_dio_handler<12>(uint32_t arg, uint8_t& handled) {
  digitalWrite(5, LOW);
  handled = true;
  return;
}

void cbTweNet_u8HwInt(uint32 u32DeviceId, uint32 u32ItemBitmap) {
  uint8_t b_handled = FALSE;
  switch(u32DeviceId) {
  	case E_AHI_DEVICE_SYSCTRL:
      if (u32ItemBitmap & (1UL << 0)){int_dio_handler<0>(0, b_handled);}
      if (u32ItemBitmap & (1UL << 1)){int_dio_handler<1>(1, b_handled);}
      ...
      if (u32ItemBitmap & (1UL << 12)){int_dio_handler<12>(12, b_handled);}
      ...
      if (u32ItemBitmap & (1UL << 19)){int_dio_handler<19>(19, b_handled);}
    break;
  }
}

実際のユーザ記述コードは、マクロ化やヘッダファイルのインクルードを行うことで、簡素化されていますが、上記は解説のために必要なコードを含めています。

TWENETからの割り込みハンドラからmy_app_def::cbTweNet_u8HwInt() が呼び出されます。cppファイル中では、int_dio_handler<12>のみが特殊化されて記載された内容でインスタンス化されます。12番以外はhppファイル中のテンプレートからインスタンス化されます。結局以下のように展開されることになります。

  	case E_AHI_DEVICE_SYSCTRL:
      if (u32ItemBitmap & (1UL << 0)){;}
      if (u32ItemBitmap & (1UL << 1)){;}
      ...
      if (u32ItemBitmap & (1UL << 12)){
          int_dio_handler<12>(12, b_handled);}
      ...
      if (u32ItemBitmap & (1UL << 19)){;}
      break;
      
    // ↓　↓　↓
    
    // 結局、このように最適化されることが期待できる。
   	case E_AHI_DEVICE_SYSCTRL:
      if (u32ItemBitmap & (1UL << 12)){
        // int_dio_handler<12> もinline展開
        digitalWrite(5, LOW);
        handled = true;
      }
      break;
    

最終的に、コンパイラの最適化により12番以外のコードは無意味と判断されコード中から消えてしまうことが期待できます（ただし、上記のように最適化されることを保証するものではありません）。

つまりユーザコード上では12番の割り込み時の振る舞いを定義したいときはint_dio_handler<12> を記述するだけで良い、ということになります（注：DIO割り込みを有効にするには attachInterrupt() を呼び出す必要があります）。登録しないハンドラはコンパイル時の最適化により低コストな呼び出しで済むことが期待できます。

// mwx_appcore.cpp
void wakeup() __attribute__((weak));
void wakeup() { }

Streamクラス

ストリームクラスは、主にUART(シリアルポート)の入出力に用います。MWXライブラリでは、出力用の手続きを主に定義しています。一部入力用の定義もあります。

ここでは派生クラスが必要とする実装について解説します。

template <class D>
class stream {
protected:
	void* pvOutputContext; // TWE_tsFILE*
public:
  inline D* get_Derived() { return static_cast<D*>(this); }
	inline D& operator << (char c) {
		get_Derived()->write(c);
		return *get_Derived();
	}
};

class serial_jen : public mwx::stream<serial_jen> {
public:
 	inline size_t write(int n) {
		return (int)SERIAL_bTxChar(_serdef._u8Port, n);
	}
};

上記は1文字書き出すwrite()メソッドの実装です。親クラスのstream<serial_jen>からはキャストを実行するget_Drived()メソッドを用いて、serial_jen::write()メソッドにアクセスしています。

必要に応じて write(), read(), flush(), available() といったメソッドを定義します。

書式出力にはMarco Paland氏によるprintfライブラリを利用しています。MWXライブラリから利用するための実装が必要になります。下記の例で派生クラスのserial_jenで必要なことは1バイト出力のための vOutput() メソッドを定義することと、vOutput()がstaticメソッドであるため出力のための補助情報を親クラスのpvOutputContextに保存することです。

template <class D>
class stream {
protected:
	void* pvOutputContext; // TWE_tsFILE*
public:
	inline tfcOutput get_pfcOutout() { return get_Derived()->vOutput; }
	
	inline D& operator << (int i) {
		(size_t)fctprintf(get_pfcOutout(), pvOutputContext, "%d", i);
		return *get_Derived();
	}
};

class serial_jen : public mwx::stream<serial_jen> {
	using SUPER = mwx::stream<serial_jen>;
	TWE_tsFILE* _psSer; // シリアル出力のためのローレベル構造体
public:
  void begin() {
    SUPER::pvOutputContext = (void*)_psSer;
  }
  
	static void vOutput(char out, void* vp) {
		TWE_tsFILE* fp = (TWE_tsFILE*)vp;
		fp->fp_putc(out, fp);
	}
};

get_pfcOutput()により、派生クラスで定義したvOutput()関数を指定し、そのパラメータとしてpvOutputContextが渡されます。上記の例では<<演算子がint型で呼び出されたときserial_jen::vOutput()とUART用に設定済みのTWE_tsFILE*をfctprintf()関数に渡しています。

Wire, SPIのワーカーオブジェクト

Wireクラスでは、2線デバイスとの送信・受信時に、通信開始から終了までを管理する必要があります。ワーカーオブジェクトを利用する記述について内容を記述します。

if (auto&& wrt = Wire.get_writer(SHTC3_ADDRESS)) {
	Serial << "{I2C SHTC3 connected.";
	wrt << SHTC3_TRIG_H;
	wrt << SHTC3_TRIG_L;
	Serial << " end}";
}

periph_twowire::writer クラスの抜粋です。streamインタフェースを実装するために mwx::stream<writer> を継承しています。steamインタフェースを利用するために write() と vOutput()メソッドの実装を行っています。

コンストラクタでは2線シリアルの通信開始を、デストラクタで通信終了のメソッドを呼び出しています。また、operator bool()演算子では、2線シリアルのデバイスの通信開始に成功した場合 true を返すようになっています。

class periph_twowire {
public:
	class writer : public mwx::stream<writer> {
		friend class mwx::stream<writer>;
		periph_twowire& _wire;
	
	public:
		writer(periph_twowire& ref, uint8_t devid) : _wire(ref) {
	  	_wire.beginTransmission(devid); // コンストラクタで通信開始
		}
	
		~writer() {
			_wire.endTransmission(); // デストラクタで通信終了
		}
	
		operator bool() {
			return (_wire._mode == periph_twowire::MODE_TX);
		}
	
	private: // stream interface
		inline size_t write(int n) {
			return _wire.write(val);
		}
	
		// for upper class use
		static void vOutput(char out, void* vp) {
			periph_twowire* p_wire = (periph_twowire*)vp;
			if (p_wire != nullptr) {
				p_wire->write(uint8_t(out));
			}
		}
	};
	
public:
	writer get_writer(uint8_t address) {
		return writer(*this, address);
	}
};
class periphe_twowire Wire; // global instance

// ユーザコード
if (auto&& wrt = Wire.get_writer(SHTC3_ADDRESS)) {
	Serial << "{I2C SHTC3 connected.";
	wrt << SHTC3_TRIG_H;
	wrt << SHTC3_TRIG_L;
	Serial << " end}";
}

get_writer()メソッドによりオブジェクトwrtを生成します。この時にオブジェクトのコピーは通常発生しません。C++コンパイラのRVO(Return Value Optimization)という最適化により、writerはwrtに直接生成されるためコピーは発生せず、コンストラクタで実行されているバスの初期化を多重に行ったりすることはありません。ただしRVOはC++の仕様では保証されておらず、念のためMWXライブラリ中ではコピー、代入演算子の削除、moveコンストラクタを定義しています（moveコンストラクタが評価される可能性はないと考えられますが）。

if節の中の wrtは、まずコンストラクタにより初期化され同時に通信開始します。通信開始でエラーがなければ、条件判定時のbool演算子がtrueを返し、if節スコープ内の処理が行われます。スコープを脱出するとデストラクタにより、2線シリアルバスの利用終了処理を行います。通信の相手先がない場合は falseが戻り、wrtオブジェクトは破棄されます。

Wire, SPI特有の定義としてoperator << (int)の定義をオーバーライドしています。ストリームのデフォルトの振る舞いは、数値を文字列に変換して出力するのですが、WireやSPIで数値文字列をバスに書き込むことは稀で、反対に設定値など数値型のリテラルをそのまま入力したいことが多いのですが、数値型リテラルは多くの場合int型として評価されるため、この振舞を変更します。

			writer& operator << (int v) {
				_wire.write(uint8_t(v & 0xFF));
				return *this;
			}

ここではint型の値については8bitに切り詰めて、その値を出力しています。

他のプラットフォームでも一部の機能(serparser, pktparser, コンソール用Serialオブジェクト)をビルドできるように、ビルド定義を用意しています。必要なファイルのみを切り出しています。

ビルド定義は{mwxライブラリ格納}/stdioフォルダに格納しています。ビルド方法はREADME.md(リンクはGitHub上)を参照してください。

• C++11でのコンパイルが出来ること。

• C++11の標準ライブラリヘッダが利用できること (utility, algorithm, functional, iteratorなど)

• new/delete/virtualは使用しません。

• newによるメモリ確保は例外的に使用する場合があります。

  • serparser/pktparserでnew演算子を利用するalloc_heapではdeleteによる処理を行っています。

  • （参考） ただしmwxライブラリとしてはdeleteについては考慮しない前提で設計されている部分もあります。

act0 から始まるアクト(Act)は、actを始める - Opening actで紹介されたものを収録しています。LEDやボタンの動作のみの単純なものですが、最初にお試しいただくことをお勧めします。

テンプレートコードです。

setup()

void setup() {
	/*** SETUP section */
	tx_busy = false;

	// the twelite main class
	the_twelite
		<< TWENET::appid(APP_ID)    // set application ID (identify network group)
		<< TWENET::channel(CHANNEL) // set channel (pysical channel)
		<< TWENET::rx_when_idle();  // open receive circuit (if not set, it can't listen packts from others)

	// Register Network
	auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
	nwk	<< NWK_SIMPLE::logical_id(0xFE); // set Logical ID. (0xFE means a child device with no ID)

	/*** BEGIN section */
	Buttons.begin(pack_bits(PIN_BTN), 5, 10); // check every 10ms, a change is reported by 5 consequent values.

	the_twelite.begin(); // start twelite!

	/*** INIT message */
	Serial << "--- Scratch act ---" << mwx::crlf;
}

the_tweliteを設定してアプリケーションID APP_ID, 無線チャネルCHANNEL、受信有を設定します。

またnwkを生成し、子機アドレス0xFEを指定しています。このアドレスは子機でアドレスを指定していない名無しの子機という意味です。

またButtonsオブジェクトを初期化します。連続参照によるチャタリング抑制アルゴリズムです。10msごとに5回連続同じ値になれば対象のポート(PIN_BTNのみ)のHIまたはLOWを確定します。pack_bits(N1, N2, ..)は1UL<<N1 | 1UL << N2 | ...を行いビットマップを生成します。

the_twelite.begin(); // start twelite!

the_tweliteを開始するための手続きです。act0..4では出てきませんでしたがthe_tweliteの設定や各種ビヘイビアの登録を行った場合は、必ず呼び出すようにしてください。

begin()

void begin() {
	Serial << "..begin (run once at boot)" << mwx::crlf;
}

始動時setup()の後に１回だけ呼び出されます。メッセージの表示のみ。

loop()

ボタン（スイッチ）の入力検出

if (Buttons.available()) {
	uint32_t bm, cm;
	Buttons.read(bm, cm);

	if (cm & 0x80000000) {
		// the first capture.
	}

	Serial << int(millis()) << ":BTN" << format("%b") << mwx::crlf;
}

Buttonsによる連続参照により状態を確定します。ボタン状態が変化したらシリアルに出力します。

シリアルからの入力

while(Serial.available()) {
  int c = Serial.read();

	Serial << '[' << char(c) << ']';

  switch(c) {
  case 'p': ... // millis() を表示
  case 't': ... // 無線パケットを送信 (vTransmit)
        if (!tx_busy) {
					tx_busy = Transmit();
					if (tx_busy) {
						Serial  << int(millis()) << ":tx request success! (" 
										<< int(tx_busy.get_value()) << ')' << mwx::crlf;
 					} else {
						Serial << int(millis()) << ":tx request failed" << mwx::crlf;;
					}
				}
  case 's': ... // スリープする
				Serial << int(millis()) << ":sleeping for " << 5000 << "ms" << mwx::crlf << mwx::flush;
				the_twelite.sleep(5000);
				break;
  }
}

Serial.available()が_true_の場合は、シリアルポートからの入力が保存されています。シリアルから１文字読み込んで、入力文字に応じた処理をします。

tを入力して無線送信

't'を入力したときは送信を行います。このサンプルではtx_busyフラグを用い連続的に入力は行わないようにしています。

--- Scratch act ---
..begin (run once at boot)
[t]11591:Transmit()
11592:tx request success! (1)
[t]11593:Transmit()
11593:tx request success! (2)
[t]11594:Transmit()
11595:tx request success! (3)
[t]11595:Transmit()
TX QUEUE is FULL
11596:tx request failed
11654:tx completed!(id=2, stat=1)
11719:tx completed!(id=3, stat=1)
11745:tx completed!(id=1, stat=1)

sを入力してスリープ

the_twelite.sleep(5000);

5000ms=5秒のスリープを実施します。復帰後はwakeup()が実行されます。

wakeup()

void wakeup() {
	Serial << int(millis()) << ":wake up!" << mwx::crlf;
}

スリープ起床時に最初に呼び出されます。メッセージの表示のみ。

Transmit()

MWX_APIRET Transmit() {
	Serial << int(millis()) << ":Transmit()" << mwx::crlf;

	if (auto&& pkt = the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet()) {
		// set tx packet behavior
		pkt << tx_addr(0xFF)  // 同報通信＝ブロードキャスト
			<< tx_retry(0x1)    // 再送１回
			<< tx_packet_delay(100,200,20); // 送信時遅延100-200msの間に送信、再送間隔20ms

		// 送信データの指定（アプリケーションごとに決める）
		pack_bytes(pkt.get_payload()
			, make_pair("SCRT", 4) // ４文字識別子
			, uint32_t(millis())   // タイムスタンプ
		);
		
		// 送信要求を行う
		return pkt.transmit(); 
	} else {
		// .prepare_tx_packet() 時点で失敗している(送信キューが一杯)
		Serial << "TX QUEUE is FULL" << mwx::crlf;
	  return MWX_APIRET(false, 0);
	}
}

送信要求を行う最小限の手続きです。

この関数を抜けた時点では、まだ要求は実行されていません。しばらく待つ必要があります。この例では100-200msの送信開始の遅延を設定しているため、送信が開始されるのは早くて100ms後です。

on_tx_comp()

void on_tx_comp(mwx::packet_ev_tx& ev, bool_t &b_handled) {
	Serial 	<< int(millis()) << ":tx completed!"
			<< format("(id=%d, stat=%d)", ev.u8CbId, ev.bStatus) << mwx::crlf;
	tx_busy = false; // clear tx busy flag.
}

送信完了時に呼び出されます。evには送信IDと完了ステータスが含まれます。

on_rx_packet()

void on_rx_packet(packet_rx& rx, bool_t &handled) {
	Serial << format("rx from %08x/%d", 
					rx.get_addr_src_long(), rx.get_addr_src_lid()) << mwx::crlf;
}

パケットを受信したら、送信元のアドレス情報を表示します。

アクトの動作を理解するため、いくつかのサンプルを用意しています。

サンプルアクトの紹介

以下には、目的別のアクトを紹介します。

無線通信を行わなず、マイコン機能のみの短いアクト

• act0..4は、無線機能などを使わないごくシンプルな例です。Actの基本構造が理解できます。

I2C センサーを用いたアクトの記述例

I2Cセンサーを接続し、スリープによる簡潔動作を行いながら無線パケットを送信する、無線センサーの実装例です。比較的簡潔、かつ、代表的な構造ですので、act0～act4を確認後に参照することを推奨します。

• BRD_I2C_TEMPHUMID

TWELITE で無線センサーを実装するための代表的な要素（シンプル中継ネット <NWK_SIMPLE> の利用・インタラクティブモード <STG_STD>、I2Cセンサーの取り扱い Wire、スリープによる間欠動作など）が含まれます。

無線通信を行う基本的なアクト

無線パケットを送信、または送受信するサンプルですが、各々少し違った視点で実装されています。

• Scratch は、UARTから１バイトコマンドを受けて、送信などを行うシンプルなコードです。

• Slp_Wk_and_Txは、ステートマシンを用い、スリープを用いた間欠動作で、スリープ復帰→無線送信→スリープを繰り返します。

• PingPongは、一方から他方にパケットを送信し、受信した他方がパケットを送り返すサンプルです。送信と受信についての基本的な手続きが含まれます。

• WirelessUARTは、UART入力をserparserを用いアスキー形式を解釈し、これを送信します。

親機側のアクト

独自の受信側親機アプリケーションを実装するときに参照してください。

• Parent_MONOSTICKは、専ら受信のみを行い、シリアルポートへ受信結果を出力します。このサンプルの無線パケットで、親機向け(0x00)や子機ブロードキャスト(0xFE)とアドレス設定しているものは受信できます。またインタラクティブモード<STG_STD>をActに追加するための手続きが含まれます。

• Rcv_Univsl はユニバーサルパケットレシーバ (TWENETレイヤーツリーネットワーク, App_Twelite, Act, ... など) のサンプルコードです。また、コンテナやアルゴリズムにEASTLライブラリを使用しています。

インタラクティブモードを追加するためのアクト

インタラクティブモードを使用するアクトの解説には大まかな流れを記しています（ここでは上述の BRD_I2C_TEMPHUMID を引用します）。どのサンプルの解説も大きな差はありません。

• BRD_I2C_TEMPHUMIDは、I2Cセンサーデバイスの読み書きコマンドを実行し I2C センサーから得られた計測値を無線送信します。またインタラクティブモード<STG_STD>をActに追加するための手続きが含まれます。

• Settings は、インタラクティブモード<STG_STD>のより高度なカスタマイズを行います。詳細はコードを参照ください。

センサーなどのデバイスを動作させるためのアクト

内蔵ペリフェラルや外部センサーデバイスからセンサー情報を得るサンプルです。

• BRD_APPTWELITEはディジタル入力、アナログ入力、ディジタル出力、アナログ出力を用いた双方向通信を行っています。またインタラクティブモード<STG_STD>をActに追加するための手続きが含まれます。

• BRD_I2C_TEMPHUMIDは、I2Cセンサーデバイスの読み書きコマンドを実行し I2C センサーから得られた計測値を無線送信します。またインタラクティブモード<STG_STD>をActに追加するための手続きが含まれます。

• PulseCounter は、パルスカウンター機能を用い、スリープ中も含め入力ポートで検出したパルス数を計数し、これを無線送信します。

• PAL_AMB_behavior は、ビヘイビアを用いた例です。PAL_AMBでは温湿度センサーはライブラリ内部のコードが呼ばれますが、このサンプルでは温湿度センサーのアクセスのための独自の手続きも含まれます。

TWELITE PAL を使用するためのアクト

TWELITE PAL には標準的なPALアプリが書き込まれていますが、PALアプリを用いずアクトによる記述を行うことができます。MWXライブラリには、PALで使用するセンサーを動作させるための標準的な手続きが用意されています。

各種PAL基板用のサンプルです。PAL基板上のセンサー値を取得し、送信し、スリープします。

• PAL_AMB

• PAL_MOT-single

• PAL_MAG

以下は応用例で、上記のアクトより少し複雑な記述になっています。

• PAL_AMB_usenap は、数十msかかるセンサーの動作時間にTWELITEマイコンを短くスリープさせ、より省電力を目指すサンプルです。

• PAL_AMB_behavior は、ビヘイビアを用いた例です。PAL_AMBでは温湿度センサーはライブラリ内部のコードが呼ばれますが、このサンプルでは温湿度センサーのアクセスのための独自の手続きも含まれます。

• PAL_MOT_fifo は、加速度センサーのFIFOおよびFIFOの割り込みを用いて、サンプルを中断することなく、連続的に取得し無線送信するためのサンプルです。

TWELITE CUE を使用するためのアクト

PAL_MOT 用のアクトが利用できます。小修整が必要な場合があります。

• PAL_MOT-single

• PAL_MOT_fifo は、加速度センサーのFIFOおよびFIFOの割り込みを用いて、サンプルを中断することなく、連続的に取得し無線送信するためのサンプルです。

TWELITE ARIA を使用するためのアクト

• [BRD_ARIA] は、TWELITE ARIA を動作させるためのアクトです。

• BRD_I2C_TEMPHUMID は、I2C センサー利用のためのテンプレートですが、実装例として TWELITE ARIA で利用する SHT40 センサー用のコードが含まれます。

• PAL_AMB 用のアクトを小修整することで利用可能です。

単体機能を紹介したAct

Unitから始まる名前のActは機能やAPIの紹介を目的としています。

最新版の入手

共通の記述

アクトのサンプル中で以下の項目は共通の設定項目になり、以下で解説します。

const uint32_t APP_ID = 0x1234abcd;
const uint8_t CHANNEL = 13;
const char APP_FOURCHAR[] = "BAT1";

MWXライブラリで記述したアプリケーションプログラムをアクト(Act)と呼びます。まずは、これをビルドして書き込みます。

• ビルドフォルダ構成について

• Visual Studio Code (VSCodeと記載) でのビルドについて

ビルドフォルダ構成について

MWSDKをインストールしたフォルダMWSDK_ROOT (例 C:\MWSDK)を開きます。以下のような構成になっています。

MWSDK_ROOT
  |
  +-ChipLib      : 半導体ライブラリ
  +-License      : ソフトウェア使用許諾契約書
  +-MkFiles      : makefile
  +-Tools        : コンパイラ等のツール一式
  +-TWENET       : TWENET/MWXライブラリ
  +-Act_samples  : アクトサンプル
  ...

アクトファイルはAct_samples 以下に格納しています。（以下は一部割愛しています）

Act_samples
  |
  +-CoreAppTwelite    : App_TweLiteと同じ構成のボード用のアクト
  +-PAL_AMB           : 環境センス PAL 用のアクト
  +-PAL_MAG           : 開閉センス PAL 用のアクト
  +-PAL_MOT           : 動作センス PAL 用のアクト
  ..
  +-Parent-MONOSTICK  : 親機アクト、MONOSTICK用
  +-PingPong          : PingPong アクト
  +-PulseCounter      : パルスカウンタを利用したアクト
  +-act0              : スクラッチ（とりあえず書いてみる）用アクト

これらのアクトは、MWXライブラリの記述の参考となるシンプルな例ですが、多くのアクトは以下の機能を有しています。

• センサー値を取得する

• センサー値取得後、無線パケットを親機宛に送信する

• 送信完了後、一定時間スリープする（または割り込みを待つ）

Parent-MONOSTICKのアクトによりパケットの受信と表示を行っています。この親機用のアクトは、アスキー形式で出力しています。 (:00112233AABBCC...FF[CR][LF] のような : で始まり、途中は１６進数のバイトをアスキー文字2字で表現する形式です。末尾の??は同様に2字のバイトとなりますがLRCというチェックサムバイトになります。参考：アスキー形式)

実際に動作させてみるときは、以下の組み合わせを試してみてください。

では、アクトの中から PingPong のフォルダの中を見てみましょう。

Act_samples
  +-PingPong
    +-PingPong.cpp   : アクトファイル
    +-build          : ビルドフォルダ
    +-.vscode        : VSCode 用の設定ファイル

必ずフォルダ直下にフォルダと同名の .cpp ファイルが必要です。

次にビルドフォルダを開きます。

Act_samples
  +-PingPong
    +-build
      +-Makefile        : makefile
      +-build-BLUE.cmd  : TWELITE BLUE 用ビルドスクリプト(Windows用)
      +-build-RED.cmd   : TWELITE RED 用ビルドスクリプト(Windows用)
      +-build-clean.cmd : obj_* ファイル削除

ビルドに必要なスクリプトとMakefileが格納されています。

このMakefile のあるフォルダで make TWELITE={BLUEまたはRED} を実行することで、ビルドが行われます。VSCode でのビルドも同様で内部的に make を呼び出します。

TWELITE STAGE アプリでのビルド

TWETLITE STAGE アプリを用いて、ビルドから書き込み、実行までを行えます。ここでは、TWELITE STAGE アプリの起動からビルドまでを解説します。

0. TWELITE の接続

MONOSTICKまたはTWELITE Rをお使いのUSBポートに接続します。

1. TWELITE STAGE アプリの起動

{TWELITE SDK インストール} フォルダにある実行形式 TWELITE_Stage.{拡張子} を起動します(参考: TWELITE STAGE アプリマニュアル-使用法)。

以下は、TWELITE STAGE アプリ動作中の画面例です。左側の主画面とコマンドプロンプト画面がありますが、主画面を操作します。コマンドプロンプト画面は通常使用しませんが、諸情報及びTWELITEマイコンシリアルポートからの入力データが表示されます。

主画面での主な操作は以下です。

• マウス左クリック （選択）

• マウス右ダブルクリック（前の画面に戻る）

• 素早く ESC を２回, 一部画面では ESC １回 （前の画面に戻る）

• Alt(Cmd) キーを押し続ける（ヘルプ画面）

• 通常キーボード入力（画面に従う）

(参考: TWELITE STAGE アプリマニュアル-キー操作・マウス操作)。

2. シリアルポートの選択

TWELITE STAGE アプリを起動すると最初に表示される画面です。事前に TWELITE R や MONOSTICK を接続しておけば、この画面に列挙されます。この画面で操作したい TWELITE を選択します。この画面で選択せずに、別の操作で選択することも可能です。

(参考: TWELITE STAGE アプリマニュアル)

3. メインメニュー

シリアルポート選択画面を抜けると、メインメニューが表示されます。ビルドや書込は「アプリ書換」メニューを選択します。

(参考: TWELITE STAGE アプリマニュアル)

4. アプリ書換メニュー

アプリ書換メニューを選択する前に、TWELITE の接続とシリアルポートの選択を確認しておいてください。シリアルポートの選択状況は Alt(Cmd) キーを押し続けると出現するヘルプ画面上で確認できます。

TWELITE STAGE アプリから参照できるプロジェクトはいくつかに分類されています。右側のﾍﾙﾌﾟは関連情報をブラウザで表示します。ﾌｫﾙﾀﾞはプロジェクトのあるフォルダを表示します。

TWELITE が接続済みであれば、メニューを選択したときに、TWELITE のモデルが判定されます。（TWELITE STAGE アプリ内部では、この判定したTWELITEモデルに応じたビルドを行うようになっています）。

(参考: TWELITE STAGE アプリマニュアル)

4. プロジェクトの選択

ここでは「アプリ書換メニュー」から「Actビルド&書換」を選択します。

サンプルアクトなどのプロジェクト名が列挙されます。右側のﾍﾙﾌﾟは関連情報をブラウザで表示します。ﾌｫﾙﾀﾞはプロジェクトのあるフォルダを表示します。

(参考: TWELITE STAGE アプリマニュアル-Actビルド&書換)

5. ビルド&書換

ここでは、先ほどのプロジェクト選択画面中で BRD_APPTWELITE を選択します。

選択すると、以下の画面例のように書き込みが行われます。エラーが表示された場合は、画面の指示に従うか、前の画面戻ってやり直してください。

(参考: TWELITE STAGE アプリマニュアル-ビルド画面)

6. インタラクティブモードに移動

書換が正常に終了すると、続けてインタラクティブモード（設定画面）に移行します。ただし、インタラクティブモードに対応するファームウェアでないと画面は表示されません。

インタラクティブモードでは、TWELITE の無線チャネルなど、各種設定を行えます。

(参考: TWELITE STAGE アプリマニュアル-インタラクティブモード)

7. ターミナル画面

ルートメニューに戻って「ビューア」→「ターミナル」を選択します。

ごく簡易的なターミナルです。TWELITE からのメッセージを確認と、TWELITE への入力を行えます。

画面では、約１秒おきに無線送信したときのメッセージが表示されます。+ + + 入力によるインタラクティブモード画面への遷移も行えます。

(参考: TWELITE STAGE アプリマニュアル-ターミナル)

VSCode でのビルドについて

VSCode はソース編集の強力なエディタですが、VSCode上で TWELITE マイコン用のファームウェアをビルドすることも可能です。

VSCode の起動は TWELITE STAGE アプリの「ビルド＆書換」メニュー以下のプロジェクト一覧より行います。（この動作を行うために TWELITE STAGE アプリの設定が必要です。設定の簡便のため Windows, Linux, macOS では TWELITE_Stage_VSCode.{拡張子} の実行形式を用意しています。）

STAGE設定で 「code でフォルダを開く(VSCode)」を 1 にする。

ビルドのリスト中の右端 [VSCode] を押します。

VSCode のビルドタスク

最初にビルドしたいワークスペースを開いておきます。TWELITE STAGE SDK添付のワークスペースにはビルドタスクの定義が追加されています。

ワークスペースを開き [Terminal>Run Task...] を選択します。

ビルドするTWELITE無線モジュールの種別(BLUE/RED)とアクト名を選択します。以下の例では Build for TWELITE BLUE を選択しています。選択後すぐにビルドが始まります。

ビルド中の経過は画面下部のターミナル部分に出力されます。

...
"windows": {
    "command": "sh",
    "args": [
        "-c", "make TWELITE=BLUE 2>&1 | sed -E -e s#\\(/mnt\\)?/\\([a-zA-Z]\\)/#\\\\\\2:/#g"
    ],

コマンドラインでのビルド

コマンドライン環境でのビルドについて補足します。

Linux, macOS 環境

コマンドラインでのビルドは、bash (または他のシェル)が動作するウインドウでmakeを実行します。事前に環境変数MWSDK_ROOTが正しく設定されていることを確認してください。例えば/work/MWSDKにインストールした場合は ~/.profile に以下のような設定を行います。

MWSDK_ROOT=/work/MWSDK
export MWSDK_ROOT

コマンドライン(bash)よりmakeを実行します。makeがない場合はパッケージをインストールする必要があります。

$ make

Command 'make' not found, but can be installed with:

sudo apt install make
sudo apt install make-guile

$ sudo apt install make
...

Windows 環境

Windowsでは {MWSTAGE SDK インストール}/MWSDK/WIN_BASH.cmd を実行します。 環境変数や make ユーティリティが設定済みです。

ビルド

ビルドは以下のようになります。

$ cd $MWSDK_ROOT
$ cd Act_samples/PingPong/build
$ pwd
/mnt/c/MWSDK/Act_samples/PingPong/build

$ ls
... ファイル一覧の表示

$ rm -rfv objs_*
... 念のため中間ファイルを削除

$ make TWELITE=BLUE
... BLUE用に通常ビルド

$ make -j8 TWELITE=BLUE
... BLUE用にパラレルビルド(同時に8プロセス)

コマンド例

詳細はMakefileの解説をご覧ください。

中間ファイルについて

ビルドが行われると objs_??? フォルダが作成され、その中に中間ファイルが生成されます。このファイルはコンパイルした環境に依存しているため、他の環境のファイルが残っているとmakeがエラーとなりビルドが失敗します。

TWELITE STAGE SDK 配布アーカイブ(ZIPなど)をダウンロードし、適切なフォルダに展開します。

TWELITE STAGE SDK アーカイブ展開後のフォルダ例です (windows, c:\work\MWSTAGE\...)

詳しくはTWELITE STAGE SDKのインストールを参照してください。

環境変数の設定

MWSDK_ROOT, MWSDK_ROOT_WINNAME(Windows10のみ) の設定が必要です。

Windows

ここでは展開後のフォルダ名を C:\MWSTAGE とします。別のフォルダにインストールした場合は、読み替えてください。

C:\MWSTAGE\Tools\SET_ENV.CMD を実行してください。以下の環境変数を設定します。

• MWSDK_ROOT

• MWSDK_ROOT_WINNAME

例えば以下のような設定になります。

MWSDK_ROOT=C:/MWSTAGE/MWSDK/
MW_ROOT_WINNAME=C:\MWSTAGE\MWSDK\

Linux

開発環境やシェルに MWX_ROOT環境変数を反映されるように設定してください。

方法はいくつかありますが、ホームフォルダの.profile（ファイルがなければ新しく作成してください）に以下の設定を追加します。この設定でVSCodeのビルドまで可能です。

MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK/ export MWSDK_ROOT

エディタを使用せずに追加するには以下のようにコマンド入力します。$はプロンプトで環境によって表示が違います。/foo/bar/MSWSDKの部分はインストールしたフォルダに応じて書き換えてください。

$ cd $HOME
$ echo MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK>>.profile
$ echo export MWSDK_ROOT>>.profile

macOS

開発環境やシェルに MWX_ROOT環境変数を反映されるように設定してください。

方法はいくつかありますが、ホームフォルダの.profile（ファイルがなければ新しく作成してください）に以下の設定を追加します。この設定でVSCodeのビルドまで可能です。

MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK/ export MWSDK_ROOT

エディタを使用せずに追加するには以下のようにコマンド入力します。$はプロンプトで環境によって表示が違います。/foo/bar/MSWSDKの部分はインストールしたフォルダに応じて書き換えてください。

$ cd $HOME
$ echo MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK>>.profile
$ echo export MWSDK_ROOT>>.profile

TWELTIE STAGE SDK では、アクト（ソースコード）記述をより容易に行うため、VisualStudio Code(VSCode)を紹介しています。添付のアクトには、VSCodeで適切にコード解釈が行われるように設定したファイルが含まれます。

ソースコードの解析や VSCode からのビルドを行うために、ライブラリソースコードが格納されるフォルダの情報などの情報が必要になります。これらの情報は TWELITE STAGE アプリから VSCode を呼び出すことによって反映されます。（具体的には適切な環境変数を設定して VSCode を始動します。プロジェクトの設定は環境変数を参照しています）

VSCode のインストール

VSCode では、以下のことができます。

• ソースコードの編集

• ソースコード解釈に基づく intellisense（＊全ての定義が正確に解釈されることを保証するわけではありません）

VSCode はリンク先より入手してください。

プラグインの導入

Visual Studio Code が C/C++ 言語の記述を解釈できるようにするために、プラグインをインストールします。

• C/C++ for Visual Studio Code

各OSでの特記事項

TWELITE STAGE から VSCode を呼び出すために、code コマンドが有効になっている必要があります。

以下は code.visualstudio.com の情報です。

• macOS - code コマンドを実行できるように PATH 設定が必要です。

• Windows

• Linux

注記事項

MONOSTICKを親機として使用するアクトです。子機からのパケットのデータペイロードをシリアルポートに出力します。サンプルアクトの多くのサンプルでのパケットを表示することが出来ます。

アクトの機能

• サンプルアクトの子機からのパケットを受信して、シリアルポートへ出力する。

アクトの使い方

必要なTWELITEと配線

最初は以下のデフォルトの設定にて確認してください。

• アプリケーションID: 0x1234abcd

• チャネル: 13

アクトの解説

宣言部

インクルード

// use twelite mwx c++ template library
#include <TWELITE>
#include <MONOSTICK>
#include <NWK_SIMPLE>
#include <STG_STD>

• <NWK_SIMPLE> 簡易中継ネットの定義を読み込みます

• <STG_STD> インタラクティブモードの定義を読み込みます。

その他

// application ID
const uint32_t DEFAULT_APP_ID = 0x1234abcd;
// channel
const uint8_t DEFAULT_CHANNEL = 13;
// option bits
uint32_t OPT_BITS = 0;

/*** function prototype */
bool analyze_payload(packet_rx& rx);

デフォルト値や関数プロトタイプなどの宣言をしています。

setup()

auto&& brd = the_twelite.board.use<MONOSTICK>();
auto&& set = the_twelite.settings.use<STG_STD>();
auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();

setup()では、まず<MONOSTICK>ボードビヘイビア、<STG_STD>インタラクティブモード ビヘイビア、<NWK_SIMPLE>ビヘイビアをuse<>を用い読み込みます。この手続きは必ずsetup()内で行います。

set << SETTINGS::appname("PARENT"); // 設定画面中のタイトル
set << SETTINGS::appid_default(DEFAULT_APP_ID); // アプリケーションIDデフォルト
set << SETTINGS::ch_default(DEFAULT_CHANNEL); // チャネルデフォルト
set << SETTINGS::lid_default(0x00); // LIDデフォルト
set.hide_items(E_STGSTD_SETID::OPT_DWORD2, E_STGSTD_SETID::OPT_DWORD3, E_STGSTD_SETID::OPT_DWORD4, E_STGSTD_SETID::ENC_KEY_STRING, E_STGSTD_SETID::ENC_MODE);
set.reload(); // 設定を不揮発性メモリから読み出す
OPT_BITS = set.u32opt1(); // 読み込み例（オプションビット）

• appname→ 設定画面中のタイトル行にでるアクト名称

• appid_default→ デフォルトのアプリケーションID

• ch_default→ デフォルトのチャネル

• lid_default→ デバイスID(LID)のデフォルト値

• .hide_items()→ 項目の非表示設定

設定値を読み出す前には必ず.reload()を呼び出します。設定値は.u32opt1()のように設定値ごとに読み出し用のメソッドが用意されています。

the_twelite
	<< set                    // インタラクティブモードの設定を反映
	<< TWENET::rx_when_idle() // 受信するように指定
	;

// Register Network
nwk << set;							// インタラクティブモードの設定を反映
nwk << NWK_SIMPLE::logical_id(0x00) // LIDだけは再設定
	;

brd.set_led_red(LED_TIMER::ON_RX, 200); // RED (on receiving)
brd.set_led_yellow(LED_TIMER::BLINK, 500); // YELLOW (blinking)

<MONOSTICK>ボードビヘイビアではLED点灯制御のための手続きを利用できます。

1行目では赤色のLEDを無線パケットを受信したら200ms点灯する設定をしています。最初のパラメータはLED_TIMER::ON_RXが無線パケット受信時を意味します。２番目は点灯時間をmsで指定します。

2行目はLEDの点滅指定です。１番目のパラメータはLED_TIMER::BLINKが点滅の指定で、２番目のパラメータは点滅のON/OFF切り替え時間です。500msごとにLEDが点灯、消灯(つまり１秒周期の点滅)を繰り返します。

the_twelite.begin(); // start twelite!

the_tweliteを開始するための手続きです。act0..4では出てきませんでしたがthe_tweliteの設定や各種ビヘイビアの登録を行った場合は、必ず呼び出すようにしてください。

loop()

このサンプルではloop()中の処理はありません。

void loop() {
}

on_rx_packet()

パケットを受信したときに呼び出されるコールバック関数です。この例では受信したパケットデータに対していくつかの出力を行っています。

void on_rx_packet(packet_rx& rx, bool_t &handled) {  
	Serial << ".. coming packet (" << int(millis()&0xffff) << ')' << mwx::crlf;

  ...
  
	// packet analyze
	analyze_payload(rx);
}

analyze_payload()

関数の末尾で呼び出されるanalyze_payload()は、いくつかのサンプルアクトのパケットを解釈するコードが含まれています。サンプルアクト中のパケット生成部分と対応させてコードを参照してください。

bool b_handled = false;

uint8_t fourchars[4]{};
auto&& np = expand_bytes(
	    rx.get_payload().begin(), rx.get_payload().end()
		, fourchars
    );
    
if (np == nullptr) return;

// display fourchars at first
Serial
	<< fourchars 
	<< format("(ID=%d/LQ=%d)", rx.get_addr_src_lid(), rx.get_lqi())
	<< "-> ";
	

この関数では最初に４文字識別データをfourchars[5]配列に読み込みます。

char fourchars[5]{}; // 終端文字\0も含め5バイト確保する
auto&& np = expand_bytes(
	    rx.get_payload().begin(), rx.get_payload().end()
		, make_pair((char *)fourchars, 4)
	);

つづいて４バイトヘッダに対応した処理を行います。ここではサンプルアクトSlp_Wk_and_Txのパケットを解釈し内容を表示します。

// Slp_Wk_and_Tx
if (!b_handled && !strncmp(fourchars, "TXSP", 4)) {
	b_handled = true;
	uint32_t tick_ms;
	uint16_t u16work_ct;

	np = expand_bytes(np, rx.get_payload().end()
		, tick_ms
		, u16work_ct
	);

	if (np != nullptr) {
		Serial << format("Tick=%d WkCt=%d", tick_ms, u16work_ct);
	} else {
		Serial << ".. error ..";
	}
}

他の解釈部の判定をスキップするようにb_handledを_true_に設定します。

読み出しに成功すれば内容を出力して終了です。

独自のアスキー書式を定義して出力する

smplbuf_u8<128> buf;
mwx::pack_bytes(buf
	, uint8_t(rx.get_addr_src_lid())		   // 送信元の論理ID
	, uint8_t(0xCC)											   // 0xCC
	, uint8_t(rx.get_psRxDataApp()->u8Seq) // パケットのシーケンス番号
	, uint32_t(rx.get_addr_src_long())		 // 送信元のシリアル番号
	, uint32_t(rx.get_addr_dst())			     // 宛先アドレス
	, uint8_t(rx.get_lqi())					       // LQI:受信品質
	, uint16_t(rx.get_length())				     // 以降のバイト数
	, rx.get_payload() 						         // データペイロード
);

serparser_attach pout;
pout.begin(PARSER::ASCII, buf.begin(), buf.size(), buf.size());

Serial << "FMT PACKET -> ";
pout >> Serial;
Serial << mwx::flush;

1行目はアスキー書式に変換する前のデータ列を格納するバッファをローカルオブジェクトとして宣言しています。

2行目はpack_bytes()を用いてデータ列を先ほどのbufに格納します。データ構造はソースコードのコメントを参照ください。pack_bytes()のパラメータにはsmplbuf_u8 (smplbuf<uint8_t, ???>)形式のコンテナを指定することもできます。

13,14,17行目は、シリアルパーサーの宣言と設定、出力です。

NWK_SIMPLEのヘッダを含めてダンプ出力する

最初の出力（if(0)により実行されないようになっています)は<NWK_SIMPLE>の制御データを含めたデータをすべて表示します。制御データは11バイトあります。通常は制御情報を直接参照することはありませんが、あくまでも参考です。

serparser_attach pout;
pout.begin(PARSER::ASCII, rx.get_psRxDataApp()->auData, 
    rx.get_psRxDataApp()->u8Len, rx.get_psRxDataApp()->u8Len);

Serial << "RAW PACKET -> ";
pout >> Serial;
Serial << mwx::flush;

// 参考：制御部のパケット構造
// uint8_t  : 0x01 固定
// uint8_t  : 送信元のLID
// uint32_t : 送信元のロングアドレス(シリアル番号)
// uint32_t : 宛先アドレス
// uint8_t  : 中継回数

２行目はシリアルパーサーのバッファを設定します。すでにあるデータ配列、つまり受信パケットのペイロード部を指定します。serparser_attach poutは、既にあるバッファを用いたシリアルパーサーの宣言です。pout.begin()の１番目のパラメータは、パーサーの対応書式をPARSER::ASCIIつまりアスキー形式として指定しています。２番目はバッファの先頭アドレス。３番目はバッファ中の有効なデータ長、４番目はバッファの最大長を指定します。出力用で書式解釈に使わないため４番目のパラメータは３番目と同じ値を入れています。

6行目でシリアルポートへ>>演算子を用いて出力しています。

7行目のSerial << mwx::flushは、ここで出力が終わっていないデータの出力が終わるまで待ち処理を行う指定です。(Serial.flush()も同じ処理です)

Slp_Wk_and_Tx は、定期起床後、何か実行（センサーデータの取得など）を行って、その結果を無線パケットとして送信するようなアプリケーションを想定した、テンプレートソースコードです。

setup(), loop() の形式では、どうしても loop() 中が判読しづらい条件分岐が発生しがちです。本Actでは、loop()中をを用いて _switch_構文による単純な状態遷移を用いることで、コードの見通しを良くしています。

アクトの機能

• 起動後、初期化処理を経て、一旦スリープする

  1. setup()初期化する

  2. begin() スリープ実行する

• スリープ起床後、状態変数を初期化し、以下の順に動作を行う

  1. wakeup()スリープからの起床、各初期化を行う

  2. loop()状態INIT->WORK_JOBに遷移: 何らかの処理を行う（このActでは 1ms ごとの TickCount ごとにカウンタを更新し乱数で決めたカウント後にTX状態に進む）

  3. loop() 状態TX送信要求を行う

  4. loop() 状態WAIT_TX送信完了待ちを行う

  5. loop() 状態EXIT_NORMALスリープする (1. に戻る)

• loop() 状態EXIT_FATAL エラーが発生した場合は、モジュールリセットする

アクトの解説

宣言部

インクルード

#include <TWELITE>
#include <NWK_SIMPLE>
#include <SM_SIMPLE>

#include "Common.h"

パケット送信を行うため <NWK_SIMPLE> をインクルードしています。また、アプリケーションIDなど基本的な定義は "Common.h" に記述しています。

状態定義

loop()内の順次処理を記述うするため、このサンプルではステートマシン（状態遷移）の考え方を用います。ごく単純な状態遷移の処理をまとめた<SM_SIMPLE>を用います。

Common.h に以下の状態に対応する列挙体 STATE が定義されています。

enum class STATE {
    INIT = 0,    // INIT STATE
    WORK_JOB,    // do some job (e.g sensor capture)
    TX,          // reuest transmit
    WAIT_TX,     // wait its completion
    EXIT_NORMAL, // normal exiting.
    EXIT_FATAL   // has a fatal error (will do system reset)
};

SM_SIMPLE<STATE> step;

ここで宣言されたstepは、状態の管理、タイムアウト、処理待ちを行うための機能が含まれています。

センサーデータ

このサンプルではセンサーデーターの処理は行いませんが、ダミーデータを用意しておきます。

struct {
	uint16_t dummy_work_ct_now;
	uint16_t dummy_work_ct_max;  // counter for dummy work job. 
} sensor;

setup()

void setup() {
	/*** SETUP section */
	step.setup(); // init state machine
	
	// the twelite main class
	the_twelite
		<< TWENET::appid(APP_ID)    // set application ID (identify network group)
		<< TWENET::channel(CHANNEL) // set channel (pysical channel)
		<< TWENET::rx_when_idle(false);  // open receive circuit (if not set, it can't listen packts from others)

	// Register Network
	auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
	nwk	<< NWK_SIMPLE::logical_id(DEVICE_ID); // set Logical ID. 

	/*** BEGIN section */
	the_twelite.begin(); // start twelite!

	/*** INIT message */
	Serial << "--- Sleep an Tx Act ---" << crlf;
}

変数やクラスオブジェクトの初期化を行います。

• stepステートマシンの初期化

• the_tweliteクラスオブジェクトの初期化

• ネットワーク <NWK_SIMPLE> の登録と初期化(DEVICE_IDの登録)を行います。

つづいてクラスオブジェクトやハードウェアなどの開始処理を行います。

the_twelite.begin(); // start twelite!

the_tweliteを開始するための手続きです。act0..4では出てきませんでしたがthe_tweliteの設定や各種ビヘイビアの登録を行った場合は、必ず呼び出すようにしてください。

begin()

void begin() {
	Serial << "..begin (run once at boot)" << crlf;
	SleepNow();
}

setup()の直後に一度だけ呼び出されます。SleepNow()関数夜を呼び出して初回のスリープ手続きを行います。

wakeup()

void wakeup() {
　memset(&sensor, 0, sizeof(sensor));
	Serial << crlf << int(millis()) << ":wake up!" << crlf;
}

起床直後に呼び出されます。ここではセンサーデータ領域の初期化と、起床時のメッセージを出力しています。

loop()

void loop() {
	do {
		switch(step.state()) {
		case STATE::INIT:
			sensor.dummy_work_ct_now = 0;
			sensor.dummy_work_ct_max = random(10,1000);
			step.next(STATE::WORK_JOB);
		break;

		...
		}
	} while (step.b_more_loop());
}

上記のコードは、実際のコードを簡略化したものです。

step.b_more_loop()は、.next()により状態遷移があった場合_true_に設定されます。これは状態遷移が発生したときloop()を脱出せずに次の状態のコード（case節）を実行する目的です。

以下に各状態の解説を行います。

STATE::INIT

sensor.dummy_work_ct_now = 0;
sensor.dummy_work_ct_max = random(10,1000);

step.next(STATE::WORK_JOB);

ダミーーのセンサー値を初期化します。一つは加算カウンタ、一つはカウンター停止値でランダムに決定しています。

STATE::WORK_JOB

if (TickTimer.available()) {
	Serial << '.';
	sensor.dummy_work_ct_now++;
	if (sensor.dummy_work_ct_now >= sensor.dummy_work_ct_max) {
		Serial << crlf;
		step.next(STATE::TX);
	}
}

WORK_JOB状態では1msごとのタイマー単位で処理します。TickタイマーごとにTickTimer.available()になります。Tickタイマーごとにカウンタを加算しdummy_work_ct_maxになったら、次の状態STATE::TXに遷移します。

STATE::TX

if (Transmit()) {
	Serial << int(millis()) << ":tx request success!" << crlf;
	step.set_timeout(100);
	step.clear_flag();
	step.next(STATE::WAIT_TX);
} else {
	// normall it should not be here.
	Serial << int(millis()) << "!FATAL: tx request failed." << crlf;
	step.next(STATE::EXIT_FATAL);
}

Transmit()関数を呼び出しパケット送信要求を行います。送信要求が成功した場合はSTATE::WAIT_TXEVENTに遷移して送信完了を待つことになります。ここでは完了待ちとしてSM_SIMPLEステートマシンのタイムアウトとフラッグ機能を用います（待ちループ中での変数値の変化により判定する単純なものです）。

単一の送信要求が失敗することは通常想定しませんが、失敗時はSTATE::EXIT_FATALとして例外処理する状態に遷移します。

STATE::WAIT_TX

if (step.is_flag_ready()) {
	Serial << int(millis()) << ":tx completed!" << crlf;
	step.next(STATE::EXIT_NORMAL);
} else if (step.is_timeout()) {
	Serial << int(millis()) << "!FATAL: tx timeout." << crlf;
	step.next(STATE::EXIT_FATAL);
}

送信完了待ちは後述のon_tx_comp()によりステートマシン機能のフラッグをセットすることで判定しています。タイムアウトは.is_timeout()を呼び出すことで.set_timeout()を行ったときからの経過時間により判定します。

送信が成功しても失敗しても通常は完了通知がありますが、タイムアウトを設け例外処理のための状態STATE::EXIT_FATALに遷移します。

STATE::EXIT_NORMAL

SleepNow();

SleepNow()を呼び出して、スリープ処理に入ります。

STATE::EXIT_FATAL

Serial << crlf << "!FATAL: RESET THE SYSTEM.";
delay(1000); // wait a while.
the_twelite.reset_system();

重大なエラーとして、システムリセットを行います。

SleepNow()

void SleepNow() {
	uint16_t u16dur = SLEEP_DUR;
	u16dur = random(SLEEP_DUR - SLEEP_DUR_TERMOR, SLEEP_DUR + SLEEP_DUR_TERMOR);

	Serial << int(millis()) << ":sleeping for " << int(u16dur) << "ms" << crlf;
	Serial.flush();

	step.on_sleep(); // reset status of statemachine to INIT state.

	the_twelite.sleep(u16dur, false);
}

周期スリープを行います。スリープ時間はrandom()関数を用いて、一定の時間ブレを作っています。これは複数のデバイスの送信周期が同期した場合、著しく失敗率が上がる場合があるためです。

スリープ前にはSM_SIMPLEステートマシンの状態を.on_sleep()を呼び出してセットしておきます。

Transmit()

MWX_APIRET vTransmit() {
	Serial << int(millis()) << ":vTransmit()" << crlf;

	if (auto&& pkt = the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet()) {
		// set tx packet behavior
		pkt << tx_addr(0x00)  // 0..0xFF (LID 0:parent, FE:child w/ no id, FF:LID broad cast), 0x8XXXXXXX (long address)
			<< tx_retry(0x1) // set retry (0x3 send four times in total)
			<< tx_packet_delay(0,0,2); // send packet w/ delay (send first packet with randomized delay from 0 to 0ms, repeat every 2ms)

		// prepare packet payload
		pack_bytes(pkt.get_payload() // set payload data objects.
			, make_pair(FOURCC, 4) // string should be paired with length explicitly.
			, uint32_t(millis()) // put timestamp here.
			, uint16_t(sensor.dummy_work_ct_now) // put dummy sensor information.
		);
		
		// do transmit 
		//return nwksmpl.transmit(pkt);
		return pkt.transmit(); 
	}

	return MWX_APIRET(false, 0);
}

ID=0x00の親機宛に無線パケットの送信要求を行います。格納されるデータはActサンプルで共通に使われている４文字識別子(FOURCC)に加え、システム時間[ms]とダミーセンサー値(sensor.dummy_work_ct_now)を格納します。

まず最初に送信パケットを格納するオブジェクトを取得します。このオブジェクトを操作し、送信データや条件を設定します。

if (auto&& pkt = the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet()) {

mwx ライブラリでは、_if_文中でオブジェクトを取得し、そのオブジェクトの_bool_判定で_true_の場合に処理を行う記述を採用しています。ここではthe_twelite.network.use<NWK_SIMPLE>()によりボードオブジェクトを取得し、ボードオブジェクトの.prepare_tx_packet()によりパケットオブジェクトを取得しています。パケットオブジェクトの取得失敗は通常想定しませんが、失敗時は送信キューが一杯で送信要求が受け付けられない場合です。このサンプルは単一の送信のみですから、エラーは想定外の重大な問題に限られます。

pkt << tx_addr(0x00) // 宛先
		<< tx_retry(0x1) // 再送回数
		<< tx_packet_delay(0,0,2); // 送信遅延

pack_bytes(pkt.get_payload() // set payload data objects.
	, make_pair(FOURCC, 4) // string should be paired with length explicitly.
	, uint32_t(millis()) // put timestamp here.
	, uint16_t(sensor.dummy_work_ct_now) // put dummy sensor information.
);	

この関数は可変数引数により指定できます。一番最初のパラメータは.get_payload()より得られた配列オブジェクトです。

• make_pair(FOURCC,4) : _make_pair_はC++標準ライブラリのもので、_std::pair_オブジェクトを生成します。文字列型に対して先頭から４バイト分を書き出すという意味になります。 （文字列型の配列は終端を含める、含めないといった話題が混乱を生むため、明示的に書き出すバイト数を指定するために、このような指定をします）

• _uint32_t_型のデータを指定するとビッグエンディアン並びで４バイト分のデータを書き込みます。

• _uint16_t_型のデータについても同様です。

auto&& pay = pkt.get_payload(); // get buffer object.

// the following code will write data directly to internal buffer of `pay' object.
uint8_t *p = pay.begin(); // get the pointer of buffer head.

S_OCTET(p, FOURCC[0]); // store byte at pointer `p' and increment the pointer.
S_OCTET(p, FOURCC[1]);
S_OCTET(p, FOURCC[2]);
S_OCTET(p, FOURCC[3]);

S_DWORD(p, millis()); // store uint32_t data.
S_WORD(p, sensor.dummy_work_ct_now); // store uint16_t data.

pay.redim(p - pay.begin());

最後に.transmit()を呼び出して、送信要求を行います。戻り値はMWX_APIRET型です。要求後、実際の送信が行われますが、送信パラメータや送信サイズにもよりますが、完了まで数ms～数十ms程度はかかります。完了時にはon_tx_comp()が呼び出されます。

return pkt.transmit(); 

on_tx_comp()

void on_tx_comp(mwx::packet_ev_tx& ev, bool_t &b_handled) {
	step.set_flag(ev.bStatus);
}

送信完了時に呼び出されるシステムイベントです。ここでは.set_flag()により完了としています。

2台のシリアル接続しているTWELITEの片方からPING(ピン)の無線パケットを送信すると、他方からPONG(ポン)の無線パケットが返ってきます。

アクトの使い方

必要なTWELITE

いずれかを２台。

• でUART接続されているなど

アクトの解説

インクルード

// use twelite mwx c++ template library
#include <TWELITE>
#include <NWK_SIMPLE>

宣言部

// application ID
const uint32_t APP_ID = 0x1234abcd;

// channel
const uint8_t CHANNEL = 13;

// DIO pins
const uint8_t PIN_BTN = 12;

/*** function prototype */
void vTransmit(const char* msg, uint32_t addr);

/*** application defs */
// packet message
const int MSG_LEN = 4;
const char MSG_PING[] = "PING";
const char MSG_PONG[] = "PONG";

• サンプルアクト共通宣言

• 長めの処理を関数化しているため、そのプロトタイプ宣言（送信と受信）

• アプリケーション中のデータ保持するための変数

セットアップ setup()

void setup() {
	/*** SETUP section */
	Buttons.setup(5); // init button manager with 5 history table.
	Analogue.setup(true, 50); // setup analogue read (check every 50ms)

	// the twelite main class
	the_twelite
		<< TWENET::appid(APP_ID)    // set application ID (identify network group)
		<< TWENET::channel(CHANNEL) // set channel (pysical channel)
		<< TWENET::rx_when_idle();  // open receive circuit (if not set, it can't listen packts from others)

	// Register Network
	auto&& nwksmpl = the_twelite.network.use<NWK_SIMPLE>();
	nwksmpl << NWK_SIMPLE::logical_id(0xFE) // set Logical ID. (0xFE means a child device with no ID)
	        << NWK_SIMPLE::repeat_max(3);   // can repeat a packet up to three times. (being kind of a router)

	/*** BEGIN section */
	Buttons.begin(pack_bits(PIN_BTN), 5, 10); // check every 10ms, a change is reported by 5 consequent values.
	Analogue.begin(pack_bits(PIN_ANALOGUE::A1, PIN_ANALOGUE::VCC)); // _start continuous adc capture.

	the_twelite.begin(); // start twelite!

	/*** INIT message */
	Serial << "--- PingPong sample (press 't' to transmit) ---" << mwx::crlf;
}

大まかな流れは、各部の初期設定、各部の開始となっています。

the_twelite

このオブジェクトはTWENETを操作するための中核クラスオブジェクトです。

	// the twelite main class
	the_twelite
		<< TWENET::appid(APP_ID)    // set application ID (identify network group)
		<< TWENET::channel(CHANNEL) // set channel (pysical channel)
		<< TWENET::rx_when_idle();  // open receive circuit (if not set, it can't listen packts from others)

the_twelite に設定を反映するには << を用います。

• TWENET::appid(APP_ID) アプリケーションIDの指定

• TWENET::channel(CHANNEL) チャネルの指定

• TWENET::rx_when_idle() 受信回路をオープンにする指定