藍牙 LE 通告

發行項
03/28/2024

本主題概述了通用 Windows 平台 (UWP) 應用程式的藍牙低功耗 (LE) 通告訊號發射器。

重要

您必須在 Package.appxmanifest 中宣告「藍牙」功能才能使用此功能。

<Capabilities> <DeviceCapability Name="bluetooth" /> </Capabilities>

重要 API

Windows.Devices.Bluetooth.Advertisement

支援的功能

LE Advertisement API 支援兩個主要功能：

通告觀察者：接聽附近的訊號發射器，並根據承載或鄰近性加以篩選。
通告發佈者：定義 Windows 的承載，以代表開發人員進行通告。

範例

有關藍牙 LE 通告的完整功能範例，請參閱 Github 上的藍牙通告範例。

基本設定

若要在通用 Windows 平台應用程式中使用基本的藍牙 LE 功能，您必須檢查 Package.appxmanifest 中的藍牙功能。

開啟 Package.appxmanifest
移至 [功能] 索引標籤
在左側清單中找到藍牙，然後選取其旁邊的方塊。

發佈通告

藍牙 LE 通告可讓您的裝置持續發出特定承載的訊號發射器，這稱為通告。如果附近任何支援 Bluetooth LE 的裝置設定為偵聽此特定廣告，則可以看到此廣告。

注意

為了保護使用者隱私，通告的生命週期與應用程式的生命週期有關。您可以建立 BluetoothLEAdvertisementPublisher，並在背景工作中呼叫 Start，以在背景發佈通告。如需背景工作的詳細資訊，請參閱啟動、繼續和背景工作。

有許多不同的方法可以將資料新增到通告中。以下範例示範了建立公司特定通告的常見方法。

首先，建立通告發佈者來控制裝置是否發出特定通告。

BluetoothLEAdvertisementPublisher publisher = new BluetoothLEAdvertisementPublisher();

其次，建立自訂資料區段。此範例使用未指派的 CompanyId 值 0xFFFE，並將文字 Hello World 新增至通告中。

// 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 開始進行通告。

publisher.Start();

監看通告

以下程式碼示範如何建立藍牙 LE 通告監看器、設定回呼，並開始監看所有 LE 通告。

BluetoothLEAdvertisementWatcher watcher = new BluetoothLEAdvertisementWatcher();
watcher.Received += OnAdvertisementReceived;
watcher.Start();

private async void OnAdvertisementReceived(BluetoothLEAdvertisementWatcher watcher, BluetoothLEAdvertisementReceivedEventArgs eventArgs)
{
    // Do whatever you want with the advertisement
}

主動掃描

若要也接收掃描回應通告，請在建立監看程式後設定以下內容。請注意，這將導致更大的功耗，並且在背景模式下不可用。

watcher.ScanningMode = BluetoothLEScanningMode.Active;

監看特定通告模式

有時您會想接聽特定的通告。在本例中，接聽包含虛構公司承載 (標識為 0xFFFE)，並在通告中包含 Hello World 字串。這可以與基本發佈範例配對，讓一台 Windows 機器做通告，另一台機器監看。請務必在啟動監看器之前設定此通告篩選器！

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);

監看附近的通告

有時，您只想在裝置通告進入範圍時觸發監看器。您可以定義自己的範圍，只需注意值將限制在 0 到 -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);

測量距離

當您的藍牙 LE 監看器回呼觸發時，eventArgs 會包含一個 RSSI 值，告知您接收到的訊號強度 (藍牙訊號有多強)。

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

這可以粗略地轉換為距離，但不應該用於測量真實距離，因為每個個別無線電都不同。不同的環境因素可能會使距離難以測量 (例如牆壁、收音機周圍的盒子，甚至空氣濕度)。

判斷純距離的另一種方法是定義「貯體」。當無線電距離非常近時，往往會報告 0 到 -50 DBm；當距離中等時，會報告為 -50 到 -90；當距離很遠時，報告會低於 -90。最好透過反覆試驗來確定您希望應用程式使用哪種貯體。