Klient Bluetooth GATT

Tento článek ukazuje, jak používat rozhraní API klienta Bluetooth Generic Attribute (GATT) v aplikacích pro Windows.

Important

V souboru Package.appxmanifest musíte deklarovat funkci "bluetooth".

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

Přehled

K přístupu k zařízením Bluetooth LE můžete použít rozhraní API v oboru názvů Windows.Devices.Bluetooth.GenericAttributeProfile. Zařízení Bluetooth LE zpřístupňují své funkce prostřednictvím kolekce:

  • Služby
  • Charakteristiky
  • Deskriptory

Služby definují funkční kontrakt zařízení LE a obsahují kolekci charakteristik, které definují službu. Tyto charakteristiky pak obsahují popisovače, které popisují vlastnosti. Tyto tři termíny se obecně označují jako atributy zařízení.

Rozhraní API Bluetooth LE GATT zpřístupňují objekty a funkce spíše než přímý přístup k nízkoúrovňové transportní vrstvě. Rozhraní API GATT vám také umožňují pracovat se zařízeními Bluetooth LE a provádět následující úlohy:

  • Provádění zjišťování atributů
  • Čtení a zápis hodnot atributů
  • Registrace zpětného volání pro událost charakteristické hodnotyChanged

Chcete-li vytvořit užitečnou implementaci, musíte mít předchozí znalosti služeb a charakteristik GATT, které má aplikace používat, a zpracovat konkrétní hodnoty charakteristik tak, aby binární data poskytovaná rozhraním API byla před jejich zobrazením uživateli převedena na užitečné informace. Rozhraní API GATT pro Bluetooth zpřístupňují pouze základní primitivy nezbytné pro komunikaci se zařízením Bluetooth LE. Aby bylo možné data interpretovat, musí být profil aplikace definován buď standardním profilem Bluetooth SIG, nebo vlastním profilem implementovaným dodavatelem zařízení. Profil vytvoří kontrakt vazby mezi aplikací a zařízením, pokud jde o to, co exchange data představují a jak je interpretovat.

Pro pohodlí siG Bluetooth udržuje seznam veřejných profilů , které jsou k dispozici.

Dotaz na okolní zařízení

Existují dvě hlavní metody dotazování na okolní zařízení:

Druhá metoda je popsána na delší dobu v dokumentaci o inzerování , takže to zde nebude popsáno, ale základní myšlenkou je najít adresu Bluetooth blízkých zařízení, která vyhovují konkrétnímu filtru reklamy. Jakmile budete mít adresu, můžete zavolat BluetoothLEDevice.FromBluetoothAddressAsync a získat odkaz na zařízení.

Teď se vraťte k metodě DeviceWatcher. Zařízení Bluetooth LE je ve Windows jako kterékoli jiné zařízení a lze jej zjišťovat pomocí rozhraní Enumeration APIs. Použijte třídu DeviceWatcher a předejte řetězec dotazu určující zařízení, která mají hledat:

// Query for extra properties you want returned
string[] requestedProperties = { "System.Devices.Aep.DeviceAddress", "System.Devices.Aep.IsConnected" };

DeviceWatcher deviceWatcher =
            DeviceInformation.CreateWatcher(
                    BluetoothLEDevice.GetDeviceSelectorFromPairingState(false),
                    requestedProperties,
                    DeviceInformationKind.AssociationEndpoint);

// Register event handlers before starting the watcher.
// Added, Updated and Removed are required to get all nearby devices
deviceWatcher.Added += DeviceWatcher_Added;
deviceWatcher.Updated += DeviceWatcher_Updated;
deviceWatcher.Removed += DeviceWatcher_Removed;

// EnumerationCompleted and Stopped are optional to implement.
deviceWatcher.EnumerationCompleted += DeviceWatcher_EnumerationCompleted;
deviceWatcher.Stopped += DeviceWatcher_Stopped;

// Start the watcher.
deviceWatcher.Start();

Jakmile spustíte DeviceWatcher, obdržíte DeviceInformation pro každé zařízení, které splňuje dotaz v obslužné rutině pro danou událost Added pro všechna zařízení. Podrobnější informace o deviceWatcheru najdete v kompletní ukázce on GitHub.

Připojení k zařízení

Jakmile zjistíte požadované zařízení, použijte DeviceInformation.Id k získání objektu zařízení Bluetooth LE pro dané zařízení:

private async Task ConnectDevice(DeviceInformation deviceInfo)
{
    // Note: BluetoothLEDevice.FromIdAsync must be called from a UI thread because it may prompt for consent.
    BluetoothLEDevice bluetoothLeDevice = await BluetoothLEDevice.FromIdAsync(deviceInfo.Id);
    // ...
}

Na druhou stranu uvolnění všech odkazů na objekt BluetoothLEDevice pro dané zařízení (a pokud žádná jiná aplikace v systému nemá na toto zařízení odkaz) způsobí po krátké prodlevě automatické odpojení.

bluetoothLeDevice.Dispose();

Pokud aplikace potřebuje znovu získat přístup k zařízení, stačí znovu vytvořit objekt zařízení a přistoupit k charakteristice (probrané v další části); operační systém pak v případě potřeby automaticky obnoví připojení. Pokud je zařízení v blízkosti, získáte přístup k zařízení, jinak se vrátí s chybou DeviceUnreachable.

Note

