XBee(無線通信)の実験パート4
(APIモード時のフレームデータフォーマットを解析します)

〔マイコンのトップに戻る〕
〔パート1〕 〔パート2〕 〔パート3〕   〔パート5〕 〔パート6〕 〔XBee3〕


前回(パート3)では、子機にスイッチ等を取り付けデジタル・アナログ入力のデータを親機に送って
みました、XBee基本(基礎)の話とX-CTU基本操作の話はパート1を参照下さい。

尚、ここでの記述は秋月電子のXBee ZBモジュール(シリーズ2)PCBアンテナタイプでの内容となります

PS. *3)
2018/1月 現在、XBee S2モジュールは製造中止です、後継機は"S2C"です
こちらの製品です、ここのMyHPは旧記事ですがぁS2Cでも少し追記して置きます。

PS. *4)
2019/7月 現在、更に低消費電力/小型化したXBee3モジュールが販売されているようです。
"XBee3"でも少し追記して置きます。

XBeeを利用して単純に文字等のデータを送受信するだけなら、透過モード(ATコマンド)で簡単に使用
出来ますが、XBeeの機能を利用してもう少し複雑な送受信を行うとすると、
どうもAPIモード(Application Programming Interface)は避けて通れない様ですね。

APIモードは、USARTのシリアル通信での送受信するデータを、APIフレームデータとして独自の
フレームフォーマットを形成して親機−子機間・子機−子機間でのデータ送受信を行うものです。

APIモードイメージ図
APIモードイメージ図

次回以降にXBeeとマイコンやパソコンで接続する為にはこのAPIフレームデータがどんな構造に
なっているのか、また、どんな種類のタイプが有るのかを調べないとダメです。
なので今回のこのページではAPIフレームデータの中でも私が使用するであろう基本のフレームタイプ
のみ記述します。

その他のAPIフレームデータについては、こちらのユーザーガイド(S2/S2B)を参照下さい。 *2)
"S2C"モジュールのユーザーガイドはこちらです。 *3)
"XBee"モジュールのユーザーガイドはこちらです。 *4)

APIフレームデータ(APIパケット)の構造

下図がAPIフレームデータ(APIパケット)の構造で、先頭が0x7Eで始まりチェックサムで終了します。

APIデータフォーマット

チェックサムの計算

チェックサムは上図のフレームデータ赤枠内のみ計算対象とします。
例) 0x7E 0x00 0x05 0x08 0x01 0x4E 0x4A 0xFF 5F
   [ 0xFF - ((0x08 + 0x01 + 0x4E + 0x4A + 0xFF) & 0xFF) ] は 5F とこの様に計算します。

”0x7E”

"0x7E"が先頭以外に現れる場合が有ります、そんな時はAPIパケットの先頭を誤認識してしまう可能性
が有ります。

Configuration(SerialInterfacing)画面
XBeeの設定項目で"AP-API Enable"を"2(API enabled escaping)"とした場合
先頭以外に現れた"0x7E"を"0x7D 0x5E"に置換えて送信を
行います、これをエスケープモードと言います。
(だからぁ、"0x7D"を挿入してぇ、"0x7E xor 0x20 ⇒ 0x5E"です)
他に "0x11"も"0x7D 0x31"に変換
    "0x13"も"0x7D 0x33"に変換
    "0x7D"も"0x7D 0x5D"に変換
但し、チェックサムは変換前のコードで計算します。 *2)
"XBee3は、[UART Interfacing]の項目です。

"AP-API Enable"を"1(API enabled)"とした場合、もちろんエスケープ処理をしなくても良いよモード。
でもこのATAP=1で"0x7E"が先頭以外に現れても送受信は正常に行われると言う報告が有りますが、
ならこんなややこしい事をしなくても良いじゃんと思うのですがぁ.....

※ "S2C/XBee"モジュールの場合、"AP-API Enable"の[1]/[2]の設定でAPIモードになり、
  Transparent mode[0]にてATモードと切り替える事になります。 *3)

APIパケットの長さについて

データシートに、"The API transmit frame can include up to 255 bytes of data"と
"An attempt to send an oversized packet (256+ bytes) will result in a Tx Status message with a status code of 0x74."と有るので255バイトまでの長さみたいな感じがします。
(でもぉ、IEEE802.15.4の送信長は127バイトまでとの話も有りますがぁ、分割するのかなぁ?....)


