Bluetooth® Low Energy

概要

本製品にはBluetooth® Low Energyの送受信機能を搭載しています。ここではBluetooth® Low Energy機能をレシピ言語から制御する方法を紹介します。

ビーコン機能の特徴

レシピ言語から扱えるビーコン機能の特徴は以下の通りです。

本機能提供の範囲ではペアリングを伴う制御は非対応です。

ビーコン

ここではビーコンの受信及び送信の機能を説明します。本機能は様々なタイプのビーコンに対応するために、やや難しい設定が必要となりますので、前半部では機能を理解する上での背景部分を解説をし後半部でAPIの利用方法を述べます。

ビーコンのPDU

本機能ではBluetooth® Low Energyの標準フォーマットに準拠した形で発信しているAdvertising Packet を受信しています。Bluetooth® Low EnergyのAdvertising Packet の構成は下図の構成となり、特にビーコンでは特定機器へのペアリングせずに不特定多数への発信を目的としている事から、Protocol Data Unit(PDU)の種類はADV_NONCONN_INDのTypeで規定されるフォーマットが利用されます。
本機能ではこのPDUの中の情報に注目して、対象のビーコンが特定出来るAPIを提供しています。

beacon_pdu

[Advertiser’s Address (AdvA)]

ビーコンで利用されるPDUフォーマットでは、Payload内にあるAdvertiser’s Address(以降 AdvA)は機器固有の番号になり、機器を特定する目的で利用されます。AdvAはBluetooth®機器の製品の外装にラベリングなどにて表記されており、Bluetooth®アドレスと表記されることもあります。

しかし、AdvAはランダムな値の可能性もあるため、必ずしもAvdAが明記されているとは限りません。また、本製品の送信機能ではランダムアドレスは非対応となりますが、受信においてはランダムアドレス機器に対応出来るAPIの設計となっています。

[Advertiser’s Data (AdvData)]

ビーコンには特定のIDを発信することで存在を示す役割の他に、ビーコン自体が持っている情報を一緒に配信することが出来ます。センサーの付いているビーコン(温度や湿度センサーなど)はこの情報をAdvertiser’s Data(以降 AdvData)内のAD Dataに入れて発信を行なっています。
beacon_advdata

Advertising Packet を受信した機器は、AD Dataの該当部分からデータを取得してアプリケーション等で利用する事が出来ます。

※ビーコンのAdvertising Packet内のデータ配列は製品ごとに違うため、ビーコンのマニュアル等を確認願います。


ビーコンの特定

Bluetooth® Low EnergyのAdvertising Packetはビーコン以外でも使われており、スマートフォンのスキャンアプリ等で検出を行うと、多くのBluetooth®機器のAdvertising Packetが検出されます。この中から該当のビーコンのみを抽出するために、本APIでは「フィルタリング機能」と「ビットマスク機能」を備えております。

[フィルタリング機能]

ビーコンは受信側に機器を特定してもらう為の固有値をAdvertising Packetの中に含めています。固有値としてはAdvAの他に、製品固有番号をAdvDataの中に埋め込んでいるものなど様々あります。このため、検出したいビーコンの固有値の場所と数値がわかれば、それに対応したパターン情報を設定し、パターンマッチするパケットのみ通すフィルタを作ることが出来ます。(このフィルタのパターンは50個まで指定することが可能です)
beacon_pattern

[ビットマスク機能]

ビーコンの検出は一つの個体のみを特定したいこともあれば、製品という単位で特定したい場合もあります。特定対象となるビーコンが少数であれば個別のフィルタを準備する事も出来ますが、ビットマスク機能を利用することで1つのフィルタで機種単位でのビーコンを特定する設定が出来ます。
例えば製品固有番号が「会社番号+製品番号+製造番号」の様な組み合わせの場合、「会社番号+製品番号」の部分だけビットマスク機能で抜き出し、抜き出した結果とフィルタのパターン情報をマッチングさせる事が出来ます。
beacon_mask
※ビットマスクは取得したデータとの論理積(AND)を取ります。上図ではFF・・と設定していますが、バイト単位で論理積(AND)を取るためビット単位でのマスク値を指定することが出来ます。


