Web Bluetooth

1. If filter.name is present then, if device’s Bluetooth Device Name isn’t complete and equal to filter.name, return mismatch.

2. If filter.namePrefix is present then if device’s Bluetooth Device Name isn’t present or doesn’t start with filter.namePrefix, return mismatch.

3. For each uuid in filter.services, if the UA has not received advertising data, an extended inquiry response, or a service discovery response indicating that the device supports a primary (vs included) service with UUID uuid, return mismatch.

4. For each manufacturerData in filter["manufacturerData"], if device hasn’t advertised manufacturer specific data with a company identifier code equal to manufacturerData["companyIdentifier"] and with data that matches manufacturerData return mismatch.

5. For each serviceData in filter["serviceData"], if device hasn’t advertised service data with a UUID whose 128-bit form is serviceData["service"] and with data that matches serviceData return mismatch.

6. Return match.

1. Let expectedPrefix be a copy of the bytes held by filter.dataPrefix.

2. Let mask be a copy of the bytes held by filter.mask.

3. If data has fewer bytes than expectedPrefix, return mismatch.

4. For each 1 bit in mask, if the corresponding bit in data is not equal to the corresponding bit in expectedPrefix, return mismatch.

5. Return match.

1. If the length of filter1 is less than the length of filter2, return false.

2. Let byteIndex be 0.

3. While byteIndex is less than the length of filter2, do the following sub-steps:

   1. If filter1.mask[byteIndex] & filter2.mask[byteIndex] is not equal to filter2.mask[byteIndex], return false.

   2. If filter1.dataPrefix[byteIndex] & filter2.mask[byteIndex] it not equal to filter2.dataPrefix[byteIndex] & filter2.mask[byteIndex], return false.

   3. Set byteIndex to byteIndex + 1.

4. Return true.

1. If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "bluetooth", reject promise with a SecurityError and abort these steps.

2. Let devices be a new empty Array.

3. For each allowedDevice in storage.allowedDevices, add the BluetoothDevice object representing allowedDevice@[[device]] to devices.

4. Resolve promise with devices.

   Note: The BluetoothDevices in devices may not be in range of the Bluetooth radio. For a given device in devices, the watchAdvertisements() method can be used to observe when device is in range and broadcasting advertisement packets. When an advertisementreceived event event is fired on a device, it may indicate that it is close enough for a connection to be established by calling event.device.gatt.connect().

1. If options.exclusionFilters is present and options.filters is not present, reject promise with a TypeError and abort these steps.

2. If options.filters is present and options.acceptAllDevices is true, or if options.filters is not present and options.acceptAllDevices is false, reject promise with a TypeError and abort these steps.

   Note: This enforces that exactly one of filters or acceptAllDevices:true is present.

3. Request Bluetooth devices, passing options.filters if options.acceptAllDevices is false or null otherwise, passing options.exclusionFilters if it exists or null otherwise, passing options.optionalServices, and passing options.optionalManufacturerData, and let devices be the result.

4. If the previous step threw an exception, reject promise with that exception and abort these steps.

5. If devices is an empty sequence, reject promise with a NotFoundError and abort these steps.

6. Resolve promise with devices[0].

1. Let global be the relevant global object for storage.

2. Let document be global’s associated Document.

3. If document is not allowed to use the policy-controlled feature named "bluetooth", throw a SecurityError and abort these steps.

4. Check that the algorithm is triggered while its relevant global object has a transient activation, otherwise throw a SecurityError and abort these steps.

5. In order to convert the arguments from service names and aliases to just UUIDs, do the following sub-steps:

   1. If filters !== null && filters.length === 0, throw a TypeError and abort these steps.

   2. If exclusionFilters !== null && exclusionFilters.length === 0, throw a TypeError and abort these steps.

   3. Let uuidFilters be a new Array, uuidExclusionFilters be a new Array, and requiredServiceUUIDs be a new Set.

   4. If filters is null, then set requiredServiceUUIDs to the set of all UUIDs.

   5. If filters isn’t null, then for each filter in filters, do the following steps:

      1. Let canonicalFilter be the result of canonicalizing filter.

      2. Append canonicalFilter to uuidFilters.

      3. Add the contents of canonicalFilter.services to requiredServiceUUIDs.

   6. If exclusionFilters isn’t null, then for each exclusionFilter in exclusionFilters, do the following steps:

      1. Let canonicalExclusionFilter be the result of canonicalizing exclusionFilter.

      2. Append canonicalExclusionFilter to uuidExclusionFilters.

   7. Let optionalServiceUUIDs be Array.prototype.map.call(optionalServices, BluetoothUUID.getService).

   8. If any of the BluetoothUUID.getService() calls threw an exception, throw that exception and abort these steps.

   9. Remove from optionalServiceUUIDs any UUIDs that are blocklisted.

6. Let descriptor be

   {
     name: "bluetooth",
     filters: uuidFilters
     optionalServices: optionalServiceUUIDs,
     optionalManufacturerData: optionalManufacturerData
     acceptAllDevices: filters !== null,
   }
   

7. Let state be descriptor’s permission state.

   Note: state will be "denied" in non-secure contexts because powerful features can’t be used in non-secure contexts.

8. If state is "denied", return [] and abort these steps.

9. If the UA can prove that no devices could possibly be found in the next step, for example because there is no Bluetooth adapter with which to scan, or because the filters can’t be matched by any possible advertising packet, the UA MAY return [] and abort these steps.

