ビヘイビアは、指定の方法でクラスを定義することで、the_twelite
クラスオブジェクトに登録できるようになります。登録したビヘイビアはTWENETに組み込まれて動作し、ユーザコードではアプリケーションの振る舞いを記述できるようになります。ループでの記述ではできなかったTWENETからの割り込みやイベントのコールバック関数を定義することが出来ます。ループでの記述に比べ、定義が多くなりますが、より複雑なアプリケーションを記述するのに向いています。
ビヘイビアのサンプルPAL_AMB-behaviorを参照してください。
ビヘイビアの定義には下記に示すようなクラス定義が必要です。
上記の例ではMY_APP_CLASSという名前でビヘイビアクラスを定義しています。いくつかの箇所にMY_APP_CLASSの記述が必要です。
クラス名の定義と、ベース(親)クラスの定義をします。MWX_APPDEFS_CRTP()
はマクロです。
ここでは必要な定義を #include
により取り込んでいます。
コンストラクタの定義です。
メインループで、グローバル定義のloop()
と同じ役割の関数です。
on_create()
はオブジェクト生成時(use<>()
メソッド)に呼び出されます。val
は将来の拡張のためのパラメータです。
on_begin()
はsetup()
終了後に呼び出されます。val
は将来の拡張のためのパラメータです。
スリープ前に呼び出されます。val
は将来の拡張のためのパラメータです。
スリープ復帰時の初期段階で呼び出されます。val
は将来の拡張のためのパラメータです。
この時点でまだペリフェラルが初期化されていません。スリープ起床要因の確認ができます。
スリープ復帰時に呼び出されます。val
は将来の拡張のためのパラメータです。
ここでスリープ呼び出しも可能です。
パケットが受信されたとき、受信したパケット情報をrx
として呼び出されます。
パケット送信完了時に送信情報をevTx
として呼び出されます。evTx.u8CbId
が送信時のIDでevTx.bStatus
が送信の成功(1
)失敗(0
)を示すフラグです。
ビヘイビアのハンドラ(割り込み、イベント、状態定義)はcppファイルに定義します。ファイルは分割できず、全てのハンドラ定義を一つのファイル中に記述します。
ハンドラの定義をしないビヘイビアの場合でも、必ず、下記のcppファイルを作成します。
cppファイルの冒頭と末尾にはMWXライブラリの必要な定義(#include "_mwx_cbs_cpphead.hpp"
)をインクルードする必要があります。
ファイルの冒頭には、上記のようにビヘイビア定義の.hppファイルをインクルードします。__MWX_APP_CLASS_NAME
にはビヘイビアのクラス名を指定します。上記ではMY_APP_CLASS
です。
ファイルの末尾では必要な定義(#include "_mwx_cbs_cpptail.cpp"
)をインクルードします。
ハンドラ定義は以下の例のように記述します。定義の種別については後述します。定義用のマクロを用いて利用したいハンドラの定義を記述します。利用しないハンドラは記述しないようにしてください。
MWX_???_INT()
は割り込みハンドラの定義、MWX_???_EVENT()
はイベントハンドラの定義、MWX_STATE()
はステートマシンの状態定義です。
割り込みハンドラは、マイコンの割り込みが発生したときに現在実行中のコードを中断して実行されます。このため、可能な限り短い処理を記述することが望ましく、また、変数等の操作に対しても細心の注意が必要です。
割り込みハンドラのパラメータにはuint8_t& handled
があり、この値をtrue
にセットすることで、続くイベント呼び出しを行いません。
handled
がfalse
のまま割り込みハンドラを終了した場合、アプリケーションループ(通常コード)の中でイベントハンドラが呼び出されます。イベントハンドラにはhandled
のパラメータはありません。イベントハンドラは通常コードですので、比較的大きな処理を行うことが出来ます。イベントハンドラのオーバーヘッドも発生するため、頻繁な割り込み都度呼び出されるような処理の場合、処理しきれなくなる可能性があります。また、イベントの発生はシステム内部のFIFOキューにより処理されるため、一定時間内に処理できない場合はイベントが消失する場合もあります。
以下にハンドラ関数定義用のマクロの解説を行います。
DIO(ディジタルIO)割り込み・イベントです。N
は対象DIOの番号を指定します。arg
は将来の拡張のための定義です。
割り込みを発生させるためにはpinMode()
による適切な入力設定, attachDioInt()
による割り込み開始の設定が必要です。
TickTimer割り込み・イベントです。arg
は将来の拡張のための定義です。
TickTimerのhandled
フラグをtrue
にセットしてはいけません。TWENETが動作しなくなります。
タイマー割り込み・イベントです。N
は対象タイマーの番号を指定します。arg
は将来の拡張のための定義です。
割り込みを発生させるためには、Timerオブジェクトをソフトウェア割り込みを有効にして開始します。
MWXライブラリで標準的に定義しない、その他の割り込み・イベントの定義です。AHIペリフェラルマニュアルの理解が必要です。
その他の割り込み・イベントは以下のハンドラ関数で受けることが出来ます。これらは将来的に専用のハンドラが定義された場合、利用できなくなります。
ペリフェラル (AHI) の割り込みハンドラのu32DeviceId
がarg
、u32ItemBitmap
がarg2
に対応します。
状態マシン(ステートマシン)は、メッセージを受け取り、そのメッセージに応じて状態を遷移させながら動作させるアプリケーションの記述方法です。
PAL_AMB-behaviorサンプルでは、センサーの動作開始からセンサーの値取得、無線パケット送信から送信完了まで、スリープ遷移といったアプリケーションの動作の流れを記述しています。実例として参考にしてください。
受け取るイベントは以下となります。
状態をs
に設定します。
状態ハンドラを抜けると次の状態に遷移し、続けてE_EVENTS_NEW_STATE
イベントで状態ハンドラが呼び出されます。
状態遷移してからの経過時間[ms]を返します。タイムアウトを管理するような目的で使用します。
上記の例では100ms経過した時点でシステムリセットを行います。
状態ハンドラ外から呼び出します。状態ハンドラをイベントev
パラメータu32evarg
で実行します。
送信完了イベントを状態マシンに伝えます。つまり状態ハンドラの呼び出しを行います。
直接状態ハンドラを呼び出すことは行わないでください。E_EVENT_NEW_STATE
が実行されないなどの問題が発生します。
スリープ直前に設定します。スリープ復帰後に、直前の状態を維持します。つまり、スリープを開始した状態でE_EVENT_START_UP
で状態ハンドラが呼び出されます。
イベントが起床時のE_EVENT_START_UP
かどうか判定します。
イベントがスリープ復帰時のE_EVENT_START_UP
かどうか判定します。
環境センサーパル AMBIENT SENSE PAL を用い、センサー値の取得を行います。
このアクトの解説の前にBRD_APPTWELITEの解説、PAL_AMBの解説、PAL_AMB-usenapの解説を参照してください。またビヘイビアの解説についても参照ください。
このサンプルはビヘイビアの記述方法のサンプルです。ビヘイビアはより複雑なアプリケーションを記述する際に用います。
環境センサーパル AMBIENT SENSE PAL を用い、センサー値の取得を行います。
コイン電池で動作させるための、スリープ機能を利用します。
親機にPALを使用する場合は、コイン電池での動作はできません。目安として50mA以上の電流を安定して得られるような電源環境を用意してください。
PAL_AMB-behavior.hpp : setup()
のみの定義です。DIP-SWを読み出し、D1..D3が上位置の場合は親機として動作し、それ以外は子機としてDIP SWに対応するIDをセットします。
Parent/myAppBhvParent.hpp : 親機用のビヘイビアクラス定義
Parent/myAppBhvParent.cpp : 実装
Parent/myAppBhvParent-handlers.cpp : ハンドラーの実装
Parent/myAppBhvParent.hpp : 子機用のビヘイビアクラス定義
Parent/myAppBhvParent.cpp : 実装
Parent/myAppBhvParent-handlers.cpp : ハンドラーの実装
親機のビヘイビア名は<MY_APP_PARENT>
、子機は<MY_APP_CHILD>
です。
ビルドファイルの追加はMakefileの解説を参照してください。
DIP SWの読み値が0の場合は親機用のビヘイビア<MY_APP_PARENT>
を、それ以外の場合は子機用のビヘイビア<MY_APP_CHILD>
を登録します。
親機がMONOSTICKの場合は、PAL用のDIP SWの読み値は0となり、親機としてふるまいます。ただしこの動作はMONOSTICKの仕様として定義されているものではありません。
親機はスリープをしない受信機としてふるまい、子機からのパケットを受信したときにシリアルポートにパケットの情報を出力します。
親機用がパケットを受信したときは、パケットの先頭4文字が照合(FOURCHARS
)できれば、そのパケット内容を表示します。
親機の割り込みハンドラはLEDの点滅を行います。
PAL上のボタン(5)が押されたときには、状態マシンに対してE_ORDER_KICK
イベントを発行します。
状態マシンは、状態遷移の参考として記述したもので、アプリケーションの動作上意味のあるものではありません。ボタンから送付されるE_ORDER_KICKイベントによる状態遷移や、タイムアウトなどを実行しています。
子機の動作の流れはPAL_AMB-usenapと同じです。初回スリープから「起床→センサー動作開始→短いスリープ→起床→センサー値取得→無線送信→無線送信完了待ち→スリープ」を繰り返します。
on_begin()
から呼び出される_begin()
関数では、初回スリープを実行しています。
(※_begin()
関数で本処理を記述せずon_begin()
に直接記述してもかまいません)
スリープからの起床処理を記述しています。
ここで初回のWire.begin()
を実行しています。2回目以降のスリープ起床時では冗長な記述です。この処理はon_begin()
に移動してもかまいません。
送信完了時に状態マシンに対してE_ORDER_KICK
メッセージを処理します。
状態名を定義しています。
SHTC3用のセンサー取得実装例です。送付コマンド等の詳細はSHTC3のデータシートなどを参考にしてください。
LTR308ALSのセンサー取得実装例です。送付コマンド等の詳細はLTR308ALSのデータシートなどを参考にしてください。
WireWriteAndGet()
はaddr
のデバイスに対してcmd
を1バイト送信してから、1バイト受信して値を返します。
0番の状態は特別な意味を持ちます。起動直後またはスリープ復帰後の状態です。
起動直後PEV_is_coldboot(ev,evarg)
判定がtrue
になって呼び出されます。on_begin()
から、そのままスリープしてしまうため、状態遷移するようなコードも含まれません。この時点では主要な初期化がまだ終わっていませんので、無線パケットの送信など複雑な処理を行うことが出来ません。そのような処理を行うための最初の状態遷移を行うためにはon_begin()
からイベントを送り、そのイベントに従って状態遷移を行います。
スリープ復帰後はPEV_is_warmboot(ev,evarg)
がtrue
になる呼び出しが最初にあります。PEV_SetState()
を呼び出しSTATE_SENSOR
状態に遷移します。
スリープ復帰後STATE_IDLE
から遷移したとき、STATE_SENSOR
の状態ハンドラが続けて呼び出されます。この時のイベントev
はE_EVENT_NEW_STATE
です。
ここではSHTC3, LTR308ALSの2センサーの動作開始を行います。一定時間経過すれば、センサーはデータ取得可能な状態になります。この時間待ちを66
ms設定のスリープで行います。スリープ前にPEV_KeepStateOnWakeup()
が呼ばれている点に注意してください。この呼び出しを行うと、スリープ復帰後の状態はSTATE_IDLE
ではなく、スリープしたときの状態、つまりSTATE_SENSOR
となります。
短いスリープから復帰するとPEV_is_warmboot(ev,evarg)
判定がtrue
となる呼び出しが最初に発生します。この呼び出し時点で、無線パケットの送信などを行うことが出来ます。STATE_TX
に遷移します。
ここではE_EVENT_NEW_STATE
イベントの時に、センサーデータ読み出し、無線パケットの送信手続きに入ります。送信手続きの詳細は他のアクトサンプル例を参考にしてください。
送信完了まちの処理はループでのアクト記述と違い、transmit_complete()
からのPEV_Process()
によるメッセージを待つことで完了確認としています。メッセージを受け取った時点でスリープします。スリープ処理はSTATE_SLEEP
に遷移することで行っています。
最後にタイムアウト処理を行っています。万が一送信パケットの完了メッセージが戻ってこなかった場合を想定します。PEV_u32Elaspsed_ms()
はその状態に遷移してからの経過時間を[ms]で返します。時間経過した場合は、上記では(このタイムアウトは余程のことだとして)システムリセットthe_twelite.reset_system()
を行います。
スリープを行います。前の状態から遷移した直後のE_EVENT_NEW_STATE
に記述します。スリープ直前に他のイベントが呼ばれる可能性がありますので、必ず1回だけ実行される判定式の中でthe_twelite.sleep()
を実行してください。
役割
例
親機
子機
イベント名
内容
E_EVENT_START_UP
システム始動時に呼び出される。電源投入直後はパラメータが0
で呼び出されます。実行初期であるため、通常処理を行う状態に遷移する場合は一旦begin()メソッドからPEV_Process()
を呼び出し動作を開始させます。
スリープ復帰後も呼び出されるがパラメータは0
以外です。この状態からは通常処理を行えます。
E_EVENT_NEW_STATE
状態遷移直後に新しい状態で呼び出されます。ある状態に遷移したときに最初に実行される処理を記述します。
E_EVENT_TICK_TIMER
1msごとのTickTimerで呼び出されます。
E_EVENT_TICK_SECOND
1秒毎に呼び出されます。