送信と受信のタイミング

ビーコンは発信する側の機器が受信側との同期を取らずに独自のタイミング(周期)で発信します。このため受信側は常に待ち受けをしないと受信し損ねる可能性がありますが、常に受信し続けると機器の電力消費が多くなります。Bluetooth®では低消費電力制御の観点から受信を開始する周期と、受信時間(受信窓幅)を指定する事でこれに対応出来る仕組みがあります。本APIにはこれに対応したパラメータがあり下図の様に受信時間と受信周期を変更することが出来ます。

beacon_rcv

本機器でACアダプタから電源を供給する場合、低消費制御が必要ないため受信周期と受信時間を同じにすることによりビーコンの受信失敗を防ぐ事が出来ます。


ビーコン受信の抑制

ビーコンの発信周期は100msのものや30秒のものなど製品や設定によって様々となります。発信周期が早いビーコンを検出する場合、受信側はその周期ごとに検出イベントを受けることからシステムの負荷が高くなります。本機能ではこれに対応するために一度受信したビーコンを一定期間受信抑制する(受信しても検出イベントを上げない)仕組みを搭載しています。

beacon_restrain

例えば1秒周期で送信するビーコンがあり、抑制期間を30秒に設定した場合、最初の受信時にはイベントが上がりますが、その後同じビーコンを受信したとしても30秒間はイベント発行が停止します。

[受信抑制期間の弊害]

ビーコン受信抑制期間はシステム構築を行う上では必要な機能ですが、前記のビットマスク機能による製品単位の受信フィルタを設定した場合に意図しない弊害が生じる事があります。下図の様にフィルタで同じビーコンとして扱われた場合、抑制期間中は同一製品の検出イベントが上がらない状態になります。

beacon_effect

これを回避するために、フィルタは製品単位として機能するが、受信抑制時に指定の数値部分は別なビーコンとして扱うという、特殊な設定をすることが出来ます。抑制時間はビーコンごとに設定されますので、下図の場合の通り受信後から別々な抑制時間が設定されます。

beacon_effect2

※上記の特殊マスクは、後述のBLE_FilterDataSetSensor()のAPIのf2_ad_data_free_mask引数が該当します。


ビーコンの受信

本機能のAPIを利用することでAdvertising Packetに対するフィルタ値を指定して特定のビーコンを受信し、内容のデータを取得する事が出来ます。ここではビーコンを受信するためのAPIの扱い方を説明します。

[ビーコンの受信手順]

ビーコンを受信して中のセンサーデータ等の値を取得するには以下の手順です。

  1. ビーコン受信周期などの基本設定を行う。
  2. 受信したビーコンを選別するためのフィルタを設定する。
  3. 該当のビーコンを受信した時の通知イベントを設定する。
  4. 受信したビーコンのAdvertising Channel PDUからデータを取得する。

制御するAPIと動きの全体イメージ図は以下のようになります。

beacon_api


ビーコン受信制御のAPI

ビーコン受信制御に関連するAPIは以下の通りです。

API 内容
1 BLE_SettingDataSet() 送受信機能の基本設定を行う
2 BLE_FilterDataSetSensor() 受信機能のフィルタ設定を行う
3 BLE_StartPolling() ビーコンの受信を開始する
4 BLE_StartOneShot() ビーコンを1回受信する
5 BLE_ScanStop() ビーコンの送信と受信を停止する

BLE_SettingDataSet()