《APIパケットフレームの作成を行うオンラインツール》

APIフレームデータ(APIパケット)を作成する場合に結構便利かもぉ〜な、ツールを紹介して置きます。
Digi International 社のHPで、「Digi API Frame Maker」です。

Digi API Frame Maker 1

上のツールはHPから削除され、X-CTU(ver6.3.4)のツールとして統合されました。 *2)

X-CTUツール(FramesGenerator)1  X-CTUのツールアイコン(左図の赤枠)を
 クリックします、ドロップダウンリストから
 [Frames Generator]を選びましょう。

 下記画面が表示されます。

X-CTUツール(FramesGenerator)2

@ "Protcol:"でXBeeのタイプを選択。
  シリーズ2なら"ZigBee"、シリーズ1なら"802.15.4"を選びましょう。

A "Mode:"でAPI1かAPI2(エスケープモード)を選択します。
  "Configuration"の"Serial Interfacing"セクションの"AP-API Enable"項目に合わせますよ。

B "Frame Type"で作成するAPIパケットのフレームタイプを選びます。
  上図は FrameType "08"での例です。

C 各項目にデータを入れ、[Copy frame]ボタンをクリックすれば、フレームデータがクリップボードに
  コピーされます。
  "Length"は入力しなくてもOKです、"AT Cmd"はそのまま文字列での入力です。
  (無いコマンドや入力エラー時は赤く表示されるので正しく入力しましょう)
  また、"API2"ならエスケープ処理された結果で表示されるので良いかもぉ。 *2)


《子機の設定を行う》

親機は前回までの設定で"ZIGBEE COORDINATOR API"になっていますね、
このままの設定で行きますが、子機をの設定を"ZIGBEE ROUTER API"に変更します。

@ USBインターフェイスボードをUSBケーブルでPCに接続し、X-CTUツールを起動させます。

A パート1のこちらを参照し、X-CTUとXBeeをコネクトして下さい。 *2)

-------------------------------------(S2/S2B)---------------------------------------

Updateボタン  B XBeeを"ZIGBEE ROUTER API"に変更します。(APIモードです) *2)
   Updateのアイコンをクリックします。

C XBeeのファームウェアを書き換えます。 *2)

Update画面
まず、"Function Set"の項目で"ZIGBEE ROUTER API"を選択します。
次に、"Firmware version"の項目で書き込むバージョンを選択します、
一番上が新しいのでそれを選びましょう。
後は、[Update]ボタンをクリックしてのファームウェアを書き込みます。

(S2/S2BはここまでDへ進む)
-----------------------------------------------------------------------------------

-----------------------------(S2C/XBee3はここから)------------------------------- *3)

B "Function Set"の項目が"ZIGBEE TH Reg"になっていますが、これは切替えてもこのままです。
  (XBee3は項目が"Digi XBee3 Zigbee 3.0 TH"です)
  "S2C/XBee3"モジュールのデフォルトも”ルータ AT”ですので”ルータ API”に切替えます。

  ※ "S2C/XBee3"モジュールは一つのファームウェア内にルータ/コーディネータ/エンドデバイスの
    全てが書込まれているのでファームウェアの書換えは必要なく設定を切替えるだけで動作します。

C コンフィギュレーションの設定を”ルータ API”に切替えます。

ルータ切替え画面1
[Sleep Modes]の項目に有る、"SM"の設定が"No Sleep(Router)[0]"に
なっている事を確認します。

ルータ切替え画面2
[Serial Interfacing]の項目に有る、"AP"の設定を"API enabled[1]"に設定を行い、
項目右横の[Write]丸ボタンをクリックして設定をXBeeに書き込んで下さい。
"XBee3は、[UART Interfacing]の項目で、"API Mode Without Escapes[1]"の設定名です。
(因みに、[1-2]以外の設定になっていれば"AT"モードとなります)

ルータ切替え画面3
[Networking]の項目に有る、"CE"の設定が"Disabled[0]"に
なっている事を確認します。(”ルータ”モードです)
"XBee3は、"Join Network[0]"の設定名です。

-----------------------------------------------------------------------------------