10. Let scanResult be the result of invoking scan for devices with global and requiredServiceUUIDs.

11. If filters isn’t null, do the following sub-steps:

    1. Remove devices from scanResult if they do not match a filter in uuidFilters.

    2. If exclusionFilters isn’t null, remove devices from scanResult if they match a filter in uuidExclusionFilters.

12. Let navigable be document’s navigable.

13. Let promptId be a new unique opaque string.

In practice, the device list is dynamically updated while a prompt is open. The spec text currently does not reflect that but this event might be emitted multiple times with the same promptId and the fresh device list. See https://github.com/WebBluetoothCG/web-bluetooth/issues/621.

1. Trigger a prompt updated event given navigable, promptId, and scanResult.

2. Even if scanResult is empty, prompt the user to choose one of the devices in scanResult, associated with descriptor, and let device be the result.

   The UA MAY allow the user to select a nearby device that does not match uuidFilters.

   Note: The UA should show the user the human-readable name of each device. If this name is not available because, for example, the UA’s Bluetooth system doesn’t support privacy-enabled scans, the UA should allow the user to indicate interest and then perform a privacy-disabled scan to retrieve the name.

3. Remove map of navigables to device prompts[navigable’s navigable id].

4. The UA MAY add device to storage.

   Note: Choosing a device probably indicates that the user intends that device to appear in the allowedDevices list of "bluetooth"’s extra permission data for at least the current settings object, for its mayUseGATT field to be true, for all the services in the union of requiredServiceUUIDs and optionalServiceUUIDs to appear in its allowedServices list, in addition to any services that were already there, and for the manufacturer codes in optionalManufacturerData to appear in its allowedManufacturerData list.

5. If device is "denied", return [] and abort these steps.

6. The UA MAY populate the Bluetooth cache with all Services inside device. Ignore any errors from this step.

7. Get the BluetoothDevice representing device inside this, propagating any exception, and let deviceObj be the result.

8. Return [deviceObj].

1. If none of filter’s members is present, throw a TypeError and abort these steps.

2. Let canonicalizedFilter be {}.

3. If filter.services is present, do the following sub-steps:

   1. If filter.services.length === 0, throw a TypeError and abort these steps.

   2. Let services be Array.prototype.map.call(filter.services, BluetoothUUID.getService).

   3. If any of the BluetoothUUID.getService() calls threw an exception, throw that exception and abort these steps.

   4. If any service in services is blocklisted, throw a SecurityError and abort these steps.

   5. Set canonicalizedFilter.services to services.

4. If filter.name is present, do the following sub-steps.

   1. If the UTF-8 encoding of filter.name is more than 248 bytes long, throw a TypeError and abort these steps.

      Note: 248 is the maximum number of UTF-8 code units in a Bluetooth Device Name.

   2. Set canonicalizedFilter.name to filter.name.

5. If filter.namePrefix is present, do the following sub-steps.

   1. If filter.namePrefix.length === 0 or if the UTF-8 encoding of filter.namePrefix is more than 248 bytes long, throw a TypeError and abort these steps.

      Note: 248 is the maximum number of UTF-8 code units in a Bluetooth Device Name.

   2. Set canonicalizedFilter.namePrefix to filter.namePrefix.

6. Set canonicalizedFilter["manufacturerData"] to [].

7. If filter["manufacturerData"] is present and filter["manufacturerData"].length === 0, throw a TypeError and abort these steps.

8. For each manufacturerData in filter["manufacturerData"], do the following sub-steps:

   1. If manufacturerData is a blocklisted manufacturer data filter, throw a SecurityError and abort these steps.

   2. If there exists an object existing in canonicalizedFilter["manufacturerData"] where existing["companyIdentifier"] === manufacturerData["companyIdentifier"], throw a TypeError and abort these steps.

   3. Let canonicalizedManufacturerDataFilter be the result of canonicalizing manufacturerData, converted to an ECMAScript value. If this throws an exception, propagate that exception and abort these steps.

   4. Set canonicalizedManufacturerDataFilter["companyIdentifier"] to manufacturerData["companyIdentifier"].

   5. Append canonicalizedManufacturerDataFilter to canonicalizedFilter["manufacturerData"].

9. Set canonicalizedFilter.serviceData to [].

10. If filter["serviceData"] is present and filter["serviceData"].length === 0, throw a TypeError and abort these steps.

11. For each serviceData in filter["serviceData"], do the following sub-steps:

    1. Let service be BluetoothUUID.getService(serviceData["service"]). If this throws an exception, propagate that exception and abort these steps.

    2. If service is blocklisted, throw a SecurityError and abort these steps.

    3. Let canonicalizedServiceDataFilter be the result of canonicalizing serviceData, converted to an ECMAScript value. If this throws an exception, propagate that exception and abort these steps.

    4. Set canonicalizedServiceDataFilter["service"] to service.

    5. Append canonicalizedServiceDataFilter to canonicalizedFilter["serviceData"].

12. Return canonicalizedFilter.

1. If filter.dataPrefix is not present, let dataPrefix be an empty sequence of bytes. Otherwise, do the following sub-steps:

   1. Let dataPrefix be a copy of the bytes held by filter.dataPrefix.

   2. If the length of dataPrefix is zero, throw a TypeError and abort these steps.

