ToCoNet SDK 非公式マニュアル¶

本マニュアルは、ToCoNet SDK (2014年6月版)付属のマニュアルを参考に、よりわかりやすいものを目指し、また Read The Docs で表示できるように書き直したものです。

警告

本マニュアルは公式SDKに可能な限り準拠して作成していますが、一部の内容に誤りがあったり、また古い情報が含まれている可能性があります。最新かつ正確な情報については、公式マニュアルを参照して下さい。

目次¶

SDKのインストール¶

TODO

動作環境¶

TODO

ファームウェアを書き込む¶

書き込み用のツール¶

TWE-Progurammer (GUIプログラマ) — C:\TWESDK\Tools\TWE-Programmer
jenprog (CUIプログラマ) — C:\TWESDK\Tools\jenprog
TWE_PGM_MODE (CUI ToCoStick, TWE-Lite-R用リセットツール) — C:\TWESDK\Tools\TWE-RstPrg

libToCoNet¶

libToCoNetは、アプリケーションのイベント処理、基本的な無線通信システムの管理を行うライブラリです。

ネットワーキング機能¶

ToCoNetでは、以下に挙げる2種類の方法で通信を行うことができます。

ネットワークレス
- ToCoNetの中継機能を利用せず、電波の到達可能な範囲内の端末と直接パケット交換を行います。
- 事前設定が不要です。
- この通信方式の場合、ToCoNetでは中継機能は提供しませんが、アプリケーション側で自力で実装することも可能です。
LayerTree ネットワーク
- LayerTreeは、自身の中継深さ(親機からのホップ数)を指定する事で、木構造のネットワークを構成し、中継処理を行います。

ネットワークレス¶

ネットワーク機能を使用せずに通信を行う場合、以下のようなToCoNetの機能を利用することができます。

近隣探索 — 電波範囲内に存在するノードのアドレスや通信電波強度を列挙する
エナジースキャン — 指定したチャネルのノイズレベルを返す
同報通信
アドレスを指定したACK確認付きの通信
MAC層の再送に加えアプリケーションによる再送(回数・ランダム設定可能な遅延時間・再送間隔の指定可能)

LayerTreeネットワーク機能¶

コールバック関数¶

アプリケーションは、以下に挙げるコールバック関数を定義する必要があります。

libToCoNetは、イベント発生時に以下のコールバック関数を呼び出します。

void cbAppColdStart(bool_t bStart)¶

電源投入・リセット後に最初にアプリケーションで呼ばれる関数です。

本関数は2回呼び出されます。

1回目は引数 bStart に FALSE が渡されます。

このとき、アプリケーションが行える処理はモジュールの登録処理のみです(モジュールの宣言 を参照)。
2回目は引数 bStart に TRUE が渡されます。

ここでは、アプリケーションで使用する大域変数やペリフェラルの初期化などが行えますが、次の処理を行う必要があります。
- sToCoNet_AppContext の初期化を行う必要があります。少なくともフィールド u32AppId の設定が必要ですが、それ以外のフィールドに関しては設定は必須ではありません。

void cbToCoNet_vMain()¶

ToCoNetのメインループで毎回呼び出される、すなわち割り込みが発生するなどして CPUがウェイクアップしたときに呼び出される関数です。

割り込みの契機の一つとして Tickタイマー がありますので、本関数は少なくともTickタイマー以上の頻度で呼び出されます。

void cbToCoNet_vRxEvent(tsRxDataApp *psRx)¶: パケットを受信した際に呼び出されます。

void cbToCoNet_vTxEvent(uint8 u8CbId, uint8 bStatus)¶

グローバル変数¶

libToCoNetでは、以下のグローバル変数が定義されています。

tsToCoNet_AppContext sToCoNet_AppContext¶

ToCoNetのパラメータを設定するのに使用するグローバル変数です。 cbAppColdStart() が引数 TRUE を指定して呼び出されている間のみ設定できるフィールドがあります。

uint32 u32AppId¶

アプリケーションの識別子を32ビットで指定します。次の値は指定できません。

0x????0000, 0x????ffff
0x0000ffff, 0xffff????

cbAppColdStart() でのみ指定できます。

既定値は 0xffffffff です。

uint32 u32ChMask¶

利用する無線チャネルの一覧をビットマスクで指定します。例えば、チャンネル12, 14のみを使用する場合、 1UL<<12 | 1UL<<14 を指定します。TWE-Strongではチャンネル26は使用できません。

既定値は 0x07fff800 (チャンネル11〜26) です。

チャンネルの指定には、モジュール MOD_CHANNEL_MGR, MOD_NBSCAN, MOD_NBSCAN_SLAVE, MOD_LAYERTREE が必要となります(モジュールの一覧 を参照)。

uint16 u16ShortAddress¶