D その他の設定は前の設定をそのまま引き継いでいると思います。
  "D1-AD1/DIO1Configuration"は "3-DIGITAL INPUT"になっていますよね?
  "D2-AD2/DIO2 Configuration"は "2-ADC"になっていますよね?
  なっていない場合は設定を変更して下さい。
  (D1/AD2を利用しないなら設定はしなくてもOKです)

E API MODEを設定します。 *2)
  "S2C/XBee3"モジュールの場合は上記Cにて設定を行っていますよね。 *3)

Configuration(SerialInterfacing)画面
今回はAP-API Enable"を"1"で実験します、エスケープモード
だとちょっとぉメンドクサイのでぇ。
"XBee3は、[UART Interfacing]の項目です。

F 尚、PAN ID(ID)は"777"で、親機のアドレスの設定(DH/DL)は勿論行っていますよね。


《子機のリモート設定操作》

子機をAPIモードにすると親機からリモートで子機の設定を行う事が出来ます、
APIフレームデータ(APIパケット)からでも良いのですがプログラミングしないとダメなので
ここではX-CTUのリモート機能を使ってみましょう。

実験回路は前回の回路を使用します。(抵抗やスイッチは配線しなくてもOK)
@ 親機の乗ったXBee USBインターフェースボードをUSBケーブルでパソコンに接続します。
  (親機から先に電源を投入して下さい)

A 子機の乗ったXBee用2.54mmピッチ変換基板に外部電源5Vを接続します。

B X-CTUを起動させ、パート1のこちらを参照し、X-CTUとXBeeをコネクトして下さい。 *2)
  ("Function Set"の項目が"ZIGBEE COORDINATOR API"と親機なのを確認しましょう)
  (S2C/XBee3は[Networking]の項目"CE"の設定が[1]、[Serial Interfacing]の項目"AP"の設定が[1]と
  なっている事で確認しましょう) *3)

C XBeeの通信網を表示させます。 *2)

図の@のタブをクリックして[Network Working Mode]にします。
下図が表示されるので図のAをクリックし通信網をスキャーンします。
(スキャーン開始したらアイコンはストップボタンになります)
Network操作画面
この様に親機にぶら下がっている子機が表示されます。
Configurationを行いたい子機(B)をダブルクリックします。

D 下図の様に子機のモジュールリストが追加されるので、Configurationの設定が出来ますね。 *2)

Net操作画面


《APIフレームデータ(APIパケット)の送信》  *2)

X-CTUから親機や子機に、APIフレームデータ(APIパケット)を送信する方法を書いて置きます。

@ [Consoles Working Mode]画面を表示させます。

図の@のタブをクリックして[Consoles Working Mode]にします。
下図が表示されるので図のAをクリックし回線をオープンします。
(オープンしたらアイコンはクローズボタンになります)
APIパケット送信画面1
上図のBの[Add new frame to the list]ボタンをクリックします。

A 下図の"Create frame using 'Frames Generator' tool"の文字をクリックします。

APIパケット送信画面2

B APIフレームデータの作成を行います。

APIパケット送信画面3
APIフレームデータの作成を行ったら、[OK]ボタンをクリックします。
フレームタイプは"08"のATコマンド("SL":自アドレスのLOWbyteを得る)発行での例です、
なので親へのパケット送信ですが、子機へのフレームデータなら親機から子機に送信されます。

APIパケット送信画面4
[Add frame]ボタンをクリックします。

C APIフレームデータの送信を行います。

APIパケット送信画面5
"frame_0"を選択し、[Send selected frame]ボタンをクリックします。
「Frames log」に送受信結果が表示されます。

以下の記事では旧X-CTUでの図による説明です、ごめんなさい。m(_ _)m

《APIモードでの通信試験》

下図の様なイメージで実験を行います、X-CTUからAPIフレームデータ(APIパケット)を送信する分けですよ。
尚、X-CTU2側の子機は”USBシリアル変換モジュール”で接続しています。(下右写真)
なのでぇ、X-CTUは親機側と子機側の2個を立ち上げて置く事になりますよ。

実験イメージ図 実験風景1

リモートATコマンド要求(フレームタイプ"17")

子機に対してリモートでATコマンドを発行するAPIパケットです。