送受信機能の基本設定を行う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送信周期 (2010000[msec])
    rcv_width     : Advertise受信時間(340000[msec])
    rcv_interval  : Advertise受信周期(33600000[msec])
    rcv_rssi_th   : 受信時の信号強度閾値 (-1280[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]となり設定する数値と距離のイメージは以下の通りです。

RSSI

ibeacon_recv, sensor_recv
前記「ビーコン受信の抑制」で説明をした内容で、一回受信したビーコンのイベン通知を一定時間抑制する時間となります。iBeaconとそれ以外のビーコンそれぞれで値を設定できます。(iBeacon以外をここではセンサービーコンと表現することもある為、引数の名前がsensor_recvとなっています。)
本機能のAPIとタスクの動作模式図は以下となります。

iBeacon_rcv

このAPIはビーコンの基本設定として送信と受信の両方を定義をするため、行いたい内容によって利用する引数が限定されます。

引数 送信設定
(Long Range含む)
受信設定
(ビーコン、
Long Range)
受信設定
(iBeacon)
send_interval
recv_width
recv_interval
recv_rssi_th
ibeacon_recv
sensor_recv

※「☓」項目は引数への設定が不要です。(0を設定してください)
※「ビーコンの送信」「Long Rangeビーコンの送信」「ビーコンの受信」「LongeRangeビーコンの受信」を同時に利用することはできません。


BLE_FilterDataSetSensor ()

ビーコンを検出するためのフィルタとビットマスクを指定する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            : 任意のビーコン設定番号 <049iBeaconの設定と共有>
   beacon_type          : ビーコンの設定Type25
   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のオフセット指定 <029> 
   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

設定する引数との対応表は以下の通り

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
「受信抑制期間の弊害」の項で説明をした「特殊マスク情報」の設定になります。


BLE_StartPolling()

ビーコンの受信を開始するAPIです。

BLE_StartPolling(int32 timeout, uint8 sync, int64 filter_id, uint8 event_id)
    timeout : API実行時のタイムアウト値 ([msec]で指定)
    sync    : API実行方法 (EAPI_SYNC_RESULT固定)
    filter_id   :  フィルタ番号 (049, センサービーコンと共有)
    event_id    :  ビーコンの受信をした場合に発行するイベント番号

filter_id
前記で設定したフィルタのIDを指定することで、そのフィルタでのビーコンの受信を開始します。フィルタは50個設定出来ますので、設定した50個のビーコンを受信しようとした場合は、ここのIDを変更して50回このAPIをコールする動きとなります。

event_id
フィルタに該当したビーコンが受信した場合に、(event_id)で指定したイベントが発行される動きとなります。イベントが発行されるとこのAPIを実行したアプリケーションにイベントが通知されます。


BLE_StartOneShot()

ビーコンの受信を1回行うAPIです。

BLE_StartOneShot(int32 timeout, uint8 sync, int64 filter_id, uint8 event_id)
    timeout : API実行時のタイムアウト値 ([msec]で指定)
    sync    : API実行方法 (EAPI_SYNC_RESULT固定)
    filter_id   :  フィルタ番号 (049, センサービーコンと共有)
    event_id    :  ビーコンの受信をした場合に発行するイベント番号

利用方法はBLE_StartPolling()と同じですが、このAPIでは該当のビーコンが1回受信されたらその時点でスキャンを停止します。


BLE_ScanStop ()

ビーコンの受信と送信を停止する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バッファの番号が通知されるため、その番号を利用してバッファからデータを取得します。

Beacon_fixedbuf

受信イベント引数 説明
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の部分のパケットフォーマットになります。

Beacon_packet

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

iBeaconの特徴

iBeaconはBluetooth® Low Energyの標準フォーマットに準拠した形で、Advertising Packet PDU内のAdvData内のフォーマットをApple社が規定したものとなります。AdvData内のフォーマットをiBeacon frameと呼び、機器を特定するUUIDやデータなどの格納をするMajor, Minorなどのエリアが定義されています。

beacon_format

※iBeaconもAD Structureの構造に則っているため、前記までのビーコン受信のAPIでも受信は出来ますが、iBeacon対応の製品も多く出ていることからiBeaconに特化したAPIを提供しています。


iBeaconの受信

本機能のAPIを利用することでiBeaconのUUID/Major/Minorの値を指定して特定のiBeaconの受信をすることが出来ます。ここではiBeaconの受信するためのAPIの扱い方を紹介します。

[iBeaconの受信手順]

iBeaconを受信してMajorやMinorの値を取得するには以下の手順が必要です。

  1. ビーコン受信周期などの基本設定を行う。
  2. 受信したビーコンを選別するためのフィルタを設定する。
  3. 受信した時の通知イベントを設定し受信開始する。
  4. 受信したiBeacon frameからデータを取得する。

制御するAPIと動きの全体模式図は以下のようになります。

iBeacon_front


iBeacon受信制御のAPI

iBeacon受信制御に関連するAPIは以下の通りです。

API 内容
1 BLE_SettingDataSet() 送受信機能の基本設定を行う
2 BLE_FilterDataSetBeacon() 受信機能のフィルタ設定を行う
3 BLE_StartPolling() ビーコンの受信を開始する
4 BLE_ScanStop() ビーコンの送信と受信を停止する

上記1,2,4のAPIは前記「ビーコンの受信」と同様の為、説明を割愛します。


BLE_FilterDataSetBeacon()

受信機能のフィルタ設定を行う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 : フィルタ番号 (049, センサービーコンと共有)
    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のフィルタ設定には、マスク設定[uuid_mask]とフィルタ設定[uuid_filter]の2つの設定値で該当のUUIDを持つビーコンを限定します。フィルタは受信したUUIDを[uuid_mask]と論理和(AND)を取り、結果を[uuid_filter]と比較する仕組みとなります。

iBeacon_filter

[Major/Minorのフィルタ設定]

Major/Minorにも、UUIDのフィルタと同じ論理でフィルタを設定することが出来ます。またUUIDを検出対象とせずに、Major/Minorだけを検出対象とすることも出来ます。この場合は[uuid_mask]と[uuid_filter]に[0000...]と全て0を入れることで、UUIDフィルタを無効にすることが出来ます。


受信したビーコンデータの取出し

受信したビーコンデータの内容はFixedバッファと呼ばれるバッファに格納されています。受信イベントの引数にはこのFixedバッファの番号が通知されるため、その番号を利用してバッファからデータを取得します。

iBeacon_fixedbuf

受信イベント引数 説明
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);

