本製品にはBluetooth® Low Energyの送受信機能を搭載しています。ここではBluetooth® Low Energy機能をレシピ言語から制御する方法を紹介します。
レシピ言語から扱えるビーコン機能の特徴は以下の通りです。
本機能提供の範囲ではペアリングを伴う制御は非対応です。
ここではビーコンの受信及び送信の機能を説明します。本機能は様々なタイプのビーコンに対応するために、やや難しい設定が必要となりますので、前半部では機能を理解する上での背景部分を解説をし後半部でAPIの利用方法を述べます。
本機能ではBluetooth® Low Energyの標準フォーマットに準拠した形で発信しているAdvertising Packet を受信しています。Bluetooth® Low EnergyのAdvertising Packet の構成は下図の構成となり、特にビーコンでは特定機器へのペアリングせずに不特定多数への発信を目的としている事から、Protocol Data Unit(PDU)の種類はADV_NONCONN_INDのTypeで規定されるフォーマットが利用されます。
本機能ではこのPDUの中の情報に注目して、対象のビーコンが特定出来るAPIを提供しています。
ビーコンで利用されるPDUフォーマットでは、Payload内にあるAdvertiser’s Address(以降 AdvA)は機器固有の番号になり、機器を特定する目的で利用されます。AdvAはBluetooth®機器の製品の外装にラベリングなどにて表記されており、Bluetooth®アドレスと表記されることもあります。
しかし、AdvAはランダムな値の可能性もあるため、必ずしもAvdAが明記されているとは限りません。また、本製品の送信機能ではランダムアドレスは非対応となりますが、受信においてはランダムアドレス機器に対応出来るAPIの設計となっています。
ビーコンには特定のIDを発信することで存在を示す役割の他に、ビーコン自体が持っている情報を一緒に配信することが出来ます。センサーの付いているビーコン(温度や湿度センサーなど)はこの情報をAdvertiser’s Data(以降 AdvData)内のAD Dataに入れて発信を行なっています。
Advertising Packet を受信した機器は、AD Dataの該当部分からデータを取得してアプリケーション等で利用する事が出来ます。
※ビーコンのAdvertising Packet内のデータ配列は製品ごとに違うため、ビーコンのマニュアル等を確認願います。
Bluetooth® Low EnergyのAdvertising Packetはビーコン以外でも使われており、スマートフォンのスキャンアプリ等で検出を行うと、多くのBluetooth®機器のAdvertising Packetが検出されます。この中から該当のビーコンのみを抽出するために、本APIでは「フィルタリング機能」と「ビットマスク機能」を備えております。
ビーコンは受信側に機器を特定してもらう為の固有値をAdvertising Packetの中に含めています。固有値としてはAdvAの他に、製品固有番号をAdvDataの中に埋め込んでいるものなど様々あります。このため、検出したいビーコンの固有値の場所と数値がわかれば、それに対応したパターン情報を設定し、パターンマッチするパケットのみ通すフィルタを作ることが出来ます。(このフィルタのパターンは50個まで指定することが可能です)
ビーコンの検出は一つの個体のみを特定したいこともあれば、製品という単位で特定したい場合もあります。特定対象となるビーコンが少数であれば個別のフィルタを準備する事も出来ますが、ビットマスク機能を利用することで1つのフィルタで機種単位でのビーコンを特定する設定が出来ます。
例えば製品固有番号が「会社番号+製品番号+製造番号」の様な組み合わせの場合、「会社番号+製品番号」の部分だけビットマスク機能で抜き出し、抜き出した結果とフィルタのパターン情報をマッチングさせる事が出来ます。
※ビットマスクは取得したデータとの論理積(AND)を取ります。上図ではFF・・と設定していますが、バイト単位で論理積(AND)を取るためビット単位でのマスク値を指定することが出来ます。
ビーコンは発信する側の機器が受信側との同期を取らずに独自のタイミング(周期)で発信します。このため受信側は常に待ち受けをしないと受信し損ねる可能性がありますが、常に受信し続けると機器の電力消費が多くなります。Bluetooth®では低消費電力制御の観点から受信を開始する周期と、受信時間(受信窓幅)を指定する事でこれに対応出来る仕組みがあります。本APIにはこれに対応したパラメータがあり下図の様に受信時間と受信周期を変更することが出来ます。
本機器でACアダプタから電源を供給する場合、低消費制御が必要ないため受信周期と受信時間を同じにすることによりビーコンの受信失敗を防ぐ事が出来ます。
ビーコンの発信周期は100msのものや30秒のものなど製品や設定によって様々となります。発信周期が早いビーコンを検出する場合、受信側はその周期ごとに検出イベントを受けることからシステムの負荷が高くなります。本機能ではこれに対応するために一度受信したビーコンを一定期間受信抑制する(受信しても検出イベントを上げない)仕組みを搭載しています。
例えば1秒周期で送信するビーコンがあり、抑制期間を30秒に設定した場合、最初の受信時にはイベントが上がりますが、その後同じビーコンを受信したとしても30秒間はイベント発行が停止します。
ビーコン受信抑制期間はシステム構築を行う上では必要な機能ですが、前記のビットマスク機能による製品単位の受信フィルタを設定した場合に意図しない弊害が生じる事があります。下図の様にフィルタで同じビーコンとして扱われた場合、抑制期間中は同一製品の検出イベントが上がらない状態になります。
これを回避するために、フィルタは製品単位として機能するが、受信抑制時に指定の数値部分は別なビーコンとして扱うという、特殊な設定をすることが出来ます。抑制時間はビーコンごとに設定されますので、下図の場合の通り受信後から別々な抑制時間が設定されます。
※上記の特殊マスクは、後述のBLE_FilterDataSetSensor()のAPIのf2_ad_data_free_mask引数が該当します。
本機能のAPIを利用することでAdvertising Packetに対するフィルタ値を指定して特定のビーコンを受信し、内容のデータを取得する事が出来ます。ここではビーコンを受信するためのAPIの扱い方を説明します。
ビーコンを受信して中のセンサーデータ等の値を取得するには以下の手順です。
制御するAPIと動きの全体イメージ図は以下のようになります。
ビーコン受信制御に関連するAPIは以下の通りです。
API | 内容 | |
---|---|---|
1 | BLE_SettingDataSet() | 送受信機能の基本設定を行う |
2 | BLE_FilterDataSetSensor() | 受信機能のフィルタ設定を行う |
3 | BLE_StartPolling() | ビーコンの受信を開始する |
4 | BLE_StartOneShot() | ビーコンを1回受信する |
5 | BLE_ScanStop() | ビーコンの送信と受信を停止する |
送受信機能の基本設定を行うAPIです。
BLE_SettingDataSet(int32 timeout, uint8 sync, uint32 send_interval, uint32 recv_width, uint32 recv_interval, int8 recv_rssi_th, uint32 ibeacon_recv, uint32 sensor_recv)
timeout : API実行時のタイムアウト値 ([msec]で指定)
sync : API実行方法 (EAPI_SYNC_RESULT固定)
send_interval : Advertise送信周期 (20~10000[msec])
rcv_width : Advertise受信時間(3~40000[msec])
rcv_interval : Advertise受信周期(3~3600000[msec])
rcv_rssi_th : 受信時の信号強度閾値 (-128~0[dBm])
ibeacon_recv : iBeacon毎の通知を抑制する期間 (1[秒]以上,0指定で1回だけ通知を行う)
sensor_recv : センサービーコン毎の通知を抑制する期間 (1[秒]以上,0指定で1回だけ通知を行う)
timeout, sync
このAPIは同期実行(関数がリターンするまでAPI側にコンテキストが移る)の為、APIが応答しない場合用にtimeout値を指定します。30秒など明らかに異常である場合の時間を指定します。syncのEAPI_SYNC_RESULTは同期実行の指定となります。
send_interval
送信時に何秒周期で送信するかを指定します。このAPIは送信/ビーコン受信/iBeacon受信の共用であるため、送信をする時にはここで値を指定しておきます。
rcv_width, rcv_interval
前記「送信と受信のタイミング」で説明をした内容で、受信の幅と周期を指定します。500ms,500ms等同じ数値を設定することにより、100% dutyの受信となり、ビーコンの取り逃しがなくなります。
rcv_rssi_th
信号強度閾値(rcv_rssi_th)は、ここで設定した受信強度より小さな電波は受け取らない設定となります。この設定を調整することで、ある程度近くにあるビーコンのみ受信する等の設定が可能となります。
設定する単位は[dBm]となり設定する数値と距離のイメージは以下の通りです。
ibeacon_recv, sensor_recv
前記「ビーコン受信の抑制」で説明をした内容で、一回受信したビーコンのイベン通知を一定時間抑制する時間となります。iBeaconとそれ以外のビーコンそれぞれで値を設定できます。(iBeacon以外をここではセンサービーコンと表現することもある為、引数の名前がsensor_recvとなっています。)
本機能のAPIとタスクの動作模式図は以下となります。
このAPIはビーコンの基本設定として送信と受信の両方を定義をするため、行いたい内容によって利用する引数が限定されます。
引数 | 送信設定 (Long Range含む) |
受信設定 (ビーコン、 Long Range) |
受信設定 (iBeacon) |
---|---|---|---|
send_interval | 〇 | ☓ | ☓ |
recv_width | ☓ | 〇 | 〇 |
recv_interval | ☓ | 〇 | 〇 |
recv_rssi_th | ☓ | 〇 | 〇 |
ibeacon_recv | ☓ | ☓ | 〇 |
sensor_recv | ☓ | 〇 | ☓ |
※「☓」項目は引数への設定が不要です。(0を設定してください)
※「ビーコンの送信」「Long Rangeビーコンの送信」「ビーコンの受信」「LongeRangeビーコンの受信」を同時に利用することはできません。
ビーコンを検出するためのフィルタとビットマスクを指定するAPIです。
BLE_FilterDataSetSensor(int32 timeout, uint8 sync, int64 filter_id, uint8 beacon_type, uint8 adv_address[], uint8 f1_ad_type[], uint8 f1_ad_data_filter[], uint8 f1_ad_data_mask[], uint8 f2_ad_type[], uint8 f2_ad_data_offset, uint8 f2_ad_data_filter[], uint8 f2_ad_data_mask[], uint8 f2_ad_data_free_mask[])
timeout : APIのタイムアウト値 [msec]
sync : 同期実⾏のみ(EAPI_SYNC_RESULT)
filter_id : 任意のビーコン設定番号 <0〜49、iBeaconの設定と共有>
beacon_type : ビーコンの設定Type2~5
adv_address[] : AdvA <6Byte配列>
f1_ad_type[] : フィルタ設定1のAD Type <1Byte配列またはuint8変数>
f1_ad_data_filter[] :フィルタ設定1のAD Data <32Byte配列>
f1_ad_data_mask[] :フィルタ設定1のAD Dataの場所 <32Byte配列でビットマスク>
f2_ad_type[] :フィルタ設定2のAD Type <1Byte配列またはuint8変数>
f2_ad_data_offset :フィルタ設定2のAD Dataのオフセット指定 <0〜29>
f2_ad_data_filter[] :フィルタ設定2のAD Data <6Byte配列>
f2_ad_data_mask[] :フィルタ設定2のAD Dataの場所。<6Byte配列でビットマスク>
f2_ad_data_free_mask[]:フィルタ設定2のAD Dataに対する部分一致を利用する場合の個々の特定範囲用のビットマスク箇所 <6Byte配列でビットマスク>
filter_id
本機能では50種類までフィルタのパターンを持つことが出来ます。filter_idではこれから設定するフィルタの番号を指定します。後述のビーコン検出を開始するAPIにて、ここで指定したfilter_idを指定します。
beacon_type
フィルタを定義するにあたりAdvertising PDUのどの要素を利用するかを指定します。Typeの番号と利用する要素の関係は以下の通りです。
設定する引数との対応表は以下の通り
beacon_type | Type2 | Type3 | Type4 | Type5 |
---|---|---|---|---|
adv_address | 〇 | ☓ | ☓ | 〇 |
f1_ad_type | 〇 | 〇 | 〇 | 〇 |
f1_ad_data_filter | 〇 | 〇 | 〇 | 〇 |
f1_ad_data_mask | 〇 | 〇 | 〇 | 〇 |
f2_ad_type | ☓ | ☓ | 〇 | 〇 |
f2_ad_data_offset | ☓ | ☓ | 〇 | 〇 |
f2_ad_data_filter | ☓ | ☓ | 〇 | 〇 |
f2_ad_data_mask | ☓ | ☓ | 〇 | 〇 |
f2_ad_data_free_mask | ☓ | ☓ | 〇 | ☓ |
※「☓」項目は利用しない為、引数の設定が不要となります。
※Type2でAdvAだけで検出する場合は、”f1_ad_type”は”0x00”を設定します。
adv_address
フィルタに設定するAdvAの情報を指定します。フィルタとしてAdvAを利用しない場合は空の配列を指定してください。
※ここで指定するAdvAは「リトルエンディアン」で指定をします。Bluetooth®SIGでの定義されているAdvertising Packet PDU内はリトルエンディアンでの定義です。
f1_ad_type
1つ目のAD Structureを特定するためのAD Typeを指定します。
f1_ad_data_filter, f1_ad_data_mask
1つ目のフィルタ情報とビットマスク情報を設定します。
f2_ad_type
2つ目のAD Structureを特定するためのAD Typeを指定します。
f2_ad_data_filter, f2_ad_data_offset, f2_ad_data_mask
2つ目のフィルタ情報とビットマスク情報を設定します。2つ目のフィルタはフィルタ開始のオフセットをかけることが出来るため、より柔軟に設定が出来ます。
f2_ad_data_free_mask
「受信抑制期間の弊害」の項で説明をした「特殊マスク情報」の設定になります。
ビーコンの受信を開始するAPIです。
BLE_StartPolling(int32 timeout, uint8 sync, int64 filter_id, uint8 event_id)
timeout : API実行時のタイムアウト値 ([msec]で指定)
sync : API実行方法 (EAPI_SYNC_RESULT固定)
filter_id : フィルタ番号 (0~49, センサービーコンと共有)
event_id : ビーコンの受信をした場合に発行するイベント番号
filter_id
前記で設定したフィルタのIDを指定することで、そのフィルタでのビーコンの受信を開始します。フィルタは50個設定出来ますので、設定した50個のビーコンを受信しようとした場合は、ここのIDを変更して50回このAPIをコールする動きとなります。
event_id
フィルタに該当したビーコンが受信した場合に、(event_id)で指定したイベントが発行される動きとなります。イベントが発行されるとこのAPIを実行したアプリケーションにイベントが通知されます。
ビーコンの受信を1回行うAPIです。
BLE_StartOneShot(int32 timeout, uint8 sync, int64 filter_id, uint8 event_id)
timeout : API実行時のタイムアウト値 ([msec]で指定)
sync : API実行方法 (EAPI_SYNC_RESULT固定)
filter_id : フィルタ番号 (0~49, センサービーコンと共有)
event_id : ビーコンの受信をした場合に発行するイベント番号
利用方法はBLE_StartPolling()と同じですが、このAPIでは該当のビーコンが1回受信されたらその時点でスキャンを停止します。
ビーコンの受信と送信を停止するAPIとなります。
func BLE_ScanStop(int32 timeout, uint8 sync, uint8 event_id)
timeout : タイムアウト時間[msec]
sync : 同期方式のみ(EAPI_SYNC_RESULT)
event_id : 処理完了後に発行するイベントID ※ビーコンの送信を停止する場合はこの入力値は不要です。
event_idにはBLE_StartPolling()で指定した同一のIDを指定することで、ビーコンの受信を停止することが出来ます。
フィルタに該当したビーコンを受信した場合、ビーコンデータの内容はFixedバッファと呼ばれるバッファに格納されています。受信イベントの引数にはこのFixedバッファの番号が通知されるため、その番号を利用してバッファからデータを取得します。
受信イベント引数 | 型 | 説明 |
---|---|---|
rcplib_TASK_GetArg(0) | int32 | 受信データのあるFixedバッファのIndex番号 |
rcplib_TASK_GetArg(1) | uint8 | 受信データのあるFixedバッファのバッファID |
受信イベント引数のindex番号とバッファIDを用いて、Fixedバッファから取り出すAPIであるrcplib_FIXBUF_Pop()を用いてAdvertising Packetを取出します。
uint8 received_data[37]; // 受信データの格納先
int32 fixed_buff_index; //Fixedバッファindex
uint8 fixed_buff_id; //FixedバッファID
fixed_buff_index = rcplib_TASK_GetArg(0);
fixed_buff_id = rcplib_TASK_GetArg(1);
// FixdバッファからBLE受信データを取得
rcplib_FIXBUF_Pop(fixed_buff_id, fixed_buff_index, received_data);
取り出されるデータは下図ようにAdvertising Channel PDUの部分のパケットフォーマットになります。
uint8配列にAdvAから順にPDUの内容が入っているため、ビーコンの製品マニュアル等を参考に該当のbyte位置からデータを取り出します。
例:温度データがAdvDataの先頭から14byte目
湿度データがAdvDataの先頭から16byte目 の場合
uint8配列はAdvAの先頭からのため、AdvAの6byteを加味する
temperature = (received_data[6+14]*256) + received_data[6+15];
humidity = (received_data[6+16]*256) + received_data[6+17];
上記例は2byteのデータがビッグエンディアンで格納されている場合です。
ビーコンによってエンディアンが違うので確認が必要です。
iBeaconはBluetooth® Low Energyの標準フォーマットに準拠した形で、Advertising Packet PDU内のAdvData内のフォーマットをApple社が規定したものとなります。AdvData内のフォーマットをiBeacon frameと呼び、機器を特定するUUIDやデータなどの格納をするMajor, Minorなどのエリアが定義されています。
※iBeaconもAD Structureの構造に則っているため、前記までのビーコン受信のAPIでも受信は出来ますが、iBeacon対応の製品も多く出ていることからiBeaconに特化したAPIを提供しています。
本機能のAPIを利用することでiBeaconのUUID/Major/Minorの値を指定して特定のiBeaconの受信をすることが出来ます。ここではiBeaconの受信するためのAPIの扱い方を紹介します。
iBeaconを受信してMajorやMinorの値を取得するには以下の手順が必要です。
制御するAPIと動きの全体模式図は以下のようになります。
iBeacon受信制御に関連するAPIは以下の通りです。
API | 内容 | |
---|---|---|
1 | BLE_SettingDataSet() | 送受信機能の基本設定を行う |
2 | BLE_FilterDataSetBeacon() | 受信機能のフィルタ設定を行う |
3 | BLE_StartPolling() | ビーコンの受信を開始する |
4 | BLE_ScanStop() | ビーコンの送信と受信を停止する |
上記1,2,4のAPIは前記「ビーコンの受信」と同様の為、説明を割愛します。
受信機能のフィルタ設定を行うAPIです。
BLE_FilterDataSetBeacon(int32 timeout, uint8 sync, int64 filter_id, uint8 uuid_filter[], uint8 uuid_mask[], uint8 major_filter[], uint8 major_mask[], uint8 minor_filter[], uint8 minor_mask[])
timeout : API実行時のタイムアウト値 ([msec]で指定)
sync : 同期実行⽅法のみ (EAPI_SYNC_RESULT固定)
filter_id : フィルタ番号 (0~49, センサービーコンと共有)
uuid_filter : UUIDに対するフィルタ設定 (16byte配列)
uuid_mask : UUIDに対するマスク設定 (16byte配列で対象箇所をbit指定)
major_filter : Majorに対するフィルタ設定 (2byte配列)
major_mask : Majorに対するマスク設定 (2byte配列で対象箇所をbit指定)
minor_filter : Minorに対するフィルタ設定 (2byte配列)
minor_mask : Minorに対するマスク設定 (2byte配列で対象箇所をbit指定)
送受信の基本設定で電波を受信できる条件に当てはまったビーコンは全て受信出来ることになりますが、受信した全てのビーコンをアプリケーション側で選別しなくて良いようにするために、フィルタを設定して通知するビーコンを限定する事が出来ます。
フィルタ設定にはUUID/Major/Minorそれぞれの値を設定することが出来ます。この設定によりUUIDのみでビーコンを特定する設定や、MajorやMinorも含めて該当のビーコンを更に限定することが出来ます。
※UUID/Major/Minorのフィルタはビッグエンディアンで設定します。
UUIDのフィルタ設定には、マスク設定[uuid_mask]とフィルタ設定[uuid_filter]の2つの設定値で該当のUUIDを持つビーコンを限定します。フィルタは受信したUUIDを[uuid_mask]と論理和(AND)を取り、結果を[uuid_filter]と比較する仕組みとなります。
Major/Minorにも、UUIDのフィルタと同じ論理でフィルタを設定することが出来ます。またUUIDを検出対象とせずに、Major/Minorだけを検出対象とすることも出来ます。この場合は[uuid_mask]と[uuid_filter]に[0000...]と全て0を入れることで、UUIDフィルタを無効にすることが出来ます。
受信したビーコンデータの内容はFixedバッファと呼ばれるバッファに格納されています。受信イベントの引数にはこのFixedバッファの番号が通知されるため、その番号を利用してバッファからデータを取得します。
受信イベント引数 | 型 | 説明 |
---|---|---|
rcplib_TASK_GetArg(0) | int32 | 受信データのあるFixedバッファのIndex番号 |
rcplib_TASK_GetArg(1) | uint8 | 受信データのあるFixedバッファのバッファID |
受信イベント引数のindex番号とバッファIDを用いて、Fixedバッファから取り出すAPIであるrcplib_FIXBUF_Pop()を用いてAdvertising Packetを取出します。
uint8 received_data[37]; // 受信データの格納先
int32 fixed_buff_index; //Fixedバッファindex
uint8 fixed_buff_id; //FixedバッファID
fixed_buff_index = rcplib_TASK_GetArg(0);
fixed_buff_id = rcplib_TASK_GetArg(1);
// FixdバッファからBLE受信データを取得
rcplib_FIXBUF_Pop(fixed_buff_id, fixed_buff_index, received_data);
取り出されたデータは下図のパケットフォーマットになります。
受信したパケットはuint8の配列へ変数として扱えます。このため取出したデータをreceived_data[]という配列に入れた際には、UUIDはreceived_data[15]~received_data[30]として順列に取得が出来ます。
UUIDと同じ様に配列から取り出せますが、Major/Minor共にBigEndianで保存がされている事から、以下の計算式で取り出す事が出来ます。
uint8配列はAdvAの先頭からのため、AdvAの6byteを加味する
major = (received_data[6+25]*256) + received_data[6+26];
minor = (received_data[6+27]*256) + received_data[6+28];
上記例は2byteのデータがビッグエンディアンで格納されている場合です。
ビーコンによってエンディアンが違う可能性があるので確認が必要です。
受信のAPIではビーコンとiBeaconのAPIを分けていましたが、送信に関してはビーコン、iBeacon、Long Range共通となります。
※ビーコン送信ではAdvAは機器内に入っている値を自動的に付与します。
ビーコンを送信するには以下の手順が必要です。
制御するAPIと動きの全体模式図は以下のようになります。
本機器のAdvAは不揮発メモリーに書き込まれて工場出荷しています。このためBluetooth®の送信時にはこのアドレスが自動的に付与されます。
AdvAをプログラム中から読み出すには以下の様にrcplib_NV_Read()を用います。
uint8 AdvA[6];
//AdvAを読出します。
rcplib_NV_Read(NV_RO_BLE_MAC, 0, AdvA);
iBeacon送信をする内容はiBeaconのフォーマットに合わせてuint8配列にAdvDataの内容をそのまま設定します。Bluetooth®SIGにて規定しているフォーマットはリトルエンディアンですが、iBeaconのUUID, Major, Minorはビッグエンディアンで記載しますのでご注意ください。
ビーコン送信制御に関連するAPIは以下の通りです。
API | 内容 | |
---|---|---|
1 | BLE_SettingDataSet() | 送受信機能の基本設定を行う |
2 | BLE_StartPDUSending() | ビーコンの送信を開始する |
ビーコンの送信を開始するAPIです。
BLE_StartPDUSending(int32 timeout, uint8 sync, uint8 send_data[], uint32 size, uint8 long_range)
timeout : API実行時のタイムアウト値 ([msec]で指定)
sync : API実行方法 (EAPI_SYNC_RESULT固定)
send_data : 送信対象とするuint8配列のデータ (最大31byte、Long Range送信時は最大244Byte)
size : 配列のデータサイズ (最大31byte、Range送信時は最大244Byte)
long_range : ビーコンの送信かLonRange送信の設定 (0:ビーコンの送信, 1:Long Range送信)
本機器ではBluetooth® 5.1 LE Coded PHY (Long Range)の送受信に対応しています。
Long Range機能の特徴は以下の通りです。
※Long Rangeの通信は、通信相手もLong Rangeに対応している必要があります。
Long Range機能では下図のAdvAとAdvDataの値を扱います。
※Bluetooth®5.0の規格では、Payloadが255まで利用出来ますが、本機能は250byteまでの対応となっています。それ以上は扱えません。
Long Rangeを受信するには以下の手順が必要です。
制御するAPIと動きの全体模式図は以下のようになります。
Long Range受信制御に関連するAPIは以下の通りです。
API | 内容 | |
---|---|---|
1 | BLE_SettingDataSet() | 送受信機能の基本設定を行う |
2 | BLE_FilterDataSetLongRange() | 受信機能のフィルタ設定を行う |
3 | BLE_StartPollingLongRange() | Long Rangeの受信を開始する |
4 | BLE_StartOneShotLongRange() | Long Rangeを1回受信する |
5 | BLE_ScanStop() | Long Rangeの送信と受信を停止する |
上記1,4のAPIは前記「ビーコンの受信」と同様の為、説明を割愛します。
意図したLong Rangeを検出する為のフィルタ設定をするAPIです。
BLE_FilterDataSetLongRange(int32 timeout, uint8 sync, int64 filter_id,
uint8 filter[], uint8 mask[])
timeout : タイムアウト時間[msec]
sync : 同期方式のみ(EAPI_SYNC_RESULT)
filter_id: 受信データに対するフィルタ設定 (0~1を利用可)
filter :受信データに対するフィルタ設定
(256Byte配列でbit毎に指定、244Byteまで利用可能、利用しない範囲は0を代入)
mask :受信データに対するマスク設定
(256Byte配列でフィルタ対象とする箇所をbit毎に指定、244Byteまで利用可能、利用しない範囲は0を代入)
filter_id
前記ビーコンとは別のIDとなり、0,1の2つまでフィルタを持つことが出来ます。
filter, mask
前記ビーコンと同じ形式のフィルタとビットマスクの設定を行います。Long Rangeでは0~244byteまでのAdvDataの内容に対してのフィルタとなります。(注:AdvAは含まれません)
Long Rangeの受信を開始するAPIです。
BLE_StartPollingLongRange(int32 timeout, uint8 sync, int64 filter_id, uint8 event_id)
timeout : タイムアウト時間[msec]
sync : 同期方式のみ(EAPI_SYNC_RESULT)
filter_id: 受信データに対するフィルタ設定
event_id : LongeRangeを受信したときに発行するイベントID
設定したフィルタと受信時のイベントIDを指定して、Long Rangeの受信を開始します。
Long Rangeの受信はサイズが違うのみで基本的には前記のビーコンと同じになります。
受信したLong RangeデータはFixedバッファと呼ばれるバッファに格納されています。受信イベントの引数にはこのFixedバッファの番号が通知されるため、その番号を利用してバッファからデータを取得します。
受信イベント引数 | 型 | 説明 |
---|---|---|
rcplib_TASK_GetArg(0) | int32 | 受信データのあるFixedバッファのIndex番号 |
rcplib_TASK_GetArg(1) | uint8 | 受信データのあるFixedバッファのバッファID |
受信イベント引数のindex番号とバッファIDを用いて、Fixedバッファから取り出すAPIであるrcplib_FIXBUF_Pop()を用いてPacketを取出します。
uint8 received_data[251]; // 受信データの格納先
int32 fixed_buff_index; //Fixedバッファindex
uint8 fixed_buff_id; //FixedバッファID
fixed_buff_index = rcplib_TASK_GetArg(0);
fixed_buff_id = rcplib_TASK_GetArg(1);
// FixdバッファからBLE受信データを取得
rcplib_FIXBUF_Pop(fixed_buff_id, fixed_buff_index, received_data);
取り出されたデータは下図の様に、AdvAから配列に格納されます。
Long Rangeの送信は、前記ビーコンの送信と同じAPIを使用します。
「ビーコンの送信」の項を参照ください。
本サンプルコードでは、一つのiBeaconを受信して、受信したパケットからMajor/Minorの値をデバッグログに出力します。
本サンプルコードでは、ボタン押下をするとiBeaconフォーマットのパケットの発信を開始します。
本サンプルコードでは、iBeaconと温湿度センサービーコンの受信を行い、iBeaconのMajor/Minorと温湿度センサーの温度/湿度をログに出力します。
本サンプルコードでは、ボタン押下をするとLong Rangeパケットの発信を開始します。
本サンプルコードでは、Long Rangeパケットの受信を行い受信内容をログに出力します。
各サンプルコードについて動作確認を行っておりますが、全ての環境において動作を保証するものではありません。正しく動作することを確認の上でご利用ください。
対応機種:KC4-C-100A/KC4-C-101A