※ ATコマンドの詳細はこちらです。

ここでは[ATIS]のコマンドを発行し、子機からはフレームタイプ"97"のAPIパケットを受信しています。
(ATISコマンドはI/O端子をスキャンしてそのON/OFF値やアナログ値情報を返すコマンドです)

X-CTU画面407
赤文字データが子機から返された内容です。

フレームタイプ"17"(親機→子機)
オフセット データ 説明
0 7E 開始コード
1 000F フレームデータの長さ (15byte)
3 17 フ レームタイプ
4 01 フ レームID 
(返信用のデータみたいだが、とりあえず01)
5 0013A200409821A5 送 信先の64ビットアドレスを設定
13 FFFE 送 信先の16ビットアドレスを設定
(アドレスが不明な場合はFFFEとしておく)
(設定するとデータは早く届くらしい)
15 00 リ モートコマンドの送信オプション
(利用しない場合は00)
16 4953 AT コマンド ("I" "S") (ATの文字はいらない)
18 FB チェックサム
このAPIパケットの送信例は、ATコマンドにパラメータがない場合のフレームデータです。

フレームタイプ"97"(子機→親機)
オフセット データ 説明
0 7E 開始コード
1 0017 フレームデータの長さ (23byte)
3 97 フ レームタイプ
4 01 フ レームID 
5 0013A200409821A5 送 信元の64ビットアドレスを設定
13 980F 送 信元の16ビットアドレスを設定
15 4953 AT コマンド ("I" "S")
17 00 コ マンドの実行結果
00=正常
01=エラー
02=無効なコマンドです
03=無効なパラメータです
04=リモートコマンド送信に失敗しました
18 0100020400020207 コマン ドデータ
01
0002   デジタルI/Oのマスクパターン
04       ADCのマスクパターン
0002 デジタルI/Oの入力情報データ
0207 AD2から読み込まれた電圧値データ
(詳しくは前頁のパート3パート1を参照下さい)
26 BF チェックサム


こんどは[ATD1]のコマンドを発行して子機に接続のLEDを点灯させて見ます。
子機の19番端子(DIO1)にLEDの足が長い方を配線し、反対側はGNDに配線して置きましょう。
(子機設定は、"D1-AD1/DIO1Configuration"は "3-DIGITAL INPUT"になっていますよね?)

APIパケットのフレームタイプ"17"で[ATD1=5]のコマンドを発行すると、 子機からはフレームタイプ"97"のAPIパケットで応答します、その後のフレームタイプ"92"のAPIパケットは "IC-Digital IO Change Detection"を"2"にしているのでDIO1端子の出力が変わりデータを送って来ています。

X-CTU画面408


フレームタイプ"17"(親機→子機)
オフセット データ 説明
0 7E 開始コード
1 0010 フレームデータの長さ (16byte)
3 17 フ レームタイプ
4 01 フ レームID 
(返信用のデータみたいだが、とりあえず01)
5 0013A200409821A5 送 信先の64ビットアドレスを設定
13 FFFE 送 信先の16ビットアドレスを設定
(アドレスが不明な場合はFFFEとしておく)
15 02 リ モートコマンドの送信オプション
(02=コマンドの指示をすぐに有効にする)
ここで有効にしない場合は、ATACコマンドで有効にします。
16 4431 AT コマンド ("D" "1")
18 05 AT コマンド(ATD1)のパラメータ
(05=I/O出力をHIGH  04=I/O出力をLOW)
19 1B チェックサム
このAPIパケットの送信例は、ATコマンドにパラメータが有る場合のフレームデータです。

フレームタイプ"97"(子機→親機)
オフセット データ 説明
0 7E 開始コード
1 000F フレームデータの長さ (15byte)
3 97 フ レームタイプ
4 01 フ レームID 
5 0013A200409821A5 送 信元の64ビットアドレスを設定
13 980F 送 信元の16ビットアドレスを設定
15 4431 AT コマンド ("D" "1")
17 00 コ マンドの実行結果
(00が正常 その他の数値はエラー上記参照)
18 BF チェックサム

フレームタイプ"92"(子機→親機)
このAPIパケットは前頁のパート3を参照下さい。


ATコマンド要求(フレームタイプ"08/09")

