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

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

• ディレクトリ構成

• コマンドラインによるビルド

• VS Codeでのビルド

• WSLでのビルド

環境変数の設定

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

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

VSCode のインストール

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

• ソースコードの編集

• GIT への接続（お客様が独自にソース管理を GIT 上で行う場合）

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

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

プラグインの導入

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

• C/C++ for Visual Studio Code

注記事項

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

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

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

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

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

ビルド環境による差異

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

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

クラスオブジェクトは、MWXライブラリであらかじめ定義されたオブジェクトで、TWENETを取り扱うthe_twelite、ペリフェラルの利用のためのオブジェクトが定義されています。

各オブジェクトは.setup(), .begin()メソッドの呼び出しを行って初期化する必要があります。(UART0を利用するSerialオブジェクトのみ初期化は必要ありません)

TWE:LITE STAGE を用いると、ビルドと実行を簡単に行えます。ビルド→プログラマの起動→書き込み→ターミナルの起動といった一連の動作を簡単な選択操作で実行できます。

1. TWELITE STAGE の起動

事前にTWELITE RやMONOSTICKを接続しておきます。TWELITE STAGE アプリを起動します。

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

TWELITE が接続されていれば、対応するシリアルポートが表示されます。選択してください。

3. アプリ書換メニューを選択

アプリ書換メニューを選択します。TWELITEが接続されていない場合はエラーになります。その場合は接続を確認の上、改めてシリアルポートをオープンしてください。

アプリ書換メニューにはいくつかのサブメニューがあります。

• BINから選択 → ビルド済みのファイルを選択して書き込む

• Actビルド＆書換 → Actのサンプル集から選択して書き込む

• TWELITE APPS ビルド＆書換 → TWELITE APPS (ビルド済みのレディメードアプリ) から選択して書き込む

• Actエクストラ → Actのその他のアプリ

4. 書換メニューを選択

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

このメニューを開くと、MWSTAGE/MWSDK/Act_samplesにあるサンプル一覧が表示されます。

ビルドしたい対象を選択します。

選択後、ビルドと書き込みが自動で行われ、ビルド終了後に「インタラクティブモード操作画面」に遷移します。Actのサンプルのほとんどが、インタラクティブモードを持ちませんが、この画面はターミナル操作の替わりにも利用できます。

ここではアクト(BINファイル)の書き込みと実行について解説します。

事前にビルド作業で生成した .BIN ファイルを用意しておきます。専用ユーティリティでは、書き込みとターミナル機能の両方を実行できます。ターミナルについては、一般のアプリケーションを利用しても構いません。

専用ユーティリティ

• (GUIアプリ、書換、ターミナル機能)

• (コマンドアプリ、書換、ターミナル機能)

ターミナル

• Windows - TeraTerm など

• Linux/macOS - screen など

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

パケット型の基底クラスですが、メンバー構造体commonにはアドレス情報など共通情報が含まれます。

class TwePacket {
	public:
		static const E_PKT _pkt_id = E_PKT::PKT_ERROR;
		
		struct {
			uint32_t tick;     // 解釈実行時のシステム時刻[ms]
			uint32_t src_addr; // 送信元アドレス(シリアル番号)
			uint8_t src_lid;   // 送信元アドレス(論理アドレス)
			uint8_t lqi;       // LQI
			uint16_t volt;     // 電圧[mV]
		} common;
};

ライブラリ中で共通的に読み込まれる定義について、定義内容を引用します。

mwx_common.h

#include <cstdint> // for type name
typedef char char_t;
typedef uint8_t byte;
typedef uint8_t boolean;

#ifndef NULL
#define NULL nullptr
#endif

スリープから起床したときにloop()に移行する前に呼ばれ、スリープ復帰後の初期化処理や復帰状態によって処理を分岐するための手続きを含めます。

ポーリングによる時間待ちを行います（μ秒指定）。

void delayMicroseconds(uint32_t microsec)

microsecにて与えられた期間待ち処理を行います。

時間の計測はTickTimerのカウントによって行っています。また長い時間待ちを行う場合はCPUのクロックを低下してポーリング処理を行います。

ペリフェラルAPIも初期化もされていない、コード実行の再初期に呼び出されます。

ディジタル出力ピンの設定を変更します。

static inline void digitalWrite(uint8_t u8pin, E_PIN_STATE ulVal)

事前にpinMode()にて設定対象のピンを出力用に設定しておきます。１番目のパラメータは、設定対象のピン番号を指定します。２番目のパラメータはHIGHかLOWのいずれかを指定します。

アプリケーションのメインループです。ループ終了後はCPUがDOZEモードに遷移し低消費電流で次の割り込みを待ちます。

アクトの記述では、ほとんどの処理がこのループ内に記述されます。

ビヘイビアの記述サンプルです。詳細はこちらを参照ください。

スリープ復帰後、ペリフェラルAPIが初期化されない再初期に呼び出されます。

loop()関数の初回コールの手前で一度だけ呼び出されます。TWENET の初期化は終了しているのでsetup()のような制約を考慮する必要はありません。

主な使い方は、

• 始動メッセージの表示

• テスト用のコードを記述

• 始動直後のスリープ遷移

• setup()で不都合がある処理（無線パケット処理・タイマー動作など）

更新方法

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

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

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

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

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

2. 以下のディレクトリの内容を差し替えます。

リリース前の更新

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

0.1.7 - 2020-12-03

主な改定内容

• TWELITE 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クラスオブジェクトを追加 ()

  • サンプル ()

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

• pktparserクラスを追加しました ()

  • サンプル ()

• serparser/pktparser を他のプラットフォームでビルドできるようサンプルを用意しました ()

• modified twenet_instance_manager to pass a parameter when constructing an object.

