Bluetooth LE アドバタイズBluetooth LE Advertisements

重要な APIImportant APIs

この記事では、ユニバーサル Windows プラットフォーム (UWP) アプリ向けの Bluetooth 低エネルギー (LE) アドバタイズ ビーコンの概要を示します。This article provides an overview of Bluetooth Low Energy (LE) Advertisement beacons for Universal Windows Platform (UWP) apps.

概要Overview

開発者が LE アドバタイズ API を使って実行できる機能には、主に次の 2 つがあります。There are two main functions that a developer can perform using the LE Advertisement APIs:

完全なサンプル コードについては、GitHub の Bluetooth アドバタイズ サンプルをご覧ください。Full sample code is found in the Bluetooth Advertisement Sample on Github

基本セットアップBasic Setup

ユニバーサル Windows プラットフォーム アプリで Bluetooth LE の基本的な機能を使用するには、Package.appxmanifest で Bluetooth の機能を確認する必要があります。To use basic Bluetooth LE functionality in a Universal Windows Platform app, you must check the Bluetooth capability in the Package.appxmanifest.

  1. Package.appxmanifest を開きます。Open Package.appxmanifest
  2. [機能] タブに移動します。Go to the Capabilities tab
  3. 左側の一覧で Bluetooth を見つけ、その横にあるチェック ボックスをオンにします。Find Bluetooth in the list on the left and check the box next to it.

アドバタイズのパブリッシュPublishing Advertisements

Bluetooth LE アドバタイズでは、デバイスから特定のペイロードを常時ビーコンできます。これをアドバタイズと呼びます。Bluetooth LE Advertisements allow your device to constantly beacon out a specific payload, called an advertisement. 近接範囲内にあり、この特定のアドバタイズをリッスンするように設定されたすべての Bluetooth LE 対応デバイスは、このアドバタイズを認識できます。This advertisement can be seen by any nearby Bluetooth LE capable device, if they are set up to listen for this specific advertisment.

注意:ユーザーのプライバシー保護のため、アプリの公開通知の有効期間が関連付けられています。Note: For user privacy, the lifespan of your advertisement is tied to that of your app. BluetoothLEAdvertisementPublisher を作成し、バックグラウンド タスクで Start を呼び出して、バックグラウンドでアドバタイズを発行できます。You can create a BluetoothLEAdvertisementPublisher and call Start in a background task for advertisement in the background. バックグラウンド タスクについて詳しくは、「起動、再開、バックグラウンド タスク」をご覧ください。For more information about background tasks, see Launching, resuming, and background tasks.

基本的なパブリッシュBasic Publishing

アドバタイズにデータを追加するには、さまざまな方法があります。There are many different ways to add data to an Advertisement. この例では、会社固有のアドバタイズを作成する一般的な方法を示します。This example shows a common way to create a company-specific advertisement.

まず、デバイスが特定のアドバタイズをビーコンするかどうかを制御するアドバタイズ パブリッシャーを作成します。First, create the advertisement publisher that controls whether or not the device is beaconing out a specific advertisement.

BluetoothLEAdvertisementPublisher publisher = new BluetoothLEAdvertisementPublisher();

次に、カスタム データ セクションを作成します。Second, create a custom data section. この例では、未割り当ての CompanyId0xFFFE を使うと共に、テキスト Hello World をアドバタイズに追加しています。This example uses an unassigned CompanyId value 0xFFFE and adds the text Hello World to the advertisement.

// Add custom data to the advertisement
var manufacturerData = new BluetoothLEManufacturerData();
manufacturerData.CompanyId = 0xFFFE;

var writer = new DataWriter();
writer.WriteString("Hello World");

// Make sure that the buffer length can fit within an advertisement payload (~20 bytes). 
// Otherwise you will get an exception.
manufacturerData.Data = writer.DetachBuffer();

// Add the manufacturer data to the advertisement publisher:
publisher.Advertisement.ManufacturerData.Add(manufacturerData);

これでパブリッシャーが作成され、セットアップされました。次に Start を呼び出してアドバタイズを開始します。Now that the publisher has been created and setup, you can call Start to begin advertising.

publisher.Start();

アドバタイズのウォッチWatching for Advertisements

基本的なウォッチBasic Watching

次のコードは、Bluetooth LE アドバタイズ ウォッチャーを作成し、コールバックを設定して、すべての LE アドバタイズのウォッチを開始する方法を示しています。The following code demonstrates how to create a Bluetooth LE Advertisement watcher, set a callback, and start watching for all LE advertisements.

BluetoothLEAdvertisementWatcher watcher = new BluetoothLEAdvertisementWatcher();
watcher.Received += OnAdvertisementReceived;
watcher.Start();
private async void OnAdvertisementReceived(BluetoothLEAdvertisementWatcher watcher, BluetoothLEAdvertisementReceivedEventArgs eventArgs)
{
    // Do whatever you want with the advertisement
}