取り出されたデータは下図のパケットフォーマットになります。

iBeacon_packet

[UUIDの取出し]

受信したパケットはuint8の配列へ変数として扱えます。このため取出したデータをreceived_data[]という配列に入れた際には、UUIDはreceived_data[15]~received_data[30]として順列に取得が出来ます。

[Major/Minorの取出し]

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共通となります。

Beacon_tx_packt
LongRange_tx_packt

※ビーコン送信ではAdvAは機器内に入っている値を自動的に付与します。

[ビーコンの送信手順]

ビーコンを送信するには以下の手順が必要です。

  1. ビーコン送信周期の基本設定を行う。
  2. 送信するAdvDataのデータ列を準備する。
  3. ビーコン送信APIにAdvDataを指定して送信開始する。

制御するAPIと動きの全体模式図は以下のようになります。
Beacon_tx

[Advertiser’s Address(AdvA)の確認方法]

本機器のAdvAは不揮発メモリーに書き込まれて工場出荷しています。このためBluetooth®の送信時にはこのアドレスが自動的に付与されます。
AdvAをプログラム中から読み出すには以下の様にrcplib_NV_Read()を用います。

    uint8 AdvA[6];
    //AdvAを読出します。
    rcplib_NV_Read(NV_RO_BLE_MAC, 0, AdvA);
[iBeaconフォーマットの作成例]

iBeacon送信をする内容はiBeaconのフォーマットに合わせてuint8配列にAdvDataの内容をそのまま設定します。Bluetooth®SIGにて規定しているフォーマットはリトルエンディアンですが、iBeaconのUUID, Major, Minorはビッグエンディアンで記載しますのでご注意ください。

Beacon_tx_format


ビーコン送信制御のAPI

ビーコン送信制御に関連するAPIは以下の通りです。

