XBee利用のためのライブラリ xbeemicrolib


XBeeを使うためのライブラリを自前で作りました.まだまだドラフトバージョンですが,これを使ったプログラミングフレームワークを提供する予定です.


デモ1.Coronに移植したxbeemicrolibを使って,CoronとPCとの通信を行っています.

デモ2.CQ Maryに移植したxbeemicrolibを使って,Maryを計2台とPCとの3台で通信しています

以下のタブを変更しながら見てください

概要
ディジインターナショナル社のZigBee通信モジュール「XBee-ZB」をマイコンやPCから使うためのライブラリを開発しています.ライブラリというよりはフレームワークに近い作りになりましたが,どうせいずれはフレームワークを作るつもりだったので,これで行きます.

(libxbeeはすでに存在していたので名称をxbeemicrolibに変更しました)

XBeeには複数の製品がありますが,今回対応が確認できているのは,XBee-ZBというシリーズです.
製品名の下に「Series2」という刻印があります.

XBeeは最低2台必要です.
1つのネットワークに,コーディネータと呼ばれるXBeeが1台必要です.これ以外にエンドデバイスと,ルーターという2種類のXBeeが配置できます.
コーディネータを使うかエンドデバイスにするかは,ファームウェアで変わります
つまりまず,製品のファームウェアをX-CTUでアップデートする必要があります.
X-CTUによるアップデートの項をお読みください.

現在はPC版,CQ Mary版,Coron版が公開されております.

ダウンロード
概要と使い方,を良くお読みのうえお使いください.

このライブラリを使ったことによる損害に対して,ysugaは一切責任を負いません.
このライブラリのライセンスはGPLです.その他のライセンス契約を希望される方はysugaまでご連絡ください.

「コーディネータ側の例」
PC版(Win, VC2008):
xbeemicrolib_coordinator110328

「エンドデバイス側の例」
PC版(Win, VC2008):
xbeemicrolib_enddevice110328