無線モジュールの16ビットのショートアドレスを設定します。 0xffff を指定することはできません。

既定値は無線モジュールのシリアル番号から自動生成されます。

uint8 u8Channel¶

利用する 単一の 無線チャネルを指定します。 u32ChMask で指定したチャネルの中から指定してください。

モジュール MOD_CHANNEL_MGR を使用している場合、u8Channel の設定は無視されます。

既定値は 18 です。

uint8 u8CPUClk¶

通常稼働時のCPUクロックを次の中から一つ選択します。

値	CPUクロック
0	4MHz
1	8MHz
2	16MHz
3	32MHz

cbAppColdStart() 以外での変更は推奨されません。

既定値は 2 (16MHz) です。

uint8 u8TxPower¶

モジュールの無線出力を次の中から一つ選択します。

値	出力
0	-34.5db
1	-23db
2	-11.5db
3	最大

既定値は 3 (最大) です。

uint8 u8TxMacRetry¶

MAC層でのパケットの最大再送回数を0以上8未満で指定します。

既定値は 3 です。

bool_t bRxOnIdle¶

TRUE を指定すると、アイドル時にも受信回路を動作させます。これにより、受信が可能な状態となりますが、常に電力を消費するようになります。

ネットワーキング機能を利用する場合は、必ず TRUE を指定してください。

既定値は FALSE (受信回路を動作させない) です。

uint8 u8HigherDataRate¶

高速モードの設定を次の中から一つ選択します。

値	速度
0	250kbps
1	500kbps
2	667kbps

TWE-Lite では高速モードに対応していないため、無視されます。

cbAppColdStart() でのみ指定できます。

既定値は 0 (250kbps) です。

uint8 u8CCA_Retry¶

CCAのリトライ回数を指定します。通常は変更する必要はありません。

TWE-Lite では無視されます。

uint8 u8CCA_Level¶

CCAアルゴリズムの開始レベルを指定します。通常は変更する必要はありません。

TWE-Lite では無視されます。

uint8 u8RandMode¶

ToCoNet内部で使用する乱数源を次の中から一つ選択します。

値	乱数源
0	ハードウェア乱数生成器
1	システム経過時間
2	モジュール `MOD_RAND_MT`
3	モジュール `MOD_RAND_XOR_SHIFT`

2 または 3 を使用する場合、モジュールを使用できるようにする宣言が必要です(モジュールの宣言 を参照)。

uint16 u16TickHz¶

Tickタイマー の周期を次の中から一つ選択します。

値	周期
1000	1ms
500	2ms
250	4ms
200	5ms
100	10ms

cbAppColdStart() 以外での変更は推奨されません。

bool_t bSkipBootCalib¶: TRUE を指定すると、スリープからの復帰時に行われるRC 32kHzクロック (Wake Timerに使用されます) のキャリブレーション処理が省略されます。

ユーザ定義イベント¶

TODO

コールバック¶

ユーザ定義イベント処理関数で使用するコールバックは以下の形式である必要があります。名前やスコープに制約はありませんが、引数と返り値の型が一致している必要があります。

void UserEventHandler(tsEvent *pEv, teEvent eEvent, uint32 u32evarg)¶: ユーザ定義イベントが発生した際に呼び出されます。

ライフサイクル¶

電源が投入、あるいはリセットされると、最初にアプリケーションの cbAppColdStart() が cbAppColdStart(FALSE) のようにして呼び出されます。アプリケーションはここではモジュールの宣言のみを行う必要があります (モジュールの宣言 を参照)。
続いて、 cbAppColdStart(TRUE) が呼び出されるので、アプリケーションは必要に応じて初期化処理を行います。
ユーザ定義イベント処理関数 が登録されている場合、:c:macro::E_EVENT_START_UP イベントが発生し、ユーザ定義イベント処理関数が呼び出されます。
スリープ・電源断まで継続的にイベント処理が行われます。イベントが発生した場合、アプリケーションで定義された以下の関数のうちいずれかを呼び出します(リファレンスマニュアルの コールバック関数 を参照)。
- cbToCoNet_vMain() — 割り込みに起因するイベントの後 (前? 最中?) に呼び出されます。
- cbToCoNet_vRxEvent() — 無線通信によりパケットを受信した時に呼び出されます。
- cbToCoNet_vTxEvent() — 無線通信によりパケットを送信した後、送信が完了した時に呼び出されます。
- cbToCoNet_vNwkEvent() — MAC層やネットワーク層でイベントが発生した際に呼び出されます。
- cbToCoNet_vHwEvent() — ペリフェラルの割り込みが発生した後に呼び出されます。
- cbToCoNet_u8HwInt() — ペリフェラルの割り込みが発生した時に呼び出されます。
- この他にも、ユーザ定義イベント処理関数 が登録されている場合は呼び出されることがあります。