アクティブ スキャンActive Scanning

スキャン応答のアドバタイズを併せて受信するには、ウォッチャーを作成した後、次を設定します。To receive scan response advertisements as well, set the following after creating the watcher. この場合、電力消費量が大きくなり、またバックグラウンド モードでは使用できないことに注意してください。Note that this will cause greater power drain and is not available while in background modes.

watcher.ScanningMode = BluetoothLEScanningMode.Active;

特定のアドバタイズ パターンのウォッチWatching for a Specific Advertisement Pattern

状況によっては、特定のアドバタイズのみをリッスンする必要がある場合があります。Sometimes you want to listen for a specific advertisement. この例では、(0xFFFE として識別される) 作成企業が指定されたペイロードが含まれ、かつ文字列 Hello World が含まれたアドバタイズをリッスンします。In this case, listen for an advertisement containing a payload with a made up company (identified as 0xFFFE) and containing the string Hello World in the advertisement. このコードは「基本的なパブリッシュ」の例に対応して、一方がアドバタイズする Windows マシン、もう片方がウォッチする Windows マシンとなります。This can be paired with the Basic Publishing example to have one Windows machine advertising and another watching. ウォッチャーを開始する前に、必ずこのアドバタイズ フィルターを設定してください。Be sure to set this advertisement filter before you start the watcher!

var manufacturerData = new BluetoothLEManufacturerData();
manufacturerData.CompanyId = 0xFFFE;

// Make sure that the buffer length can fit within an advertisement payload (~20 bytes). 
// Otherwise you will get an exception.
var writer = new DataWriter();
writer.WriteString("Hello World");
manufacturerData.Data = writer.DetachBuffer();

watcher.AdvertisementFilter.Advertisement.ManufacturerData.Add(manufacturerData);

近接範囲内のアドバタイズのウォッチWatching for a Nearby Advertisement

アドバタイズしているデバイスが範囲内に入った場合のみ、ウォッチをトリガーするように設定することもできます。Sometimes you only want to trigger your watcher when the device advertising has come in range. 範囲は独自に定義できますが、値は 0 ~ -128 の間にクリップされます。You can define your own range, just note that values will be clipped to between 0 and -128.

// Set the in-range threshold to -70dBm. This means advertisements with RSSI >= -70dBm 
// will start to be considered "in-range" (callbacks will start in this range).
watcher.SignalStrengthFilter.InRangeThresholdInDBm = -70;

// Set the out-of-range threshold to -75dBm (give some buffer). Used in conjunction 
// with OutOfRangeTimeout to determine when an advertisement is no longer 
// considered "in-range".
watcher.SignalStrengthFilter.OutOfRangeThresholdInDBm = -75;

// Set the out-of-range timeout to be 2 seconds. Used in conjunction with 
// OutOfRangeThresholdInDBm to determine when an advertisement is no longer 
// considered "in-range"
watcher.SignalStrengthFilter.OutOfRangeTimeout = TimeSpan.FromMilliseconds(2000);

距離の測定Gauging Distance

Bluetooth LE ウォッチャーのコールバックがトリガーされたとき、eventArgs には受信シグナルの強さ (Bluetooth シグナルの強さ) を示す、RSSI 値が格納されています。When your Bluetooth LE Watcher's callback is triggered, the eventArgs include an RSSI value telling you the received signal strength (how strong the Bluetooth signal is).

private async void OnAdvertisementReceived(BluetoothLEAdvertisementWatcher watcher, BluetoothLEAdvertisementReceivedEventArgs eventArgs)
{
    // The received signal strength indicator (RSSI)
    Int16 rssi = eventArgs.RawSignalStrengthInDBm;
}

シグナルの強さからおよその距離を割り出すことができますが、電波はそれぞれ異なるため、正確な距離の測定に使うことはできません。This can be roughly translated into distance, but should not be used to measure true distances as each individual radio is different. さまざまな環境因子が存在するため、距離の測定は困難です (電波の周囲の壁や覆い、さらに湿度によっても電波状態が左右されます)。Different environmental factors can make distance difficult to gauge (such as walls, cases around the radio, or even air humidity).

そこで、純粋な距離を判断する代わりに「バケット」を定義することができます。An alternative to judging pure distance is to define "buckets". 電波は、発信源が非常に近い場合は 0 ~ -50 DBm、中程度の距離の場合は -50 ~ -90 DBm、遠く離れている場合は -90 DBm 未満を示す傾向があります。Radios tend to report 0 to -50 DBm when they are very close, -50 to -90 when they are a medium distance away, and below -90 when they are far away. アプリの作成にあたってこれらのバケットを判断するには、試行錯誤を繰り返すのが最良の方法です。Trial and error is best to determine what you want these buckets to be for your app.