CQ Mary版:
xbeemicrolib_mary110328(CQ Maryについてはこちらをご覧ください:【増刊】超小型ARMマイコン基板 特設ページ

Coron版:
xbeemicrolib_coron110330(Coronについてはこちらをご覧ください:ロボット用マイコンボード「Coron」

X-CTUのインストールとアップデート

X-CTUのインストール

まずDigiインターナショナルのサイトに飛びます.
http://www.digi.com/

メニューから「Support」>「Diagnostics, Utilities, and MIBs」を選択します.

現れた画面の選択肢を一番下までスクロールさせ,「X-CTU」を選んで,Selectボタンをクリックします.

X-CTUの5.1.4.1バージョンを選択してダウンロードし,インストールします.

XBeeのファームウェアのダウンロードと読み込み

次に,XBeeのファームウェア本体をダウンロードして,X-CTUに読み込ませる作業があります.
ウェブからダウンロードするボタンがあるのですが,僕の環境では上手く動かなかったので,手動で認識させる方法をお教えします.

先ほどのX-CTUのダウンロード画面から,「Firmware Updates」を選択します.

出てきたメニューから「XBee / XBee-Pro ZB (ZigBee) Adapters」を選択します.

ここからファームウェアをダウンロードしますが,一番上が新しいと思ったらハマります.冷静に「2×70」バージョンの最新版を選択します.2011年3月22日時点では下記のものです.

ダウンロードしたZipファイルは展開する必要がありません.
これをX-CTUがインストールされているフォルダにコピーします.
僕の環境では,
C:\Program Files (x86)\Digi\XCTU\update
というフォルダに置いておきました.

次にX-CTUを起動します.

まず,Modem Configurationのタブを選択します.

次に,「Download new versions」というボタンをクリックします

ここで「File」をえらび,先ほどのZIPファイルを選択すれば,X-CTUにファームウェアが読み込まれます.

X-CTUの使い方,に進んでください

X-CTUの使い方
X-CTUの使い方について解説しますが,ファームウェアのアップデートが終わっていない方はX-CTUのインストールの項をよく読みなおしてください.

X-CTUを起動する前に,PCにXBeeを接続します.XBeeの接続には,変換基板が必要になりますが,ysugaが動作を確認しているのは以下の2つです.
1.SparkFun XBee Explorer USB
http://www.sparkfun.com/products/8687
http://www.switch-science.com/products/detail.php?product_id=30
http://www.marutsu.co.jp/shohin_71503/

2.マルツパーツ XB基板
http://www.marutsu.co.jp/shohin_104610/

XBee Explorerの方が入手性が高く,使ってるUSB変換チップがFTDI社のものなので信頼がおけます.通信モニタ用のLEDも付いています.ただし,リセットスイッチの取り付けが必要になります.
XB基板は使っているチップがシリコンラボラトリー社のCP210xシリーズでドライバを始めソフトウエアが酷いです.考え直してもらいたいですね.リセットボタンがあるのでこちらの方がこの用途には便利ですが・・・
このサイトでドライバのインストールの仕方を解説しているので,ハマった人がいたらそちらを確認してみてください.
http://ysuga.net/robot/micon/xb_driver_install

XBee Explorer USBのリセットスイッチは,裏面から見てRSTと書かれたピンと,GNDと書かれたピンの間にスイッチを挿入します.

ysugaはフリスクケースに入れて使っています.便利.

さて,XBeeをアダプタに取り付けますが,逆挿しが出来てしまうので,XBeeの刺し込み方向には十分注意してください.
アダプタをPCにUSB接続してからX-CTUを起動します.

自動的にCOMポートを検出してくれます(写真はXB基板を使った例)
ここで通信の設定をします.設定項目は以下のものです
1.ボーレート他,COMポートの設定
2.APIモードか,ATモードか,
3.APIモードの場合,AP=1かAP=2か.
この設定がどれかひとつでも間違っていると通信が失敗します.

XBeeは購入時点では,ファームウェアが古く,
1.ボーレート9600,8ビットノンパリティ,1ストップビット,フロー無し
2.ATモード
3.設定の必要なし
のはずです.上の写真の設定のままで動くはずです.

「Test Query」ボタンを押して,下記のようなダイアログが出てくれば,一応は通信出来ています.このまま進みます.Unable Connectと出た場合は,上記の設定をいじって,何とか「ID=ホニャララ」が出るまで続けます.

次にModem Configurationを選択します.ここで「Modem」を「XB24-ZB」を選択します.

次にFunction Setを選択します.このライブラリはAPI通信に対応しています.
ZIGBEE COORDINATOR APIか,ZIGBEE ENDDEVICE APIに対応しています.ZIGBEE ROUTER APIにも対応予定です.
もちろん,それぞれがコーディネータとエンドデバイス,ルータに対応しています.コーディネータはネットワークに最低1台必要です.
コーディネータを例にとって説明します.

「Show Default」を選択すると,デフォルトの設定値が表示されます.

ここで「Always Update firmware」を選択状態にして,「Write」を押すとファームウェアのアップデートが始まります.
*ファームウェアのアップデートは自己責任でお願いします.
ここで,リセットを求められるかもしれません.リセットしてあげてください.また,ファームウェアアップデート直後の通信が失敗することが多いのですが,大抵はアップデートが済んでいます.

アップデート後はAPIモードでなければ通信出来なくなります.X-CTUの最初の画面で,「Enable API」を選択してからTest Queryをクリックしてみてください.
Modem Configurationの画面で「Read」を行って,ファームウェアが表示されればアップデートは終了です.

この後,普通はPANIDなどの設定が必要ですが,僕のライブラリはライブラリ内でPANIDの設定が可能になっています.
「使い方」に進んでください.

使い方
まずは概要をお読みください.

まず,製品のファームウェアをX-CTUでアップデートする必要があります.
X-CTUによるアップデートの項をお読みください.

展開されるコードは,Visual Studio 2008でプログラムしたものです.
今後はArduino, Arduino FIO, Coron, CQ Mary基板に移植します.

展開されたファイルはコーディネータ側の例,エンドデバイス側の例,ともに同じlibxbeeを使っています.
ご自身で変更されるファイルは
1. xbee_conf.h
(2. uart.c)
3. main.c
だけだと思います.

1.xbee_conf.h

ZIGBEEネットワークに関する設定です.主な設定項目は
1. pan64bitID
PANIDで,ネットワークのIDです.すべてのデバイスで同じ値である必要があります.
2. NI_STRING_LENGTH, networkIdentifierString
ネットワークの識別子文字列です.coordinatorの場合は設定する必要がありません.なぜならコーディネータのアドレスは常にゼロだからです.エンドデバイス向けにデータを送信する場合は,libxbeeでは,この識別子からアドレスを解決します.たとえば以下のように設定します.

const char NI_STRING_LENGTH = 6; // This value should include null character.
const char* networkIdentifierString = “HELLO”;

NI_STRING_LENGTHには最後のヌル文字の文の長さも入れてあげます.

2.uart.c

COM番号を変更してあげてください.

3. main.c

コーディネータとエンドデバイスでは少し異なります.

エンドデバイス側はコーディネータにデータを送信するプログラムになっていますが,コーディネータのアドレスは常にゼロなので解決する必要がありません.
kbhit関数で常にキーボードを監視して,キーコードをXBeeに送信します.

コーディネータ側は「r」キーが押されるとエンドデバイスのアドレス解決を試みます.デフォルトでエンドデバイスの識別子は「HELLO」になっています.
他のキーを押すとデータが送信されます.

受信はmyRxPacketという関数で行います.mainの前の方で,XBee_registerOnRxPacketという関数を使って,myRxPacket関数を受信時のイベントハンドラとして登録してあります.これで受信時には自動的にこの関数が呼ばれます.
引数には送信元の64ビットアドレス,16ビットアドレス(どちらもネットワークアドレスです),データ本体とそのサイズが入っています.
例では単純にprintfするだけです.

エンドデバイス側のmain関数

#include 
#include 

#include "libxbee.h"

/**
 * @brief Event handler code. This function is automatically called when Data Packet is received from XBee module.
 * This function is called in XBee_polling function. The polling function must be called periodically.
 */
void myOnRxPacket(const char* addr64, const char* addr16, const char* dat, const unsigned short size)
{
	printf("Rx(%s)\n", dat);
}

/**
 * @brief Host Record
 * Host record must be resoved by calling XBee_resolve function before using it (except Coordinator record, because it's special.)
 */
XBeeHostRecord coordinator = HOST_RECORD_COORDINATOR;

/**
 * @brief main function.
 */
int main(int argc, char* argv[])
{
	/**
	 * Setup Xbee. Parameters of the network is configured in this function.
	 * Parameters can be changed by developer in "xbee_conf.h" file.
	 */
	XBee_setup();

	/**
	 * This function register the receive event handler.
	 */
	XBee_registerOnRxPacket(myOnRxPacket);

	/* Loop */
	while(1) {
		/* if keyboard is hit... */
		if(_kbhit()) {
			char c = _getch();
			XBee_transmit(&coordinator, &c, 1);
		}
		/**
		 * this function must be called periodically.
		 */
		XBee_polling();

	}
	return 0;
}

コーディネータ側のmain.c

#include 
#include 

#include "libxbee.h"

/**
 * @brief Event handler code. This function is automatically called when Data Packet is received from XBee module.
 * This function is called in XBee_polling function. The polling function must be called periodically.
 */
void myOnRxPacket(const char* addr64, const char* addr16, const char* dat, const unsigned short size)
{
	printf("Rx(%s)\n", dat);
}

/**
 * @brief Host Record
 * Host record must be resoved by calling XBee_resolve function before using it (except Coordinator record, because it's special.)
 */
XBeeHostRecord enddevice = HOST_RECORD_INITIALIZER("HELLO");

/**
 * @brief main function.
 */
int main(int argc, char* argv[])
{
	/**
	 * Setup Xbee. Parameters of the network is configured in this function.
	 * Parameters can be changed by developer in "xbee_conf.h" file.
	 */
	XBee_setup();

	/**
	 * This function register the receive event handler.
	 */
	XBee_registerOnRxPacket(myOnRxPacket);

	/* Loop */
	while(1) {
		/* if keyboard is hit... */
		if(_kbhit()) {
			char c = _getch();
			if(c == 'r') { /* The hit key is 'r', resolve record. */
				XBee_resolve(&enddevice);
				XBee_waitResolveDone();
			} else { /* other, transmit the key code. */
				XBee_transmit(&enddevice, &c, 1);
			}
		}
		/**
		 * this function must be called periodically.
		 */
		XBee_polling();

	}
	return 0;
}

リンク