リモートではなく自分自身と繋がっているXBeeに対してATコマンドを発行する場合に使用します。

X-CTU画面414
APIパケットのフレームタイプ"08"で[ATSL]のコマンドを発行すると、
XBeeからはフレームタイプ "88" のAPIパケットで応答します。
(ATSLコマンドは自分のアドレスの下位4バイトが返されます)

フレームタイプ"08"(X-CTU→XBee)
オフセット データ 説明
0 7E 開始コード
1 0004 フレームデータの長さ (15byte)
3 08 フ レームタイプ
4 01 フ レームID 
(返信用のデータみたいだが、とりあえず01)
5 534C AT コマンド ("S" "L") (ATの文字はいらない)
7 57 チェックサム
このAPIパケットの送信例は、ATコマンドにパラメータがない場合のフレームデータ例です。
パラメータ値が有る場合は、ATコマンドの後(8バイト目以降)にセットします。

APIパケットのフレームタイプ"09"も同じような使い方ですが、
APIパケット"09"で指示したパラメータ値はATACコマンドを発行するまでは変更されません。
"08"で指示したパラメータ値は直ぐ更新されます。 *1)

フレームタイプ"88"(X-CTUの受信したパケット)
オフセット データ 説明
0 7E 開始コード
1 0009 フレームデータの長さ (15byte)
3 88 フ レームタイプ
4 01 フ レームID
5 534C AT コマンド ("S" "L") 
7 00 コマンドの実行結果
00=正常
01=エラー
02=無効なコマンドです
03=無効なパラメータです
04=Tx送信に失敗しました
8 409C90AB コマンドのデータ
(アドレスの下位4バイトが返されました)
12 C0 チェックサム


送信要求APIフレーム(フレームタイプ"10")

相手に対して文字や数値等のデータを送信するAPIパケットです。

通信イメージ図

フレームタイプ"10"のAPIパケットで文字列データ"TEST"を送信しています、
上図はその通信のイメージ図です。

X-CTU画面409
(親機側 X-CTU1 の画面)
フレームタイプ"10"のAPIパケットが送信され、
その送信結果をフレームタイプ"8B"のAPIパケットで返されます。

X-CTU画面410
(子機側 X-CTU2 の画面)
送られてきたデータはフレームタイプ"90"のAPIパケットで受信します。

フレームタイプ"10"(親機→子機)
オフセット データ 説明
0 7E 開始コード
1 0012 フレームデータの長さ (18byte)
3 10 フ レームタイプ
4 01 フ レームID 
(00にするとAPIパケット"8B"が送信されない)
5 0013A200409821A5 送 信先の64ビットアドレスを設定
13 FFFE 送 信先の16ビットアドレスを設定
(アドレスが不明な場合はFFFEとしておく)
15 00 ブ ロードキャスト送信の最大ホップ数を設定??
16 00 送 信オプション
17 54455354 送信す るデータ("TEST")
21 5E チェックサム

フレームタイプ"90"(X-CTU2の受信したパケット)
オフセット データ 説明
0 7E 開始コード
1 0010 フレームデータの長さ (16byte)
3 90 フ レームタイプ
4 0013A200409C90AB 送 信元の64ビットアドレスを設定
12 0000 送 信元の16ビットアドレスを設定
14 01 受 信したパケットの情報
01=内容を認めたパケット(通常)
02=ブロードキャストされたパケット
20=
暗号化されたパケット
40=エンドデバイスから送信さ れたパケット
15 54455354 受信し たデータ("TEST")
19 62 チェックサム