Vytvoření objektu BluetoothLEDevice voláním této metody (nutně) neicializuje připojení. Chcete-li navázat připojení, nastavte GattSession.MaintainConnection na true, nebo zavolejte metodu zjišťování služeb bez použití mezipaměti u objektu BluetoothLEDevice, nebo proveďte operaci čtení nebo zápisu na zařízení.

  • Pokud je GattSession.MaintainConnection nastavena na hodnotu true, systém čeká na připojení po neomezenou dobu a připojí se, jakmile bude zařízení dostupné. Vaše aplikace nemá na co čekat, protože GattSession.MaintainConnection je vlastnost.
  • Při zjišťování služeb a operacích čtení a zápisu v GATT systém čeká po omezenou, ale proměnlivou dobu. Může to trvat od okamžiku až po několik minut. Mezi faktory patří zatížení zásobníku a to, jak dlouho požadavek čeká ve frontě. Pokud neexistují žádné další nevyřízené požadavky a vzdálené zařízení není dostupné, systém počká sedm (7) sekund, než vyprší časový limit. Pokud existují další čekající požadavky, zpracování každého požadavku ve frontě může trvat sedm (7) sekund, takže čím dál se vaše fronta blíží k zadní straně fronty, tím déle počkáte.

V současné době nemůžete zrušit proces připojení.

Výčet podporovaných služeb a charakteristik

Teď, když máte objekt BluetoothLEDevice, dalším krokem je zjistit, jaká data zařízení zveřejňuje. Prvním krokem k tomuto kroku je dotazování na služby:

GattDeviceServicesResult result = await bluetoothLeDevice.GetGattServicesAsync();

if (result.Status == GattCommunicationStatus.Success)
{
    var services = result.Services;
    // ...
}

Jakmile je služba zájmu identifikována, dalším krokem je dotazování na charakteristiky.

GattCharacteristicsResult result = await service.GetCharacteristicsAsync();

if (result.Status == GattCommunicationStatus.Success)
{
    var characteristics = result.Characteristics;
    // ...
}

Operační systém vrací seznam objektů GattCharacteristic pouze pro čtení, se kterými pak můžete provádět operace.

Provádění operací čtení a zápisu u charakteristické vlastnosti

Charakteristika je základní jednotkou komunikace založené na GATT. Obsahuje hodnotu, která představuje jedinečnou část dat v zařízení. Například charakteristika úrovně baterie má hodnotu, která představuje úroveň baterie zařízení.

Přečtěte si vlastnosti charakteristik a určete, jaké operace jsou podporovány:

GattCharacteristicProperties properties = characteristic.CharacteristicProperties;

if(properties.HasFlag(GattCharacteristicProperties.Read))
{
    // This characteristic supports reading from it.
}
if(properties.HasFlag(GattCharacteristicProperties.Write))
{
    // This characteristic supports writing to it.
}
if(properties.HasFlag(GattCharacteristicProperties.Notify))
{
    // This characteristic supports subscribing to notifications.
}

Pokud je čtení podporované, můžete si tuto hodnotu přečíst:

GattReadResult result = await selectedCharacteristic.ReadValueAsync();
if (result.Status == GattCommunicationStatus.Success)
{
    var reader = DataReader.FromBuffer(result.Value);
    byte[] input = new byte[reader.UnconsumedBufferLength];
    reader.ReadBytes(input);
    // Utilize the data as needed
}

Zápis do charakteristiky probíhá podobným způsobem:

var writer = new DataWriter();
// WriteByte used for simplicity. Other common functions - WriteInt16 and WriteSingle
writer.WriteByte(0x01);

GattCommunicationStatus result = await selectedCharacteristic.WriteValueAsync(writer.DetachBuffer());
if (result == GattCommunicationStatus.Success)
{
    // Successfully wrote to device
}

Tip

DataReader a DataWriter jsou nepostradatelné při práci s nezpracovanými vyrovnávacími paměťmi, které získáte z mnoha rozhraní API Bluetooth.

Přihlášení k odběru oznámení

Ujistěte se, že charakteristika podporuje buď Indicate, nebo Notify (ověřte to ve vlastnostech charakteristiky).

Indicate je považována za spolehlivější, protože každá změněná událost hodnoty je spojená s potvrzením z klientského zařízení. Notify je běžnější, protože většina transakcí GATT upřednostňuje nižší spotřebu energie před extrémní spolehlivostí. V každém případě se všechno zpracovává ve vrstvě kontroleru, aby se aplikace nezúčastněla. Souhrnně je budeme označovat jako "oznámení".

Před získáním oznámení je potřeba se postarat o dvě věci:

  • Zapsat do popisovače konfigurace klientské charakteristiky (CCCD)
  • Zpracování události Characteristic.ValueChanged

Zápis do CCCD informuje serverové zařízení, že tento klient chce vědět pokaždé, když se změní konkrétní charakteristické hodnoty. Postup:

GattCommunicationStatus status = await selectedCharacteristic.WriteClientCharacteristicConfigurationDescriptorAsync(
                        GattClientCharacteristicConfigurationDescriptorValue.Notify);
if(status == GattCommunicationStatus.Success)
{
    // Server has been informed of clients interest.
}

Nyní bude událost ValueChanged objektu GattCharacteristic vyvolána pokaždé, když se hodnota změní na vzdáleném zařízení. Zbývá už jen naimplementovat obslužnou rutinu:

characteristic.ValueChanged += Characteristic_ValueChanged;

...

void Characteristic_ValueChanged(GattCharacteristic sender,
                                    GattValueChangedEventArgs args)
{
    // An Indicate or Notify reported that the value has changed.
    var reader = DataReader.FromBuffer(args.CharacteristicValue);
    // Parse the data however required.
}

Examples

Úplnou ukázku najdete v části Bluetooth Low Energy sample.

  • Last updated on