2. If filter.mask is present, let mask be a copy of the bytes held by filter.mask. Otherwise, let mask be a sequence of 0xFF bytes the same length as dataPrefix.

3. If mask is not the same length as dataPrefix, throw a TypeError and abort these steps.

4. Return {dataPrefix: new Uint8Array(|dataPrefix|), mask: new Uint8Array(|mask|)}.

1. If the UA has scanned for devices recently with a set of UUIDs that was a superset of the UUIDs for the current scan, then the UA MAY return the result of that scan and abort these steps.

   TODO: Nail down the amount of time.

2. Let nearbyDevices be a set of Bluetooth devices, initially equal to the set of devices that are connected (have an ATT Bearer) to the UA.

3. Let topLevelTraversable be the global’s navigable's top-level traversable.

4. Let simulatedBluetoothDevices be an empty list.

5. If topLevelTraversable has a simulated Bluetooth adapter, let simulatedBluetoothDevices be the result of getting the values of its simulated Bluetooth device mapping.

   Support asynchronous device discovery.

6. If the UA supports the LE transport, perform the General Discovery Procedure, except that the UA may include devices that have no Discoverable Mode flag set, and add the discovered Bluetooth devices to nearbyDevices. The UA SHOULD enable the Privacy Feature.

   Both passive scanning and the Privacy Feature avoid leaking the unique, immutable device ID. We ought to require UAs to use either one, but none of the OS APIs appear to expose either. Bluetooth also makes it hard to use passive scanning since it doesn’t require Central devices to support the Observation Procedure.

7. If the UA supports the BR/EDR transport, perform the Device Discovery Procedure and add the discovered Bluetooth devices to nearbyDevices.

   All forms of BR/EDR inquiry/discovery appear to leak the unique, immutable device address.

8. Let result be a set of Bluetooth devices, initially empty.

9. For each Bluetooth device device in nearbyDevices and simulatedBluetoothDevices, do the following sub-steps:

   1. If device’s supported physical transports include LE and its Bluetooth Device Name is partial or absent, the UA SHOULD perform the Name Discovery Procedure to acquire a complete name.

   2. If device’s advertised Service UUIDs have a non-empty intersection with the set of Service UUIDs, add device to result and abort these sub-steps.

      Note: For BR/EDR devices, there is no way to distinguish GATT from non-GATT services in the Extended Inquiry Response. If a site filters to the UUID of a non-GATT service, the user may be able to select a device for the result of requestDevice that this API provides no way to interact with.

   3. The UA MAY connect to device and populate the Bluetooth cache with all Services whose UUIDs are in the set of Service UUIDs. If device’s supported physical transports include BR/EDR, then in addition to the standard GATT procedures, the UA MAY use the Service Discovery Protocol (Searching for Services) when populating the cache.

      Note: Connecting to every nearby device to discover services costs power and can slow down other use of the Bluetooth radio. UAs should only discover extra services on a device if they have some reason to expect that device to be interesting.

      UAs should also help developers avoid relying on this extra discovery behavior. For example, say a developer has previously connected to a device, so the UA knows the device’s full set of supported services. If this developer then filters using a non-advertised UUID, the dialog they see may include this device, even if the filter would likely exclude the device on users' machines. The UA could provide a developer option to warn when this happens or to include only advertised services in matching filters.

   4. If the Bluetooth cache contains known-present Services inside device with UUIDs in the set of Service UUIDs, the UA MAY add device to result.

10. Return result from the scan.

1. Let grantedServiceUUIDs be a new Set.

2. Add the contents of requiredServiceUUIDs to grantedServiceUUIDs.

3. Add the contents of optionalServiceUUIDs to grantedServiceUUIDs.

4. Search for an element allowedDevice in storage.allowedDevices where device is equal to allowedDevice@[[device]]. If one is found, perform the following sub-steps:

   1. Add the contents of allowedDevice.allowedServices to grantedServiceUUIDs.

   If one is not found, perform the following sub-steps:

   1. Let allowedDevice.deviceId be a unique ID to the extent that the UA can determine that two Bluetooth connections are the same device and to the extent that the user wants to expose that fact to script.

5. Set allowedDevice.allowedServices to grantedServiceUUIDs.

6. Set allowedDevice.mayUseGATT to true.

1. If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "bluetooth", queue a task to resolve promise with false, and abort these steps.

2. If the user has configured the UA to return a particular answer from this function for the current origin, queue a task to resolve promise with the configured answer, and abort these steps.

   Note: If the Web Bluetooth permission has been blocked by the user, the UA may resolve promise with false.

3. Let simulatedBluetoothAdapter be this's navigable's top-level traversable's simulated Bluetooth adapter.

4. If simulatedBluetoothAdapter is not empty,

   1. If simulatedBluetoothAdapter’s adapter state is "absent", queue a task to resolve promise with false.

   2. Otherwise, queue a task to resolve promise with true.

   3. Abort these steps.

5. If the UA is running on a system that has a Bluetooth radio queue a task to resolve promise with true regardless of the powered state of the Bluetooth radio.

6. Otherwise, queue a task to resolve promise with false.

   Note: The promise is resolved in parallel to let the UA call out to other systems to determine whether Bluetooth is available.

1. Let storage, a BluetoothPermissionStorage, be "bluetooth"’s extra permission data for the current settings object.