• added EncodeVolt(), DecodeVolt() to compress 16bit voltage value into 8bit.

• modified CRC_u8Calc() or others to be passed const uint8_t*.

• modified smplbuf which copy constructor/assigin operator is supported with alloc_local() allocator.

• added build support for serparser/pktparser to build at standard io based platform at `stdio' folder. (tested only on macOS)

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 のサポートを追加 (解説 , サンプル )

• 除算を行わない 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 にすると、平文のパケットも受信する。

• 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

一括ダウンロード

()

主な改定内容

• を追加

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

0.1.4 - 2020-07-29 (MWSDK2020_07_UNOFFICIAL)

一括ダウンロード

()

主な改定内容

• delayMilliseconds() の追加

• digitalReadBitmap() の追加

• delay() の精度向上

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

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

0.1.3 - 2020-05-29

MWSDK2020_05 に対応

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

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

0.1.2 - 2020-04-24

MWSDK2020_04 に対応

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

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

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

0.1.1 - 2020-02-28

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

0.1.0 - 2019-12-23

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

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

一般的な用語

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は本質的には同じもので、いずれのキーワードで宣言してもクラスとなります。

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

ラッパークラス

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

メソッド・メンバー関数

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

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

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

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

コンストラクタ

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

デストラクタ

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

抽象クラス

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

スコープ

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

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

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

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

名前空間 (namespace)

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

テンプレート (template)

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

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

nullptr

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

参照型

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

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

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

型推論

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

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

コンテナ

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

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

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

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

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

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

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

C++標準ライブラリ

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

アルゴリズム

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

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

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

VS Code では、Act_samplesディレクトリ直下にあるワークスペースファイルを開くか、Act_samples以下のアクトディレクトリを開きます。

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

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

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

は Windows10 のサブシステムとして動作する Linux 環境です。

MWSDK2020_05 .. 2020_10

MWSDK/Tools/ba-elf-ba2-r36379.w10 以下に Windows10用とLinux用の実行形式が両方含まれます。WSLを動作させ環境変数MWSDK_ROOTを適切に設定します。

例えば C:\Work\MWSTAGE\MWSDK の場合は以下のように設定します。

MWSDK2020_12

TWELITE STAGE SDK パッケージには、WSL用の実行形式は含まれません。

MWSTAGE/Tools/ba-elf-ba2-r36379.wslというフォルダ名で、ツール一式を格納してください。ツールはMWSDK2020_10のMWSDK/Tools/ba-elf-ba2-r36379.w10を用いるのが平易です。

ビルドについて

makeが実行可能で MWSDK_ROOT が適切に設定されていれば、Linuxでの方法と同じです。書き込みなどのユーティリティはWSL上で動作するものがないためWindows10用のものを利用してください。

begin()メソッドによりハードウェアの初期化を行った後、beginTransaction()によりバスの読み書きができるようになります。beginTransaction()を実行するとSPIのセレクトピンが選択されます。読み書きはtransfer()関数を用います。SPIは読み出しと書き込みを同時に実行します。

beginTransaction()

バスの利用開始を行います。SPIのセレクトピンをセットします。

settingsパラメータを与えて呼び出した場合は、バスの設定を行います。

endTransaction()

バスの利用を終了します。SPIのセレクトピンを解除します。

transfer(), transfer16(), transfer32()

バスの読み書きを行います。trasnfer()は8bit、transfer16()は16bit、transfer32()は32bitの転送を行います。

この組み込みクラスはシリアルポートでの書式入力に利用することを想定して組み込みオブジェクトとして定義しています。

初期化時(begin())にヒープから内部で使用するバッファ領域を確保するmwx::serial_parser<mwx::alloc_heap<uint8_t>>型として定義されています。

詳細はクラス を参照してください。

mwx::stream の << 演算子に対して数値型をビッグエンディアンのバイト列で出力するヘルパークラスです。

コンストラクタ

コード実行の初期に呼び出され、初期化コードを記述します。

TwePacketAppIOクラスは、標準アプリを解釈したものです。

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

DataAppIO構造体

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

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

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

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

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

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

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

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

mwx::stream の << 演算子に対して改行コード (CR LF) を出力するためのヘルパークラスのインスタンスです。

保証・ライセンス

本パッケージ内で、ライセンス上特別な記述のないものは、(MW-SLA)を適用します。

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

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

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

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

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

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

Act_samples
  +-PingPong
    +-PingPong.cpp   : アクトファイル
    +-build          : ビルドディレクトリ
    +-.vscode        : VS Code 用の設定ファイル    

この PingPong ディレクトリを別の場所（ただしディレクトリ名に日本語や空白が含まない）にコピーします。

SomeDir
  +-AlphaBravo
    +-PingPong.cpp -> AplhaBravo.cpp ※ファイル名を変更
    +-build          : ビルドディレクトリ
    +-.vscode        : VS Code 用の設定ファイル

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

タイマーでは、指定周期でのソフトウェア割り込みを発生させる目的、指定周期でPWM出力を行う２つの機能があります。TWELITE無線モジュールには0..4まで合計５つのタイマーが利用可能です。

組み込みオブジェクト名は Timer0..4 ですが、このページでは TimerXと記載します。

メソッド

setup()

void setup()

タイマーを初期化します。この呼び出しにより必要なメモリ領域の確保を行います。

begin()

void begin(uint16_t u16Hz, bool b_sw_int = true, bool b_pwm_out = false)

タイマーを開始します。１番目のパラメータは、タイマーの周期でHzで指定します。２番目のパラメータをtrueにするとソフトウェア割り込みが有効になります。３番目のパラメータをtrueにするとPWM出力を有効にします。

end()

void end()

タイマーの動作を停止します。

available()

inline bool available()

タイマー割り込みが発生した直後のloop()でtrueになり、loop()が終了すればfalseになります。

change_duty()

void change_duty(uint16_t duty, uint16_t duty_max = 1024)

デューティー比の設定を行う。１番目のパラメータにデューティ比を指定します（小さい値を指定すると波形の平均はGNDレベルに近づき、大きい値を指定するとVccレベルに近づく）。２番目のパラメータはデューティ比の最大値を指定します。

change_hz()

void change_hz(uint16_t hz, uint16_t mil = 0) 

タイマーの周波数を設定します。２番目のパラメータは周波数の小数点３桁分の値を整数で指定します。例えば 10.4 Hz としたい場合は hz=10, mil=400 と指定します。

ディジタル入力の変化を検出します。このクラスは、同じ検出値が複数回得られたときに変化を検出します。メカ式のボタンのチャタリングの影響を小さくするのに有効です。

メソッド

setup()

void setup(uint8_t max_history);

パラメータのmax_historyは、begin()で設定可能な参照回数の最大値です。ここではメモリーの確保と初期化を行います。

begin()

void begin(uint32_t bmPortMask,
				   uint8_t u8HistoryCount,
				   uint16_t tick_delta);

Buttonsの動作を開始します。１番目のパラメータbmPortMaskは監視対象のディジタル入力のビットマップを指定します。bit 0がDIO 0, ... , bit N がDIO Nに対応します。複数指定することができます。２番目のu8HistoryCountは値の確定をするのに必要な回数です。３番目のtick_deltaは値の確認を行う間隔をmsで指定します。

値の確定にはu8HistoryCount*tick_delta[ms]かかることになります。例えばu8HistoryCount=5, tick_delta=4の場合は、状態の確定に最低約20msかかります。

確認はTickTimerのイベントハンドラで行っています。割り込みハンドラではないので、処理等の遅延の影響を受けますが、メカ式ボタン等のチャタリング抑制には十分です。

end()

void end()

Buttonsの動作を終了します。

available()

inline bool available()

変化が検出されたときにtrueを返します。read()を実行するとクリアされます。

read()

bool read(uint32_t& u32port, uint32_t& u32changed)

availableになったとき呼び出します。u32portは現在の入力DIOのビットマップ、u32changedは変化が検出されたDIOのビットマップです。

Buttonsが動作していない場合はfalseを返します。

動作について

初回の値確定

Buttonsが動作を開始した時点では、DIOの入力状態は未確定です。値が確定した時点でavailableになります。このときread()で読み出すビットマップのMSB(bit31)が１にセットされます。

動作確定を要するため、入力値が定常的に変化するポートを監視する目的では利用できません。

スリープ

スリープ前にButtonsが稼働状態であれば、復帰後に再開します。再開後、初回確定を行います。

TwePacketAppUartクラスは、App_UARTの拡張書式を親機・中継器アプリApp_Wingsで受信したときの形式です。

class TwePacketAppUART : public TwePacket, public DataAppUART

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

DataAppUART構造体

struct DataAppUART {
		/**
		 * source address (Serial ID)
		 */
		uint32_t u32addr_src;

		/**
		 * source address (Serial ID)
		 */
		uint32_t u32addr_dst;

		/**
		 * source address (logical ID)
		 */
		uint8_t u8addr_src;

		/**
		 * destination address (logical ID)
		 */
		uint8_t u8addr_dst;

		/**
		 * LQI value
		 */
		uint8_t u8lqi;

		/**
		 * Response ID
		 */
		uint8_t u8response_id;

		/**
		 * Payload length
		 */
		uint16_t u16paylen;

		/**
		 * payload
		 */
#if MWX_PARSER_PKT_APPUART_FIXED_BUF == 0
		mwx::smplbuf_u8_attach payload;
#else
		mwx::smplbuf_u8<MWX_PARSER_PKT_APPUART_FIXED_BUF> payload;
#endif
	};

payloadはデータ部分ですが、マクロ定義によってデータ格納の方法が変わります。

MWX_PARSER_PKT_APPUART_FIXED_BUFの値が0としてコンパイルした場合は、payloadはパケット解析を行うバイト列を直接参照します。元のバイト列の値が変更されるとpayload中のデータは破壊されます。

MWX_PARSER_PKT_APPUART_FIXED_BUFの値を0より大きい値として定義した場合は、payloadにはその値（バイト数）のバッファが確保されます。ただしシリアル電文のデータがバッファサイズを超えた場合はparse<TwePacketAppUART>()は失敗しE_PKT::PKT_ERRORを戻します。

DIO(汎用ディジタルIO)ピンの設定を行います。

void pinMode(uint8_t u8pin, E_PIN_MODE mode)

この関数では DIO0..19 と、DO0,1のピンの状態を変更できます。設定内容は E_PIN_MODE の列挙値のDIOの解説とDOの解説を参照してください。

mwx::stream の出力バッファをフラッシュする。flush() メソッドを呼び出すヘルパークラスへのインスタンス。

for (int i = 0; i < 127; ++i) {
    Serial << "hello world! (" << i << ")" << twe::endl << twe::flush;
}

• シリアルポートの場合は出力完了までポーリング待ちを行う

• mwx::simpbuf バッファの場合は 0x00 を末尾に出力する（サイズは変更しない）

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

最初にBRD_APPTWELITEとParent_MONOSTICKの解説に目を通すようにしてください。

最新版の入手

共通の記述

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

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

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

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

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

DataTwelite構造体

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

		// 宛先の論理ID
		uint8_t u8addr_dst;

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

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

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

		// LQI値
		uint16_t u8lqi;

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

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

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

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

アプリケーションの記述を行うコールバック関数です。コールバックはシステム（ライブラリ）から呼び出されるという意味です。ユーザがいくつかのコールバック関数を定義することでシステムの振る舞いを記述します。

以下のコールバック関数は必須定義です。

• setup()

• loop()

それ以外の関数は定義しない場合は、何も実行しない空の関数が替わりにリンクされます。

通常のコールバック呼び出し順序

init_coldboot()
  ↓ (TWENET内部処理:初期化1)
setup()
  ↓（TWENET内部処理:初期化2)
begin() --- 初回のみ
  ↓
loop() <--+
  ↓       |イベント処理、ビヘイビア処理
CPU DOZE -+

スリープ復帰時のコールバック呼び出し順序

the_twelite.sleep()
  ↓ sleeping...
 
 
init_warmboot()
  ↓ (TWENET内部処理:初期化3)
wakeup()
  ↓（TWENET内部処理:初期化4)
loop() <--+
  ↓       |イベント処理、ビヘイビア処理
CPU DOZE -+

TickTimerはTWENETの内部制御用に利用され、暗黙に実行されています。タイマーの周期は1msです。loop()中でTickTimerイベントにより1msごとの処理を記述する目的でavailable()メソッドのみを定義しています。

void loop() {
  if (TickTimer.available()) {
    if ((millis() & 0x3FF) == 0) { // これは処理されない場合がある
      Serial << '*';
    }
  }
}

メソッド

available()

inline bool available()

TickTimer割り込み発生後にセットされ、その直後のloop()でtrueになります。loop()終了後にクリアされます。

システム時刻[ms]を得ます。

uint32_t millis()

システム時刻はTickTimerの割り込みで更新されます。

パケットデータのバイト列を入力として、パケットの種別を判定します。戻り値はE_PKTです。

E_PKT identify_packet_type(uint8_t* p, uint8_t u8len)

特定のパケットであると解釈できなかった場合はE_PKT::PKT_ERRORが戻ります。

Unit_で始まるアクト(Act)は、ごく単機能の記述や動作を確認するためのものです。

コンテナクラス(smplbuf, smplque)のテンプレート引数として指定し、内部で利用するメモリの確保または領域指定します。

alloc_attachやalloc_heapではメモリ確保クラスに応じた初期化メソッド (init_???())を実行する必要があります。

初期化

バッファーp・サイズnで初期化します。

メソッド

alloc_size()

バッファのサイズを返す。

_is_attach(), _is_local(), _is_heap()

想定したallocクラスと違うメソッド呼び出し記述に対して、static_assertのように、コンパイルエラーを発生させるためのメソッドです。

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

uint8_t型のsmplbuf配列を参照したを経由して、による演算子やメソッドを用います。

ヘルパーオブジェクトの型名は長くなるためauto&&により解決しています。このオブジェクトに対して<<演算子などmwx::streamで定義されたインタフェースを利用できます。

生成されたヘルパーオブジェクトbsは生成時に大本の配列bの先頭位置から読み書きを始めます。配列の末尾の場合はappend()によりデータを追加します。読み書きを行うたびに位置は次に移動していきます

ヘルパー関数では読み出し用の>>演算子が利用できます。

SPIバス (MASTER) の読み書きを行います。

注意事項

定数

初期化と終了

SPIバスの利用手続きはbegin()メソッドによります。

begin()

void begin(uint8_t slave_select, SPISettings settings)
SPISettings(uint32_t clock, uint8_t bitOrder, uint8_t dataMode)

ハードウェアの初期化を行います。

例

void setup() {
  ...
  SPI.begin(0, SPISettings(2000000, SPI_CONF::MSBFIRST, SPI_CONF::SPI_MODE3));
  ...
}

void wakeip() {
  ...
  SPI.begin(0, SPISettings(2000000, SPI_CONF::MSBFIRST, SPI_CONF::SPI_MODE3));
  ...
}

end()

void end()

SPIのハードウェアの利用を終了します。

読み書き

読み書きの手続きは、以下の2種類あります。いずれかを選択して利用します。

• メンバ関数版 (以下のメンバ関数を用いた入出力) beginTransaction(), endTransaction(), transfer(), transfer16(), transfer32()

• ヘルパークラス版(stream機能が使用可能) transceiver

PAL_AMB のサンプルを少し改良して、センサーデータ取得中の待ち時間（約50ms)を、スリープで待つようにします。

アクトの解説

begin()

begin()関数はsetup()関数を終了し(そのあとTWENETの初期化が行われる)一番最初のloop()の直前で呼ばれます。

void begin() {
	sleepNow(); // the first time is just sleeping.
}

setup()終了後に初回スリープを実行します。setup()中にセンサーデータ取得を開始していますが、この結果は評価せず、センサーを事前に一度は動かしておくという意味あいで、必ずしも必要な手続きではありません。

wakeup()

起床後の手続きです。以下の処理を行います。

• まだセンサーデータの取得開始をしていない場合、センサーデータ取得を行い、短いスリープに入る。

• 直前にセンサーデータ取得開始を行ったので、データを確認して無線送信する。

void wakeup() {
	if (!b_senser_started) {
		// delete/make shorter this message if power requirement is harder.	
		Serial	<< mwx::crlf
				<< "--- PAL_AMB:" << FOURCHARS << " wake up ---"
				<< mwx::crlf
				<< "..start sensor capture again."
				<< mwx::crlf;

		startSensorCapture();
		b_senser_started = true;

		napNow(); // short period sleep.
	} else {
		Serial << "..wake up from short nap.." << mwx::crlf;

		auto&& brd = the_twelite.board.use<PAL_AMB>();

		b_senser_started = false;

		// tell sensors waking up.
		brd.sns_LTR308ALS.process_ev(E_EVENT_START_UP);
		brd.sns_SHTC3.process_ev(E_EVENT_START_UP);
	}
}

上記の分岐をグローバル変数のb_sensor_startedにより制御しています。!b_sensor_startedの場合はセンサー取得開始(startSensorCapture())を行い、napNow()により短いスリープに入ります。時間は100msです。

napNow()によるスリープ復帰後、b_sensor_started==trueの節が実行されます。ここでは、2つのセンサーに対してE_EVENT_START_UPイベントを通知しています。このイベントは、センサーの取得が終了するのに十分な時間が経過したことを意味します。この通知をもとにsns_LTR308ALSとsns_SHTC3はavailableになります。この後loop()に移行し、無線パケットが送信されます。

napNow()

ごく短いスリープを実行する。

void napNow() {
	uint32_t u32ct = 100;
	Serial << "..nap " << int(u32ct) << "ms." << mwx::crlf;
	the_twelite.sleep(u32ct, false, false, TWENET::SLEEP_WAKETIMER_SECONDARY);
}

sleepのパラメータの2番目をtrueにすると前回のスリープ復帰時刻をもとに次の復帰時間を調整します。常に5秒おきに起床したいような場合設定します。

3番目をtrueにするとメモリーを保持しないスリープになります。復帰後はwakup()は呼び出されじ、電源再投入と同じ処理になります。

4番目はウェイクアップタイマーの2番目を使う指定です。ここでは1番目は通常のスリープに使用して、2番目を短いスリープに用いています。このアクトでは2番目を使う強い理由はありませんが、例えば上述の5秒おきに起床したいような場合、短いスリープに1番目のタイマーを用いてしまうとカウンター値がリセットされてしまい、経過時間の補正計算が煩雑になるため2番目のタイマーを使用します。

TWELITE 無線マイコンの内蔵EEPROMに対して読み書きを実行します。

内蔵EEPROMはアドレス0x000～0xEFFまでの3480バイトが利用可能です。

先頭部分は設定（インタラクティブモード）に利用されるため、併用する場合は後半のアドレスの利用を推奨します。設定（インタラクティブモード）でどの程度の領域を消費するかは、その実装に依存します。最小限度の設定であっても先頭から256バイトまでは利用されるため、それ以降の利用を推奨します。

メソッド

read()

uint8_t read(uint16_t address)

EEPROMからaddressに対応するデータを読み出します。

write()

void write(uint16_t address, uint8_t value)

EEPROMからaddressに対してvalueを書き込みます。

update()

void update(uint16_t address, uint8_t value)

write()と同じく書き込みを行いますが、先にaddressにあるデータを読み出してvalueと違う場合のみ、書き込みを行います。EEPROMの書き換え寿命を考慮し、書換回数を減らしたいときに用います。

get_stream_helper()

auto&& get_stream_helper()
// 戻り値型は長くなるためauto&&と省略しています。

後述のmwx::streamを用いた読み書きを行うために、ヘルパーオブジェクトを取得します。

mwx::streamインタフェースを用いた入出力

stream_helper ヘルパーオブジェクトを経由して、mwx::streamによる演算子やメソッドを用います。mwx::streamを用いるとuint16_tやuint32_t型といった整数型の読み書き、uint8_tの固定長配列型の読み書き、format()オブジェクトによる書式整形などが可能になります。

auto&& strm = EEPROM.get_stream_helper();
// ヘルパーオブジェクトの型名は長くなるためauto&&により解決しています。

このオブジェクトに対して<<演算子などmwx::streamで定義されたインタフェースを利用できます。

strm.seek(1024); // 1024バイト目に移動

strm << format("%08x", 12345678); // 12345678を16進数の8文字で記録
strm << uint32_t(0x12ab34cd);     // 0x12ab34cd の4バイトを記録
uint8_t msg_hello[16] = "HELLO WORLD!";
strm << msg_hello;                // バイト列 "HELLO WORLD!" を記録(終端なし)

// 結果
// 0400: 30 30 62 63 36 31 34 65 12 ab 34 cd 48 45 4c 4c
//        0  0  b  c  6  1  4  e  0x12ab34cd  H  E  L  L
// 0410: 4f 20 57 4f 52 4c 44 21 00 00 00 00 ff ff ff ff
//        O SP  W  O  R  L  D  ! 

.seek()を用いてEEPROMのアドレスを1024に移動しています。

上記では８バイト文字列(00bc614e)、４バイト整数(0x12ab34cd)、16バイトバイト列(HELLO WORLD!...)、1バイト終端文字を書き込んでいます。

strm.seek(1024);

uint8_t msg1[8];
strm >> msg1;
Serial << crlf << "MSG1=" << msg1;
// MSG1=00bc614e

uint32_t var1;
strm >> var1;
Serial << crlf << "VAR1=" << format("%08x", var1);
// VAR1=12ab34cd

uint8_t msg2[16]; // "HELLO WORLD!"の文字数
strm >> msg2;
Serial << crlf << "MSG2=" << msg2;
// MSG2=HELLO WORLD!

.seek()を用いてEEPROMのアドレスを1024に移動しています。

先ほど書き出したデータ列を読み出します。順番に8バイト文字、4バイト整数、16バイト文字列を>>演算子を用いて読み出します。

３軸の加速度センサーの値を格納するための構造体ですが、コンテナクラスに格納したときの利便性を上げるための手続きを追加しています。

struct axis_xyzt {
    int16_t x;
    int16_t y;
    int16_t z;
    uint16_t t;
};

get_axis_{x,y,z}_iter()

/*戻り型は長いテンプレート型名なのでauto&&と記載します*/
auto&& get_axis_x_iter(Iter p)
auto&& get_axis_y_iter(Iter p)
auto&& get_axis_z_iter(Iter p)

axis_xyztを格納したコンテナクラスのイテレータをパラメータとして、X, Y, Z 軸のいずれかの要素にアクセスするイテレータを生成します。

以下の例では、buf.begin(), buf.end()をX軸用のイテレータとしてアルゴリズムstd::minmax_elementに用いています。

#include <algorithm>

void myfunc() {  
  // コンテナクラス
  smplbuf_local<axis_xyzt, 10> buf;
  
  // テスト用にデータを投入
  buf[0] = { 1, 2, 3, 4 };
  buf[1] = { 2, 3, 4, 5 };
  ...
  
  // 最大、最小値を得るアルゴリズム
  auto&& minmax = std::minmax_element(
    get_axis_x_iter(buf.begin()),
    get_axis_x_iter(buf.end()));
  
  Serial << "min=" << int(*minmax.first)
        << ",max=" << int(*minmax.second) << mwx::crlf;
}

get_axis_{x,y,z}()

/*戻り型は長いテンプレート型名なのでauto&&と記載します*/
auto&& get_axis_x(T& c)
auto&& get_axis_y(T& c)
auto&& get_axis_z(T& c)

axis_xyztを格納したコンテナクラスのXYZ軸のいずれかの軸を取り出した仮想的なコンテナクラスを生成する関数です。この生成したクラスにはbegin()とend()メソッドのみ実装されています。このbegin()とend()メソッドで取得できるイテレータは前節get_axis_{x,y,z}_iter()のイテレータと同じものになります。

#include <algorithm>

void myfunc() {
  // コンテナクラス
  smplbuf_local<axis_xyzt, 10> buf;
  
  // テスト用にデータを投入
  buf[0] = { 1, 2, 3, 4 };
  buf[1] = { 2, 3, 4, 5 };
  ...
  
  // キューの中の X 軸を取り出す
  auto&& vx = get_axis_x(que);
  
  // 範囲for文の利用
  for (auto&& e : vx) { Serial << int(e) << ','; }
  
  // 最大、最小値を得るアルゴリズム
  auto&& minmax = std::minmax_element(
      vx.begin(), vx.end());
                          
  Serial << "min=" << int(*minmax.first)
        << ",max=" << int(*minmax.second) << mwx::crlf;
}

パルスカウンタは、マイコンのCPUが稼働していない時もパルスを読み取り計数する回路です。パルスカウンターは２系統あります。PC0はPulseCounter0, PC1はPulseCounter1に割り当てられます。

またPulseCounterはPulseCounter1の別名です。

メソッド

begin()

void begin(uint16_t refct = 0, 
           E_PIN_INT_MODE edge = PIN_INT_MODE::FALLING,
           uint8_t debounce = 0)

オブジェクトを初期化し、計数を開始します。１番目のパラメータrefctは割り込みやavailable判定の基準となるカウント数です。この数を超えたときにアプリケーションに報告されます。またrefctには0を指定することもできます。この場合は、スリープ起床要因にはなりません。

２番目のパラメータedgeは割り込みが立ち会がり(PIN_INT_MODE::RISING)か立下り(PIN_INT_MODE::FALLING)を指定します。

３番目のdebounceは、0,1,2,3の値をとります。1,2,3の設定はノイズの影響を小さくするため値の変化の検出に連続した同じ値を要する設定です。

end()

void end()

検出を中止します。

available()

inline bool available()

指定カウント数(begin()のrefct)が０の場合は、カウントが１以上でtrueを返します。

指定カウント数(begin()のrefct)が1以上の場合は、検出回数が指定カウント数を超えた場合にtrueとなります。

read()

uint16_t read()

カウント値を読み出します。読み出し後にカウント値を０にリセットします。

このクラスはTWENETのtsRxDataApp構造体のラッパークラスです。

このクラスオブジェクトは、ビヘイビアのコールバック関数またはthe_twelite.receiver.read()により取得できます。

packet_rxでは、特にパケットのデータペイロードをsmplbufコンテナで取り扱えるようにし、expand_bytes()などのユーティリティ関数によりペイロードの解釈記述を簡素化しています。

メソッド

get_payload()

smplbuf_u8_attach& get_payload()

パケットのデータペイロードを取得する。

get_psRxDataApp()

const tsRxDataApp* get_psRxDataApp() 

TWENET Cライブラリの受信構造体を得る。

get_length()

uint8_t get_length()

ペイロードのデータ長を返す。.get_payload().size()と同じ値になる。

get_lqi()

uint8_t get_lqi()

LQI値 (Link Quality Indicator)を得る。

get_addr_src_long(), get_addr_src_lid()

uint32_t get_addr_src_long()
uint8_t get_addr_src_lid()

送信元のアドレスを得る。

get_addr_src_long()は送信元のシリアル番号で、MSB(bit31)が必ず１になります。

get_addr_src_lid()は送信元の論理IDで0x00-0xFEまでの値をとります（<NWK_SIMPLE>で指定する論理IDです）。

get_addr_dst()

uint32_t get_addr_dst()

宛先アドレスを得ます。

宛先アドレスは、送信元で指定され、宛先の種別によって値の範囲が変わります。

is_secure_pkt()

bool is_secure_pkt()

暗号化パケットの場合は true を返し、平文の時はfalse を返します。

pktparser(parser_packet)は、serparserで変換したバイト列に対して、内容の解釈を行います。

serparser_heap parser_ser;

void setup() {
    // init ser parser (heap alloc)
    parser_ser.begin(PARSER::ASCII, 256);
}

void loop() {
    int c;
    while ((c = Serial.read()) >= 0) {
        parser_ser.parse(c);
        if (parser_ser.available()) {
            // get buffer object
            auto&& payl = parser_ser.get_buf();
            // identify packet type
            auto&& typ = identify_packet_type(payl.begin(), payl.end());
            
            // if packet type is TWELITE standard 0x81 message
            if (typ == E_PKT::PKT_TWELITE) {
                pktparser pkt; // packet parser object
                // analyze packet data
                typ = pkt.parse<TwePacketTwelite>(payl.begin(), payl.end());
                
                if (typ != E_PKT::PKT_ERROR) { // success!
                    // get data object
                    auto&& atw = pkt.use<TwePacketTwelite>();
                    
                    // display packet inforamtion
                    Serial << crlf << format("TWELITE: SRC=%08X LQI=%03d "
                        , app.u32addr_src, app.u8lqi);
	                  Serial << " DI1..4="
	                      << atw.DI1 ? 'L' : 'H' << atw.DI2 ? 'L' : 'H' 
                        << atw.DI3 ? 'L' : 'H' << atw.DI4 ? 'L' : 'H';
                }
            }
        }
    }
}

上記の例は、標準アプリケーションの0x81メッセージの解釈を行っています。parser_serオブジェクトによりSerialより入力された電文をバイト列に変換します。このバイト列をまずidentify_packet_type()により電文の種別E_PKTを特定します。電文の種別が判定できたら次に.parse<TwePacketTwelite>()により電文を解析します。解析結果はTwePacketTwelite型になりますが、このオブジェクトを取り出す手続きが.use<TwePacketTwelite>()です。TwePacketTwelite型はクラスですが構造体として直接メンバー変数を参照します。

parse<T>

template <class T>
E_PKT parse(const uint8_t* p, const uint8_t* e)

バイト列を解析します。

Tには解析対象のパケット型を指定します。例えば標準アプリケーションの0x81メッセージならTwePacketTweliteを指定します。

pとeはバイト列の先頭と終端の次を指定します。

戻り値はE_PKT型です。エラーの場合はE_PKT::PKT_ERRORが戻ります。

user<T>

template <class T> 
T& use()

解釈したバイト列に対応するパケット型に対応するオブジェクトの参照を返します。事前にparse<T>を実行しエラーがなかった場合に呼び出すせます。

Tはparse<T>で実行した型と同じもの、または基本的な情報のみ取得できるTwePacketを指定します。

stream_helperは、mwx::streamインタフェースを付与するヘルパーオブジェクトです。データクラスを参照するヘルパーオブジェクトを生成し、ヘルパーオブジェクト経由でデータの入出力を行います。

以下にはsmplbufの配列bからヘルパーオブジェクトbsを生成しmwx::stream::operator <<()演算子によるデータ入力を行っています。

smplbuf_u8<32> b;
auto&& bs = b.get_stream_helper(); // ヘルパーオブジェクト

// データ列の生成
uint8_t FOURCHARS[]={'A', 'B', 'C', 'D'};
bs << FOURCHARS;
bs << ';';
bs << uint32_t(0x30313233); // "0123"
bs << format(";%d", 99);

Serial << b << crlf; // Serialへの出力は smplbuf_u8<32> クラス経由で

//結果: ABCD;0123;99

概要

stream_helper はデータ配列をストリームに見立てて振舞います。

内部にはデータ配列中の読み書き位置を保持しています。次のようにふるまいます。

• 読み出しまたは書き込みをすると次の読み書き位置に移動します。

• 最期のデータを読み出した後、またはデータを末尾に追記した後には、読み書き位置は終端となります。

• 読み書き位置が終端の場合、

  • available()がfalseになります。

  • 読み出しは出来ません。

  • 書き込みは書き込み可能範囲であれば追記します。

stream_helperの生成

stream_helper は、データクラス (smplbuf, EEPROM) のメンバー関数より生成します。

auto&& obj_helper = obj.get_stream_helper()
// obj はデータクラスのオブジェクト、obj_helperの型は長くなるのでauto&&で受けています。

メソッド

rewind()

void rewind()

読み書き位置を先頭に移動します。

seek()

int seek(int offset, int whence = MWX_SEEK_SET)

読み書き位置を設定します。

tell()

int tell()

読み書き位置を返します。終端位置の場合は-1を返します。

available()

int available()

読み書き位置が終端であれば0を返します。終端でなければそれ以外の値を返します。

mwx::stream の << 演算子に対してフォーマット書式を書き出すヘルパークラスです。ライブラリ内では Using format=mwx::mwx_format; として別名定義しています。

Serial << format("formatted print: %.2f", (double)3123 / 100.) << mwx::crlf;

// formatted print: 31.23[改行]

• コンストラクタで受け取った引数リストを、パラメータパックの展開機能を用いてクラス内部変数に格納する

• operator << が呼び出された時点で、fctprintf() を呼び出し、ストリームにデータを書き出す

コンストラクタ

format(const char *fmt, ...)

コンストラクタでは、書式のポインタとパラメータを保存します。続く <<演算子による呼び出しでフォーマットを解釈して出力処理を行います。

ここでは Windows 専用のプログラマ（書換）＆ターミナル機能を有した TWE_Programmer について解説します。

BINファイルの書き込みと実行

出来上がったBINファイルをTWELITEに書き込むにはTWE-Programmerを使用します。詳しい使い方はこちらを参照ください。

1. 事前に MONOSTICK や TWELITE R をPCに差し込んでドライバのセットアップを終了しておく。

デバイスが認識されれば、新たにCOMポートが追加されます。複数あってわかりにくい場合は、抜いた状態でのCOMポートと刺した状態でのCOMポートの様子を観察してみてください。

2. TWE-Programmer.exe を起動する。

{MWSDKインストールディレクトリ}/Tools/TWE-Programmerディレクトリを開き、TWE-Programmer.exe をダブルクリックします。

TWE-Programmer.exe を起動すると以下のような画面になります。画面例では、起動前に MONOSTICK を差し込んでいて COM6 に割り当てられています。

3. TWE-Programmer 上で BIN ファイルを指定する。

ファイルダイアログから BIN ファイルを指定します。

4. BINファイルの書き込み

BINファイルの書き込みは、BINファイルを指定すると自動で行われます。

5-1. 書き込み成功時

5-2. 書き込み失敗時

書き込みに失敗したときは、ターミナルは開かず、TWE-Programmerのウインドウ背景がピンク色になります。

WirelessUARTはシリアル通信を行います。

アクトの機能

• ２台のUART接続のTWELITE同士をアスキー書式で通信する。

アクトの使い方

必要なTWELITE

いずれかを２台。

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

アクトの解説

setup()

論理IDはrandom(1,5)により1,2,3,4のいずれかの値に割り当てています。通常は、論理IDを設定保存したデータ、またはDIP SWといったハードウェアの情報から生成します。

を初期化します。

loop()

シリアルからのデータ入力があった時点で、シリアルパーサーに１バイト入力します。アスキー形式が最後まで受け付けられた時点でSerialParser.parse()はtrueを戻します。

SerialParserは内部バッファに対してsmplbufでアクセスできます。上の例ではバッファの１バイト目を送信先のアドレスとして取り出し、２バイト目から末尾までをtransmit()関数に渡します。

パケットを受信したときには、送信元を先頭バイトにし続くペイロードを格納したバッファsmplbuf_u8<128> bufを生成し、出力用のシリアルパーサーserparser_attach poutからシリアルに出力しています。

テスト用のコマンド

例

任意の子機宛に00112233を送付します。

例

子機３番に対してAABBCC00112233を送付します。

MWSDKをインストールしたディレクトリを開きます。以下のような構成になっています。TWELITE STAGE SDKをインストールした場合は、../MWSTAGE/MWSDKがそのディレクトリです。

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

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

• センサー値を取得する

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

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

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

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

では、アクトの中から PingPong のディレクトリの中を見てみましょう。

必ずディレクトリ直下にディレクトリと同名の .cpp ファイルが必要です。

次にビルドディレクトリを開きます。

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

ビルドの実行は、このbuildディレクトリに移動してmakeを実行します。以下はコマンドラインの例です。

を実装し TWELITE の UART0 で入出力する。

• Serialオブジェクトはシステム起動時に UART0, 115200 bps で初期化され、ライブラリ内で初期化処理が行われます。ユーザコード上は、setup()から利用できます。

• Serial1オブジェクトは、ライブラリ内で用意されていますが、初期化処理は行っていません。UART1を有効化するためには、必要な初期化手続き Serial1.setup(), Serial1.begin() を行ってください。

setup()

オブジェクトの初期化を行う。

• TX/RX用のFIFOバッファのメモリ確保

• TWE_tsFILE 構造体のメモリ確保

begin()

ハードウェアの初期化を行う。

end()

（未実装）ハードウェアの使用を停止する。

get_tsFile()

Cライブラリで利用する TWE_tsFILE* 形式での構造体を得る。

を用いたアクト例です。

パルスカウンターは、マイコンを介在せず信号の立ち上がりまたは立ち下りの回数を計数するものです。不定期のパルスを計数し一定回数までカウントが進んだ時点で無線パケットで回数を送信するといった使用方法が考えられます。

アクトの機能

• 子機側のDIO8に接続したパルスを計数し、一定時間経過後または一定数のカウントを検出した時点で無線送信する。

• 子機側はスリープしながら動作する。

アクトの使い方

必要なTWELITE

アクトの解説

setup()

パルスカウンターの初期化を行います。

begin()

パルスカウンターの動作を開始し、初回スリープを実行します。PulseCounter.begin()の最初のパラメータは、起床割り込みを発生させるためのカウント数100で、２番目は立ち下がり検出PIN_INT_MODE::FALLINGを指定しています。

wakeup()

起床時にPulseCounter.available()を確認しています。availableつまりtrueになっていると、指定したカウント数以上のカウントになっていることを示します。ここではfalseの場合再スリープしています。

カウント数が指定以上の場合はloop()で送信処理と送信完了待ちを行います。

loop()

パルスカウント値の読み出しを行います。読み出した後カウンタはリセットされます。

二線シリアル(I2C) master の読み書きを行います。

別名定義

mwx::periph_wire<MWX_TWOWIRE_RCVBUFF>はTwoWireとして参照可能です。

型定義

以下の定義型で引数や戻り値の型を記載します。

注意事項

初期化と終了

Wire インスタンスの生成

ライブラリ内でインスタンスの生成と必要な初期化は行われます。ユーザコードでは Wire.begin() を呼び出すことで利用可能となります。

requestFrom() メソッドを用いる場合、データを一時保管するための FIFO キューのサイズを指定できます。コンパイル時にマクロMWX_TWOWIRE_BUFF に必要なバイト数を指定してコンパイルする。デフォルトは 32 バイトです。

例： -DMWX_TWOWIRE_BUFF=16

begin()

ハードウェアの初期化を行います。

例

読み書き

読み書きの手続きは、以下の2種類あります。いずれかを選択して利用します。

• requestFrom(), beginTransmission(), endTransmission(), write()

• reader, writer

その他

プローブ（デバイスの存在判定)

address で指定したデバイスが応答するかを確認します。デバイスが存在する場合は true が戻ります。

setClock()

本来はバス周波数を変更するための手続きですが、何も処理をしません。

uint8_t型のsmplbuf_strm_u8???はインタフェースも有しているため、いくつかのストリーム用のメソッドを使用することができます。

例

ポーリングによる時間待ちを行います。

msにて与えられた期間待ち処理を行います。

時間の計測はTickTimerのカウントによって行っています。また長い時間待ちを行う場合はCPUのクロックを低下してポーリング処理を行います。

入力設定のポートの値を読み出す。

事前に入力に設定したピンの入力値をLOWまたはHIGHで得ます。