フレームタイプ"8B"(X-CTU1の受信したパケット)
オフセット データ 説明
0 7E 開始コード
1 0007 フレームデータの長さ (7byte)
3 8B フ レームタイプ
4 01 フ レームID
5 980F 送 信元の16ビットアドレスを設定
(レスポンスACKを返したXbeeの16ビットアドレス)
7 00 送 信を何回リトライしたかの個数
8 00 送信の状況
00=正常
01=MAC ACK 失敗
02=CCA 失敗
15=指定した送信先アドレスが不正
21=ネットワークでACKが失敗
22=ネットワークに参加していない
23=自分宛のアドレスを指定した
24=指定のアドレスが見当たらない
25=ルートが見つからない
26=ブロードキャスト失敗
2B=無効なバインディングテーブルインデックス
2C=空きバッファのリソースエラー欠如、タイマなど
2D=APS通信をブロードキャストで試してみた
2E=APS通信をユニキャストで試してみたが、EE=0
32=空きバッファのリソースエラー欠如、タイマなど
74=データ・ペイロードが長すぎる
75=要求されていない間接メッセージ
9 00 ディスカバリーの状況??
00=ディスカバリーのオーバヘッドはなかった
01=アドレスディスカバリー
02=ルートディスカバリー
03=アドレスとルートディスカバリー
40=拡張タイムアウトディスカバリー
10 CC チェックサム
もし子機がエンドデバイスの場合は、子機が起動している時(スリープ状態でない時)にデータを受信
します、なので、フレームタイプ"10"のAPIパケットをこの時受信しACKを返すので、この時点で"8B"の
返信が有ります。
と言う事は、親が"10"を送信しても"8B"を受けるまでは時間がかかる事になります。 *1)


今度は子機側から送信をして見ます。

X-CTU画面411
(子機側 X-CTU2 の画面)
フレームタイプ"10"のAPIパケット内のフレームIDを"00"にして
いるのでフレームタイプ"8B"のAPIパケットは返されていません。
又、送信先アドレスを"0000000000000000"にしています、コーディネータに送る場合はこれでもOK

X-CTU画面412
(親機側 X-CTU1 の画面)
フレームタイプ"90"のAPIパケットで受信されています。


モデムステータス(フレームタイプ"8A")

このAPIパケットはXBeeがリセットした時やネットワークに参加した時などの状況が変化した時に
XBeeから自動的に送信されます。
なのでぇ、プログラミングを行う際はこれを処理するようなコードを書いた方が良いでしょう。

X-CTU画面413
親機のリセットボタンを押して見た、ステータス"00"と"06"の2個が送られて来ています。

フレームタイプ"8A"(X-CTU1の受信したパケット)
オフセット データ 説明
0 7E 開始コード
1 0002 フレームデータの長さ (2byte)
3 8A フ レームタイプ
4 00 ステータス
00:ハードウエアがリセットされた
01:ウオッチドッグタイマーにてリセットされた
02:ネットワークに接続した(ルータ・エンドデバイスのみ)
03:ネットワークから切り離された
06:コーディネータが動作を開始した
07:ネットワークセキュリティキーを更新した
0D:供給する電源電圧が超えた(PRO S2B のみ)
11:ネット接続中にモデム構成が変更された
80+:スタックエラー
5 75 チェックサム

子機(ルータ)の電源が入るとステータス"00"と"02"の2個が送られて来ますが、親機の電源がONでも
OFFでも同じです、他にXBeeがいないのに"ネットワークに接続した"と言われてもねぇ..... *1)

子機(エンドデバイス)の電源が入るとまず"00"が送られてきます、親機の電源が入っていると
数10秒後に"02"が送られてきますが、親機が電源OFFなら送られてきません。  *1)

って事は、"02"が送られてきてからXBeeをアクセスする様にプログラムした方が良いでしょう。  *1)


ノード識別インジケータ(フレームタイプ"95") *1)

このAPIパケットは親機のコミッショニングボタンスイッチを押すと子機に送られてきますが、
どんな機能を持ったパケットかよく解りません。
また、子機でコミッショニングボタンスイッチを押すと親機に送られます。

《その他》

その他のAPIパケットを利用する場合は、その都度実験してこのページに追記して行きたいとは
思うのですがぁ.....

これで次回にAPIモードでマイコンと接続した時の基礎情報は判明しました、後はバリバリと
プログラミング&実験をするだけですがぁ、ちょっとぉ、疲れました。
なのでぇ、とにかくぅ、ちょっと休憩 州´ー`)d□~~
次回(パート5)の記事追加しました。  *1)



"XBee3"モジュールでの見直し(*4) 2019/07/06
"S2C"モジュールでの見直し(*3) 2018/02/05
X-CTU(ver6.3.4)での見直し(*2) 2017/01/20
追記(*1) 2013/05/18


【きむ茶工房ガレージハウス】
Copyright (C) 2006-2019 Shigehiro Kimura All Rights Reserved.