2. Find the allowedDevice in storage.allowedDevices with allowedDevice.[[device]] the same device as device. If there is no such object, throw a SecurityError and abort these steps.

3. If there is no key in context.[[deviceInstanceMap]] that is the same device as device, run the following sub-steps:

   1. Let result be a new instance of BluetoothDevice.

   2. Initialize all of result’s optional fields to null.

   3. Initialize result.[[context]] to context.

   4. Initialize result.[[representedDevice]] to device.

   5. Initialize result.id to allowedDevice.deviceId, and initialize result.[[allowedServices]] to allowedDevice.allowedServices.

   6. If device has a partial or complete Bluetooth Device Name, set result.name to that string.

   7. Initialize result.watchingAdvertisements to false.

   8. Add a mapping from device to result in context.[[deviceInstanceMap]].

4. Return the value in context.[[deviceInstanceMap]] whose key is the same device as device.

1. If "bluetooth"’s extra permission data for this’s relevant settings object has an AllowedBluetoothDevice allowedDevice in its allowedDevices list with allowedDevice.[[device]] the same device as this.[[representedDevice]] and allowedDevice.mayUseGATT equal to true, return this.[[gatt]].

2. Otherwise, return null.

1. Let device be the target BluetoothDevice object.

2. Let storage be the BluetoothPermissionStorage object in the current script execution environment.

3. Remove device from storage with storage.

4. Resolve promise.

1. If options.signal is present, then perform the following sub-steps:

   1. If options.signal is aborted, then abort watchAdvertisements with this and abort these steps.

   2. Add the following abort steps to options.signal:

      1. Abort watchAdvertisements with this.

      2. Reject promise with AbortError

2. If this.[[watchAdvertisementsState]] is:

   'not-watching'

   1. Set this.[[watchAdvertisementsState]] to 'pending-watch'.

   2. Enqueue the following steps to the watch advertisements manager, but abort when this.[[watchAdvertisementsState]] becomes not-watching:

      1. Ensure that the UA is scanning for this device’s advertisements. The UA SHOULD NOT filter out "duplicate" advertisements for the same device.

      2. If the UA fails to enable scanning, queue a task to perform the following steps, and abort these steps:

         1. Set this.[[watchAdvertisementsState]] to 'not-watching'.

         2. Reject promise with one of the following errors:

            The UA doesn’t support scanning for advertisements

            NotSupportedError

            Bluetooth is turned off

            InvalidStateError

            Other reasons

            UnknownError

      3. Queue a task to perform the following steps, but abort when this.[[watchAdvertisementsState]] becomes not-watching:

         1. Set this.[[watchAdvertisementsState]] to watching.

         2. Set this.watchingAdvertisements to true.

         3. Resolve promise with undefined.

   'pending-watch'

   1. Reject promise with InvalidStateError.

   'watching'

   1. Resolve promise with undefined.

3. If aborted, reject promise with AbortError.

Note: Scanning costs power, so websites should avoid watching for advertisements unnecessarily, and should use their AbortController to stop using power as soon as possible.

1. Set this.[[watchAdvertisementsState]] to 'not-watching'.

2. Set device.watchingAdvertisements to false.

3. Enqueue the following steps to watch advertisements manager:

   1. If no more BluetoothDevices in the whole UA have watchingAdvertisements set to true, the UA SHOULD stop scanning for advertisements. Otherwise, if no more BluetoothDevices representing the same device as this have watchingAdvertisements set to true, the UA SHOULD reconfigure the scan to avoid receiving reports for this device.

1. For each device in Bluetooth.[[deviceInstanceMap]], perform the following steps:

   1. If device.[[watchAdvertisementsState]] is pending-watch or watching, run abort watchAdvertisements with device.

1. Attempt to make all matching entries in the cache either known-present or known-absent, using any sequence of GATT procedures that [BLUETOOTH42] specifies will return enough information. Handle errors as described in § 6.7 Error handling.

2. If the previous step returns an error, return that error from this algorithm.

1. Populate the Bluetooth cache with entries matching the description.

2. If the previous step returns an error, reject promise with that error and abort these steps.

3. Let entries be the sequence of known-present cache entries matching the description.

4. Let context be deviceObj.[[context]].

5. Let result be a new sequence.

6. For each entry in entries:

   1. If entry has no associated Promise<BluetoothGATT*> instance in context.[[attributeInstanceMap]], create a BluetoothRemoteGATTService representing entry, create a BluetoothRemoteGATTCharacteristic representing entry, or create a BluetoothRemoteGATTDescriptor representing entry, depending on whether entry is a Service, Characteristic, or Descriptor, and add a mapping from entry to the resulting Promise in context.[[attributeInstanceMap]].

   2. Append to result the Promise<BluetoothGATT*> instance associated with entry in context.[[attributeInstanceMap]].

7. Resolve promise with the result of waiting for all elements of result.

BluetoothDevice

obj.[[representedDevice]]

BluetoothRemoteGATTService

obj.[[representedService]]

BluetoothRemoteGATTCharacteristic

obj.[[representedCharacteristic]]

BluetoothRemoteGATTDescriptor

obj.[[representedDescriptor]]

1. If uuid is present, set it to uuidCanonicalizer(uuid). If uuidCanonicalizer threw an exception, return a promise rejected with that exception and abort these steps.

2. If uuid is present and is blocklisted, return a promise rejected with a SecurityError and abort these steps.

