Signatur
Beschreibung
Die Eigenschaft isPrimary eines BluetoothRemoteGATTService-Objekts gibt an, ob der Dienst auf dem entfernten Bluetooth-Low-Energy-Gerät ein primärer Dienst ist. Primäre Dienste stellen die Hauptfunktion eines Geräts dar, etwa heart_rate oder battery_service. Man findet sie über BluetoothRemoteGATTServer.getPrimaryService() oder getPrimaryServices().
Sekundäre Dienste (isPrimary === false) gibt es nicht eigenständig. Sie werden von anderen Diensten als eingebundene Dienste (Included Services) referenziert und über BluetoothRemoteGATTService.getIncludedService() bzw. getIncludedServices() abgerufen.
Nützlich ist die Eigenschaft vor allem beim Erkunden unbekannter Geräte, beim Debuggen von GATT-Profilen oder wenn Tools die Dienststruktur eines Geräts als Baum darstellen sollen. Der Wert ist schreibgeschützt und bleibt für die Lebensdauer des Dienstobjekts gleich.
Rückgabewert
true, wenn es sich um einen primären Dienst handelt, sonst false (sekundärer bzw. eingebundener Dienst).Beispiele
Primären Dienst abfragen und prüfen
const button = document.querySelector('#connect');
button.addEventListener('click', async () => {
// requestDevice erfordert eine Nutzergeste
const device = await navigator.bluetooth.requestDevice({
filters: [{ services: ['battery_service'] }]
});
const server = await device.gatt.connect();
const service = await server.getPrimaryService('battery_service');
console.log(`UUID: ${service.uuid}`);
console.log(`Primär: ${service.isPrimary}`);
});Dienststruktur inklusive eingebundener Dienste ausgeben
const dumpServices = async (server) => {
const services = await server.getPrimaryServices();
for (const service of services) {
console.log(`${service.isPrimary ? '[primär]' : '[sekundär]'} ${service.uuid}`);
try {
const included = await service.getIncludedServices();
for (const inc of included) {
console.log(` └ ${inc.isPrimary ? '[primär]' : '[sekundär]'} ${inc.uuid}`);
}
} catch (err) {
// Nicht jeder Browser bzw. jedes Gerät unterstützt Included Services
console.warn(` Keine eingebundenen Dienste: ${err.name}`);
}
}
};
document.querySelector('#scan').addEventListener('click', async () => {
const device = await navigator.bluetooth.requestDevice({
acceptAllDevices: true,
optionalServices: ['heart_rate', 'battery_service', 'device_information']
});
const server = await device.gatt.connect();
await dumpServices(server);
});Nur primäre Dienste filtern
const getOnlyPrimary = (services) =>
services.filter((service) => service.isPrimary);
// Beispiel mit einer bereits geladenen Dienstliste
const primary = getOnlyPrimary(allServices);
console.log(`${primary.length} primäre Dienste gefunden`);// Wichtig · Fallstricke
- Browser-Kompatibilität: Web Bluetooth gibt es nur in Chromium-Browsern (Chrome, Edge, Opera), und selbst dort je nach Plattform nur eingeschränkt. Firefox und Safari (auch iOS) unterstützen die API nicht. Prüfe die Unterstützung vorher mit
'bluetooth' in navigator. - Sicherer Kontext: Die API funktioniert nur über HTTPS (oder
localhost).requestDevice()muss durch eine Nutzergeste wie einen Klick ausgelöst werden. - Dienste über
getPrimaryService()/getPrimaryServices()liefern immertrue. Interessant wird die Eigenschaft also erst bei Diensten ausgetIncludedServices(), und diese Methode ist in Chrome derzeit nicht vollständig umgesetzt. - Dienste, die nicht in
filtersoderoptionalServicesstehen, sind nicht erreichbar. Der Versuch führt zu einemSecurityError. - Die Eigenschaft ist schreibgeschützt: Zuweisungen werden stillschweigend ignoriert (im Strict Mode:
TypeError).