API 内容
1 BLE_SettingDataSet() 送受信機能の基本設定を行う
2 BLE_StartPDUSending() ビーコンの送信を開始する

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配列のデータ (最大31byteLong Range送信時は最大244Byte)
    size        :  配列のデータサイズ (最大31byteRange送信時は最大244Byte)
    long_range  : ビーコンの送信かLonRange送信の設定 (0:ビーコンの送信, 1:Long Range送信)

LongRange

本機器ではBluetooth® 5.1 LE Coded PHY (Long Range)の送受信に対応しています。

Long Range機能の特徴

Long Range機能の特徴は以下の通りです。

※Long Rangeの通信は、通信相手もLong Rangeに対応している必要があります。

[Long Range機能で扱うPDU]

Long Range機能では下図のAdvAとAdvDataの値を扱います。
LongRangePaket

※Bluetooth®5.0の規格では、Payloadが255まで利用出来ますが、本機能は250byteまでの対応となっています。それ以上は扱えません。


Long Range受信

[Long Rangeの受信手順]

Long Rangeを受信するには以下の手順が必要です。

  1. 受信周期などの基本設定を行う。
  2. 受信したPaketを選別するためのフィルタを設定する。
  3. 受信した時の通知イベントを設定し受信開始する。
  4. 受信したPaketからデータを取得する。

制御するAPIと動きの全体模式図は以下のようになります。

LongRangeAPI


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は前記「ビーコンの受信」と同様の為、説明を割愛します。


BLE_FilterDataSetLongRange()

意図したLong Rangeを検出する為のフィルタ設定をするAPIです。

BLE_FilterDataSetLongRange(int32 timeout, uint8 sync, int64 filter_id,
uint8 filter[], uint8 mask[])
   timeout   タイムアウト時間[msec]
   sync      同期方式のみEAPI_SYNC_RESULT
   filter_id 受信データに対するフィルタ設定 (01を利用可)
   filter   受信データに対するフィルタ設定
       (256Byte配列でbit毎に指定244Byteまで利用可能利用しない範囲は0を代入)
   mask     受信データに対するマスク設定
      (256Byte配列でフィルタ対象とする箇所をbit毎に指定244Byteまで利用可能利用しない範囲は0を代入)

filter_id
前記ビーコンとは別のIDとなり、0,1の2つまでフィルタを持つことが出来ます。

filter, mask
前記ビーコンと同じ形式のフィルタとビットマスクの設定を行います。Long Rangeでは0~244byteまでのAdvDataの内容に対してのフィルタとなります。(注:AdvAは含まれません)
LongRange_packet


BLE_StartPollingLongRange()

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バッファの番号が通知されるため、その番号を利用してバッファからデータを取得します。

iBeacon_fixedbuf

受信イベント引数 説明
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から配列に格納されます。

LongRange_packet


Long Rangeの送信

Long Rangeの送信は、前記ビーコンの送信と同じAPIを使用します。
「ビーコンの送信」の項を参照ください。


サンプルコードの解説

「0301_iBeaconの受信確認」

本サンプルコードでは、一つのiBeaconを受信して、受信したパケットからMajor/Minorの値をデバッグログに出力します。

「0302_iBeaconフォーマットの送信開始⇔停止」

本サンプルコードでは、ボタン押下をするとiBeaconフォーマットのパケットの発信を開始します。

「0303_iBeaconと温湿度センサBeaconの受信開始⇔停止」

本サンプルコードでは、iBeaconと温湿度センサービーコンの受信を行い、iBeaconのMajor/Minorと温湿度センサーの温度/湿度をログに出力します。

「0304_LongRangeの送信開始⇔停止」

本サンプルコードでは、ボタン押下をするとLong Rangeパケットの発信を開始します。

「0305_LongRangeの受信開始⇔停止」

本サンプルコードでは、Long Rangeパケットの受信を行い受信内容をログに出力します。

関連情報等

各サンプルコードについて動作確認を行っておりますが、全ての環境において動作を保証するものではありません。正しく動作することを確認の上でご利用ください。

対応機種:KC4-C-100A/KC4-C-101A