3. Let deviceObj be, depending on the type of attribute:

   BluetoothDevice

   attribute

   BluetoothRemoteGATTService

   attribute.device

   BluetoothRemoteGATTCharacteristic

   attribute.service.device

4. If deviceObj.gatt.connected is false, return a promise rejected with with a NetworkError and abort these steps.

5. If Represented(attribute) is null, return a promise rejected with an InvalidStateError and abort these steps.

   Note: This happens when a Service or Characteristic is removed from the device or invalidated by a disconnection, and then its object is used again.

6. Query the Bluetooth cache in deviceObj for entries that:

   • are within Represented(attribute),

   • have a type described by child type,

   • have a UUID that is not blocklisted,

   • if uuid is present, have a UUID of uuid,

   • if allowedUuids is present and not "all", have a UUID in allowedUuids, and

   • if the single flag is set, are the first of these.

   Let promise be the result.

7. Upon fulfillment of promise with result, run the following steps:

   • If result is empty, throw a NotFoundError,

   • Otherwise, if the single flag is set, returns the first (only) element of result.

   • Otherwise, return result.

1. Let promise be a new promise.

2. If this.device.[[representedDevice]] is null, queue a task to reject promise with a NetworkError, return promise, and abort these steps.

3. If the UA is currently using the Bluetooth system, it MAY queue a task to reject promise with a NetworkError, return promise, and abort these steps.

   Implementations may be able to avoid this NetworkError, but for now sites need to serialize their use of this API and/or give the user a way to retry failed operations. [Issue #188]

4. Add promise to this.[[activeAlgorithms]].

5. Return promise and run the following steps in parallel:

   1. If this.device.[[representedDevice]] has no ATT Bearer, do the following sub-steps:

      1. Attempt to create an ATT Bearer using the procedures described in "Connection Establishment" under GAP Interoperability Requirements. Abort this attempt if promise is removed from this.[[activeAlgorithms]].

         Note: These procedures can wait forever if a connectable advertisement isn’t received. The website should call disconnect() if it no longer wants to connect.

      2. If this attempt was aborted because promise was removed from this.[[activeAlgorithms]], reject promise with an AbortError and abort these steps.

      3. If this attempt failed for another reason, reject promise with a NetworkError and abort these steps.

      4. Use the Exchange MTU procedure to negotiate the largest supported MTU. Ignore any errors from this step.

      5. The UA MAY attempt to bond with the remote device using the BR/EDR Bonding Procedure or the LE Bonding Procedure.

         Note: We would normally prefer to give the website control over whether and when bonding happens, but the Core Bluetooth platform API doesn’t provide a way for UAs to implement such a knob. Having a bond is more secure than not having one, so this specification allows the UA to opportunistically create one on platforms where that’s possible. This may cause a user-visible pairing dialog to appear when a connection is created, instead of when a restricted characteristic is accessed.

   2. Queue a task to perform the following sub-steps:

      1. If promise is not in this.[[activeAlgorithms]], reject promise with an AbortError, garbage-collect the connection of this.[[representedDevice]], and abort these steps.

      2. Remove promise from this.[[activeAlgorithms]].

      3. If this.device.[[representedDevice]] is null, reject promise with a NetworkError, garbage-collect the connection of this.[[representedDevice]], and abort these steps.

      4. Set this.connected to true.

      5. Resolve promise with this.

1. Clear this.[[activeAlgorithms]] to abort any active connect() calls.

2. If this.connected is false, abort these steps.

3. Clean up the disconnected device this.device.

4. Let device be this.device.[[representedDevice]].

5. Garbage-collect the connection of device.

1. If systems that aren’t using this API, either inside or outside of the UA, are using the device’s ATT Bearer, abort this algorithm.

2. For all BluetoothDevices deviceObj in the whole UA:

   1. If deviceObj.[[representedDevice]] is not the same device as device, continue to the next deviceObj.

   2. If deviceObj.gatt.connected is true, abort this algorithm.

   3. If deviceObj.gatt.[[activeAlgorithms]] contains the Promise of a call to connect(), abort this algorithm.

3. Destroy device’s ATT Bearer.

To create a gattServer-connection-checking wrapper around a Promise promise, the UA MUST:

1. If gattServer.connected is true, add promise to gattServer.[[activeAlgorithms]].

2. React to promise:

   • If promise was fulfilled with value result, then:

     1. If promise is in gattServer.[[activeAlgorithms]], remove it and return result.

     2. Otherwise, throw a NetworkError.

        Note: This error is thrown because gattServer was disconnected during the execution of the main algorithm.

   • If promise was rejected with reason error, then:

     1. If promise is in gattServer.[[activeAlgorithms]], remove it and throw error.

     2. Otherwise, throw a NetworkError.

        Note: This error is thrown because gattServer was disconnected during the execution of the main algorithm.

1. If this.device.[[allowedServices]] is not "all" and service is not in this.device.[[allowedServices]], return a promise rejected with a SecurityError and abort these steps.

2. Return GetGATTChildren(attribute=this.device,
   single=true,
   uuidCanonicalizer=BluetoothUUID.getService,
   uuid=service,
   allowedUuids=this.device.[[allowedServices]],
   child type="GATT Primary Service")

1. If this.device.[[allowedServices]] is not "all", and service is present and not in this.device.[[allowedServices]], return a promise rejected with a SecurityError and abort these steps.

2. Return GetGATTChildren(attribute=this.device,
   single=false,
   uuidCanonicalizer=BluetoothUUID.getService,
   uuid=service,
   allowedUuids=this.device.[[allowedServices]],
   child type="GATT Primary Service")

1. Let result be a new instance of BluetoothRemoteGATTService with its [[representedService]] slot initialized to service.

2. Get the BluetoothDevice representing the device in which service appears, and let device be the result.

3. If the previous step threw an error, reject promise with that error and abort these steps.

4. Initialize result.device from device.

5. Initialize result.uuid from the UUID of service.

6. If service is a Primary Service, initialize result.isPrimary to true. Otherwise initialize result.isPrimary to false.

7. Resolve promise with result.

GetGATTChildren(attribute=this,
single=true,
uuidCanonicalizer=BluetoothUUID.getCharacteristic,
uuid=characteristic,
allowedUuids=undefined,
child type="GATT Characteristic")

GetGATTChildren(attribute=this,
single=false,
uuidCanonicalizer=BluetoothUUID.getCharacteristic,
uuid=characteristic,
allowedUuids=undefined,
child type="GATT Characteristic")

1. Let result be a new instance of BluetoothRemoteGATTCharacteristic with its [[representedCharacteristic]] slot initialized to characteristic.

2. Initialize result.service from the BluetoothRemoteGATTService instance representing the Service in which characteristic appears.

3. Initialize result.uuid from the UUID of characteristic.

4. Create a BluetoothCharacteristicProperties instance from the Characteristic characteristic, and let propertiesPromise be the result.

5. Wait for propertiesPromise to settle.

6. If propertiesPromise was rejected, resolve promise with propertiesPromise and abort these steps.

7. Initialize result.properties from the value propertiesPromise was fulfilled with.

8. Initialize result.value to null. The UA MAY initialize result.value to a new DataView wrapping a new ArrayBuffer containing the most recently read value from characteristic if this value is available.

9. Resolve promise with result.

GetGATTChildren(attribute=this,
single=true,
uuidCanonicalizer=BluetoothUUID.getDescriptor,
uuid=descriptor,
allowedUuids=undefined,
child type="GATT Descriptor")

GetGATTChildren(attribute=this,
single=false,
uuidCanonicalizer=BluetoothUUID.getDescriptor,
uuid=descriptor,
allowedUuids=undefined,
child type="GATT Descriptor")

1. If this.uuid is blocklisted for reads, return a promise rejected with a SecurityError and abort these steps.

2. If this.service.device.gatt.connected is false, return a promise rejected with a NetworkError and abort these steps.

3. Let characteristic be this.[[representedCharacteristic]].

4. If characteristic is null, return a promise rejected with an InvalidStateError and abort these steps.

5. Return a this.service.device.gatt-connection-checking wrapper around a new promise promise and run the following steps in parallel:

   1. If the Read bit is not set in characteristic’s properties, reject promise with a NotSupportedError and abort these steps.

   2. If the UA is currently using the Bluetooth system, it MAY reject promise with a NetworkError and abort these steps.

      Implementations may be able to avoid this NetworkError, but for now sites need to serialize their use of this API and/or give the user a way to retry failed operations. [Issue #188]

   3. Use any combination of the sub-procedures in the Characteristic Value Read procedure to retrieve the value of characteristic. Handle errors as described in § 6.7 Error handling.

   4. If the previous step returned an error, reject promise with that error and abort these steps.

   5. Queue a task to perform the following steps:

      1. If promise is not in this.service.device.gatt.[[activeAlgorithms]], reject promise with a NetworkError and abort these steps.

      2. Let buffer be an ArrayBuffer holding the retrieved value, and assign new DataView(buffer) to this.value.

      3. Fire an event named characteristicvaluechanged with its bubbles attribute initialized to true at this.

      4. Resolve promise with this.value.

1. If this.uuid is blocklisted for writes, return a promise rejected with a SecurityError and abort these steps.

2. Let bytes be a copy of the bytes held by value.

3. If bytes is more than 512 bytes long (the maximum length of an attribute value, per Long Attribute Values) return a promise rejected with an InvalidModificationError and abort these steps.

4. If this.service.device.gatt.connected is false, return a promise rejected with a NetworkError and abort these steps.

5. Let characteristic be this.[[representedCharacteristic]].

6. If characteristic is null, return a promise rejected with an InvalidStateError and abort these steps.

7. Return a this.service.device.gatt- connection-checking wrapper around a new promise promise and run the following steps in parallel.

   1. Assert: response is one of "required", "never", or "optional".

   2. If the UA is currently using the Bluetooth system, it MAY reject promise with a NetworkError and abort these steps.

      Implementations may be able to avoid this NetworkError, but for now sites need to serialize their use of this API and/or give the user a way to retry failed operations. [Issue #188]

   3. Write bytes to characteristic by performing the following steps:

      If response is "required"

      Use the Write Characteristic Value procedure.

      If response is "never"

      Use the Write Without Response procedure.

      Otherwise

      Use any combination of the sub-procedures in the Characteristic Value Write procedure.

      Handle errors as described in § 6.7 Error handling.

   4. If the previous step returned an error, reject promise with that error and abort these steps.

   5. Queue a task to perform the following steps:

      1. If promise is not in this.service.device.gatt.[[activeAlgorithms]], reject promise with a NetworkError and abort these steps.

      2. Set this.value to a new DataView wrapping a new ArrayBuffer containing bytes.

      3. Resolve promise with undefined.

WriteCharacteristicValue( this=this,
value=value,
response="required")

WriteCharacteristicValue( this=this,
value=value,
response="never")

1. If this.uuid is blocklisted for reads, reject promise with a SecurityError and abort these steps.

2. If this.service.device.gatt.connected is false, reject promise with a NetworkError and abort these steps.

3. Let characteristic be this.[[representedCharacteristic]].

4. If characteristic is null, return a promise rejected with an InvalidStateError and abort these steps.

5. If neither of the Notify or Indicate bits are set in characteristic’s properties, reject promise with a NotSupportedError and abort these steps.

6. If characteristic’s active notification context set contains navigator.bluetooth, resolve promise with this and abort these steps.

7. If the UA is currently using the Bluetooth system, it MAY reject promise with a NetworkError and abort these steps.

   Implementations may be able to avoid this NetworkError, but for now sites need to serialize their use of this API and/or give the user a way to retry failed operations. [Issue #188]

8. If the characteristic has a Client Characteristic Configuration descriptor, use any of the Characteristic Descriptors procedures to ensure that one of the Notification or Indication bits in characteristic’s Client Characteristic Configuration descriptor is set, matching the constraints in characteristic’s properties. The UA SHOULD avoid setting both bits, and MUST deduplicate value-change events if both bits are set. Handle errors as described in § 6.7 Error handling.

   Note: Some devices have characteristics whose properties include the Notify or Indicate bit but that don’t have a Client Characteristic Configuration descriptor. These non-standard-compliant characteristics tend to send notifications or indications unconditionally, so this specification allows applications to simply subscribe to their messages.

9. If the previous step returned an error, reject promise with that error and abort these steps.

10. Add navigator.bluetooth to characteristic’s active notification context set.

11. Resolve promise with this.

1. Let characteristic be this.[[representedCharacteristic]].

2. If characteristic is null, return a promise rejected with an InvalidStateError and abort these steps.

3. If characteristic’s active notification context set contains navigator.bluetooth, remove it.

4. If characteristic’s active notification context set became empty and the characteristic has a Client Characteristic Configuration descriptor, the UA SHOULD use any of the Characteristic Descriptors procedures to clear the Notification and Indication bits in characteristic’s Client Characteristic Configuration descriptor.

5. Queue a task to resolve promise with this.

1. Let propertiesObj be a new instance of BluetoothCharacteristicProperties.

2. Let properties be the characteristic properties of characteristic.

3. Initialize the attributes of propertiesObj from the corresponding bits in properties:

   Attribute	Bit
   broadcast	Broadcast
   read	Read
   writeWithoutResponse	Write Without Response
   write	Write
   notify	Notify
   indicate	Indicate
   authenticatedSignedWrites	Authenticated Signed Writes

4. If the Extended Properties bit of the characteristic properties is not set, initialize propertiesObj.reliableWrite and propertiesObj.writableAuxiliaries to false. Otherwise, run the following steps:

   1. Discover the Characteristic Extended Properties descriptor for characteristic and read its value into extendedProperties. Handle errors as described in § 6.7 Error handling.

      Characteristic Extended Properties isn’t clear whether the extended properties are immutable for a given Characteristic. If they are, the UA should be allowed to cache them.

   2. If the previous step returned an error, reject promise with that error and abort these steps.

   3. Initialize propertiesObj.reliableWrite from the Reliable Write bit of extendedProperties.

   4. Initialize propertiesObj.writableAuxiliaries from the Writable Auxiliaries bit of extendedProperties.

5. Resolve promise with propertiesObj.

1. Let result be a new instance of BluetoothRemoteGATTDescriptor with its [[representedDescriptor]] slot initialized to descriptor.

2. Initialize result.characteristic from the BluetoothRemoteGATTCharacteristic instance representing the Characteristic in which descriptor appears.

3. Initialize result.uuid from the UUID of descriptor.

4. Initialize result.value to null. The UA MAY initialize result.value to a new DataView wrapping a new ArrayBuffer containing the most recently read value from descriptor if this value is available.

5. Resolve promise with result.

1. If this.uuid is blocklisted for reads, return a promise rejected with a SecurityError and abort these steps.

2. If this.characteristic.service.device.gatt.connected is false, return a promise rejected with a NetworkError and abort these steps.

3. Let descriptor be this.[[representedDescriptor]].

4. If descriptor is null, return a promise rejected with an InvalidStateError and abort these steps.

5. Return a this.characteristic.service.device.gatt- connection-checking wrapper around a new promise promise and run the following steps in parallel:

   1. If the UA is currently using the Bluetooth system, it MAY reject promise with a NetworkError and abort these steps.

      Implementations may be able to avoid this NetworkError, but for now sites need to serialize their use of this API and/or give the user a way to retry failed operations. [Issue #188]

   2. Use either the Read Characteristic Descriptors or the Read Long Characteristic Descriptors sub-procedure to retrieve the value of descriptor. Handle errors as described in § 6.7 Error handling.

   3. If the previous step returned an error, reject promise with that error and abort these steps.

   4. Queue a task to perform the following steps:

      1. If promise is not in this.characteristic.service.device.gatt.[[activeAlgorithms]], reject promise with a NetworkError and abort these steps.

      2. Let buffer be an ArrayBuffer holding the retrieved value, and assign new DataView(buffer) to this.value.

      3. Resolve promise with this.value.

1. If this.uuid is blocklisted for writes, return a promise rejected with a SecurityError and abort these steps.

2. Let bytes be a copy of the bytes held by value.

3. If bytes is more than 512 bytes long (the maximum length of an attribute value, per Long Attribute Values) return a promise rejected with an InvalidModificationError and abort these steps.

4. If this.characteristic.service.device.gatt.connected is false, return a promise rejected with a NetworkError and abort these steps.

5. Let descriptor be this.[[representedDescriptor]].

6. If descriptor is null, return a promise rejected with an InvalidStateError and abort these steps.

7. Return a this.characteristic.service.device.gatt- connection-checking wrapper around a new promise promise and run the following steps in parallel.

   1. If the UA is currently using the Bluetooth system, it MAY reject promise with a NetworkError and abort these steps.

      Implementations may be able to avoid this NetworkError, but for now sites need to serialize their use of this API and/or give the user a way to retry failed operations. [Issue #188]

   2. Use either the Write Characteristic Descriptors or the Write Long Characteristic Descriptors sub-procedure to write bytes to descriptor. Handle errors as described in § 6.7 Error handling.

   3. If the previous step returned an error, reject promise with that error and abort these steps.

   4. Queue a task to perform the following steps:

      1. If promise is not in this.characteristic.service.device.gatt.[[activeAlgorithms]], reject promise with a NetworkError and abort these steps.

      2. Set this.value to a new DataView wrapping a new ArrayBuffer containing bytes.

      3. Resolve promise with undefined.

1. If deviceObj.[[representedDevice]] is not the same device as device, abort these steps.

2. If !deviceObj.gatt.connected, abort these steps.

3. Clean up the disconnected device deviceObj.

1. Set deviceObj.gatt.connected to false.

2. Clear deviceObj.gatt.[[activeAlgorithms]].

3. Let context be deviceObj.[[context]].

4. Remove all entries from context.[[attributeInstanceMap]] whose keys are inside deviceObj.[[representedDevice]].

5. For each BluetoothRemoteGATTService service in deviceObj’s realm, set service.[[representedService]] to null.

6. For each BluetoothRemoteGATTCharacteristic characteristic in deviceObj’s realm, do the following sub-steps:

   1. Let notificationContexts be characteristic.[[representedCharacteristic]]’s active notification context set.

   2. Remove context from notificationContexts.

   3. If notificationContexts became empty and there is still an ATT Bearer to deviceObj.[[representedDevice]] and characteristic has a Client Characteristic Configuration descriptor, the UA SHOULD use any of the Characteristic Descriptors procedures to clear the Notification and Indication bits in characteristic’s Client Characteristic Configuration descriptor.

   4. Set characteristic.[[representedCharacteristic]] to null.

7. For each BluetoothRemoteGATTDescriptor descriptor in deviceObj’s realm, set descriptor.[[representedDescriptor]] to null.

8. Fire an event named gattserverdisconnected with its bubbles attribute initialized to true at deviceObj.

   Note: This event is not fired at the BluetoothRemoteGATTServer.

1. For each bluetoothGlobal in the Characteristic’s active notification context set, queue a task on the event loop of the script settings object of bluetoothGlobal to do the following sub-steps:

   1. Let characteristicObject be the BluetoothRemoteGATTCharacteristic in the Bluetooth tree rooted at bluetoothGlobal that represents the Characteristic.

   2. If characteristicObject .service.device.gatt.connected is false, abort these sub-steps.

   3. Set characteristicObject.value to a new DataView wrapping a new ArrayBuffer holding the new value of the Characteristic.

   4. Fire an event named characteristicvaluechanged with its bubbles attribute initialized to true at characteristicObject.

1. If the procedure times out or the ATT Bearer (described in Profile Fundamentals) is absent or terminated for any reason, return a NetworkError from the step and abort these steps.

2. Take the following actions depending on the Error Code:

   Invalid PDU

   Invalid Offset

   Attribute Not Found

   Unsupported Group Type

   These error codes indicate that something unexpected happened at the protocol layer, likely either due to a UA or device bug. Return a NotSupportedError from the step.

   Invalid Handle

   Return an InvalidStateError from the step.

   Invalid Attribute Value Length

   Return an InvalidModificationError from the step.

   Attribute Not Long

   If this error code is received without having used a "Long" sub-procedure, this may indicate a device bug. Return a NotSupportedError from the step.

   Otherwise, retry the step without using a "Long" sub-procedure. If this is impossible due to the length of the value being written, return an InvalidModificationError from the step.

   Insufficient Authentication

   Insufficient Encryption

   Insufficient Encryption Key Size

   The UA SHOULD attempt to increase the security level of the connection. If this attempt fails or the UA doesn’t support any higher security, Return a SecurityError from the step. Otherwise, retry the step at the new higher security level.

   Insufficient Authorization

   Return a SecurityError from the step.

   Application Error

   If the GATT procedure was a Write, return an InvalidModificationError from the step. Otherwise, return a NotSupportedError from the step.

   Read Not Permitted

   Write Not Permitted

   Request Not Supported

   Prepare Queue Full

   Insufficient Resources

   Unlikely Error

   Anything else

   Return a NotSupportedError from the step.