ToCoNet_vSleep() が呼び出されると、TWEモジュールはスリープ状態に入ります。

スリープ状態から復帰した場合、以下のようにして通常処理に復帰します。

アプリケーションの cbAppWarmStart() が cbAppWarmStart(FALSE) のように呼び出されます。ここでは、スリープ復帰要因を取得することができますが、ペリフェラル等の使用はできません。(?)
アプリケーションの cbAppWarmStart(TRUE) が呼び出されます。ここで必要に応じて初期化処理を行います。
ユーザ定義イベント処理関数 が登録されている場合、E_EVENT_START_UP イベントが発生し、ユーザ定義イベント処理関数が呼び出されます。
この後、通常のイベント処理に復帰します。

警告

イベント処理が滞ってしまうため、コールバック関数で時間の掛かる処理をしてはいけません。

モジュールの一覧¶

警告

ここで使用する「モジュール」はToCoNetライブラリを機能別に分割したものを指すもので、 TWEのハードウェアを指すものではありません。

MOD_ENERGYSCAN — チャネルの入力レベルを測定するのに使用するモジュールです。
MOD_NBSCAN — 電波到達範囲内に存在するTWEを検索するのに使用します。
MOD_RAND_MT — MT法を使用した高品位な疑似乱数生成を行うモジュールです。 ( 注意このモジュールを使用する場合、ライセンス表記が必要です。 )
MOD_RAND_XOR_SHIFT — Xorshiftによる高速な疑似乱数生成を行うモジュールです。
MOD_NWK_LAYERTREE — LayerTreeネットワークを実現するモジュールです。( 注意 MOD_DUPCHK が必要です。 )
MOD_NWK_LAYERTREE_MININODES — ?
MOD_DUPCHK — パケットの重複チェックを行うモジュールです。
MOD_NWK_MESSAGE_POOL — メッセージプール機能を実装するモジュールです。
MOD_CHANNEL_MGR — チャネルアジリティを実装するモジュールです。
以下のモジュールはメッセージの送信キューを実装するモジュールですが、送信キューのサイズによって別のモジュールに分かれていますので、一度に送信できるメッセージの個数とメモリ消費量を考慮して、いずれか1つを選択して下さい。 (いずれも選択しない場合は、MOD_TXRXQUEUE_MID が使用されます。)
- MOD_TXRXQUEUE_SMALL — 最大3個のメッセージを送信キューに含むことができます。 384バイトのRAMを占領します。
- MOD_TXRXQUEUE_MID — 最大6個のメッセージを送信キューに含むことができます。 768バイトのRAMを占領します。
- MOD_TXRXQUEUE_BIG — 最大20個のメッセージを送信キューに含むことができます。 2560バイトのRAMを占領します。

モジュールの宣言¶

ToCoNetのモジュールを使用する際は、ソースコードに以下の修正を行い、使用するモジュールを宣言する必要があります。

#include "ToCoNet.h" の前で、適切なプリプロセッサ定義を行う。:

// MOD_RXQUEUE_BIG を使用する場合、以下のような定義を行います。
#define ToCoNet_USE_MOD_RXQUEUE_BIG

// MOD_CHANNEL_MGR を使用する場合、以下のような定義を行います。
#define ToCoNet_USE_MOD_CHANNEL_MGR

#include "ToCoNet.h"
#include "ToCoNet_mod_prototype.h"

cbAppColdStart(FALSE) が呼び出された際に、ToCoNet_REG_MOD_ALL() を呼び出すようにする。:

void cbAppColdStart(bool_t bStart) {
  if (!bStart) {
    ToCoNet_REG_MOD_ALL();
  } else {
    /* (以下略) */
  }
}

`sToCoNet_AppContext` の初期化¶

cbAppColdStart(TRUE) が呼び出された際、アプリケーションはグローバル変数 sToCoNet_AppContext のフィールドの値を適切な値に初期化する必要があります。

Tickタイマー¶

ToCoNetの初期化が完了した後、 Tickタイマー と呼ばれるタイマーがスリープ時を除いて常に作動し、周期的に割り込みが発生します。

Tickタイマーの周期は sToCoNet_AppContext. u16TickHz で指定することができます。

ToCoNet SDK 非公式マニュアル¶

目次¶

SDKのインストール¶

動作環境¶

ファームウェアを書き込む¶

書き込み用のツール¶

libToCoNet¶

ネットワーキング機能¶

ネットワークレス¶

LayerTreeネットワーク機能¶

コールバック関数¶

グローバル変数¶

ユーザ定義イベント¶

コールバック¶

ライフサイクル¶

モジュールの一覧¶

モジュールの宣言¶

sToCoNet_AppContext の初期化¶

Tickタイマー¶

`sToCoNet_AppContext` の初期化¶