\nTitle: Web Bluetooth Use Cases\nRepository: WebBluetoothCG/web-bluetooth\nStatus: CG-DRAFT\nED: http://webbluetoothcg.github.io/web-bluetooth/use-cases.html\nShortname: web-bluetooth-use-cases\nLevel: 1\nEditor: See contributors on GitHub, , https://github.com/WebBluetoothCG/web-bluetooth/graphs/contributors\nAbstract: This specification provides a collection of use cases for Bluetooth in the web platform.\n\nGroup: web-bluetooth-cg\n!Participate: Join the W3C Community Group\n!Participate: Fix the text through GitHub\n!Participate: public-web-bluetooth@w3.org (archives)\n!Participate: IRC: #web-bluetooth on W3C's IRC\n\nMax ToC Depth: 2\nMarkup Shorthands: css no, markdown yes\n

\n\n

\n{\n  \"BLUETOOTH42\": {\n    \"href\": \"https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=286439\",\n    \"title\": \"BLUETOOTH SPECIFICATION Version 4.2\",\n    \"publisher\": \"Bluetooth SIG\",\n    \"date\": \"2 December 2014\"\n  }\n}\n

\n\n

Introduction

\n\n

We intend to define an API that uses Bluetooth to discover and communicate with devices.\n This document collects use cases for such an API.\n

\n\n

Use-Cases and Requirements

Use-Cases

\n These are potential use cases for Bluetooth in general,\n but they may not all be supported in\n the initial versions of the Web Bluetooth API.\n\n

Designer of a new device writes a web page to control that device

\n\n

A group making a product like Fitbit, a heart rate monitor, or a singing lightbulb\n can write a web site that users can navigate to and control their device.\n\n

Other devices include:\n

\n Bicycle cadence sensor\n (standard profile)\n
Barcode scanner\n
BT security tags\n
BT plant sensors\n
\n Camera shutter remote\n (this may be a HID device)\n
BT weather station\n
BT kitchen scale\n
BT enabled dive logger\n
Robotic car\n

\n\n

Third party writes a web page to control a device

\n\n

\n Not only original manufacturers should be able to interact with devices.\n It should be possible to write a single page that can pull your heart rate data from\n lots\n of\n different\n heart\n rate\n monitors.\n

\n\n

Bluetooth LE scale begins advertising after the user has opened its web page.

\n\n

A user opens their BTLE scale's website before they step onto their scale.\n They may also be in range of several unrelated Bluetooth devices when they first open the website.\n Stepping onto the scale turns on the Bluetooth transmitter, at which point the website begins pulling data from the scale.\n

\n\n

Device advertised URL opened by user.

\n\n

As described in Physical Web, devices may advertise a URL for the convenience of users who wish to interact.\n Launching an advertised URL loads a website with the device already paired and available for communication.

\n\n

E.G. a user approaches a parking meter and wishes to make a payment.\n They look at their mobile's user interface for nearby device discovery provided by the operating system, browser, or app.\n Upon selecting the parking meter the web browser is launched with the URL provided by the parking meter.\n The website is then able to communicate with the parking meter without requiring further pairing user interface.\n

\n\n

NFC Handover.

\n\n

\n Likely unsupported initially because of the immaturity of [[nfc]].\n\n

A website may already have established a Near Field Communication (NFC) channel with a device via [[nfc]] and then initiate a Bluetooth connection.\n As security for communication with the device has already been established in the NFC channel the transition to Bluetooth communication may proceed without interrupting the user for pairing with the device.

\n\n

E.G. a set of two users wish to play a game together.\n They both load a given website which prompts to pair using NFC by tapping devices together.\n Upon tapping the devices handover the connection from NFC to Bluetooth, enabling playing while sitting in the same room.\n

\n\n

Beacons

\n\n

\n Likely unsupported initially because of\n the privacy risks\n of granting access to a class of devices.\n\n

\n Bluetooth beacons can allow a web page to get precise indoor location or to detect distance to interesting physical objects.\n iBeacon and PayPal Beacons\n are particularly famous examples.\n

\n\n

Audio control

\n\n

\n The process of playing audio to a Bluetooth speaker or\n recording from a Bluetooth microphone should be handled by a combination of the\n navigator.mediaDevices and\n WebAudio APIs.\n Websites shouldn't need to deal with the Bluetooth audio protocol\n in order to simply play or record sound.\n However, speakers and microphones can also expose a metadata channel,\n for example to control hardware volume, balance,\n or even report the position of the user's head.\n\n

\n A user should be able to pair a device to a site in a single interaction,\n rather than needing separate actions for each API the site wants to use.\n The site should be able to associate representations of the same device\n across multiple APIs.\n

\n\n

Requirements

\n\n

The Bluetooth API must allow websites to request access to devices they know how to interact with.

\n\n

The Bluetooth API must allow websites to watch for new devices.

\n\n

The Bluetooth API should be able to pair a site with a device based on previous user action linking the two.

\n\n

\n For example, an OS chooser in which the user selects a particular web site or a previously-consented NFC connection should be sufficient.\n These may only be sufficient to pair for the duration of the session, rather than permanently.\n

\n\n

Security considerations

\n\n Issue(575): See section.\n\n

Privacy considerations

\n\n

Risks

\n\n

Exposes a larger kernel attack surface

\n\n

Bluetooth drivers are complex. Unless a very narrow, well-defined API is exposed to\n websites through Web Bluetooth, this has the potential to expose a large kernel attack\n surface to users. For sandboxed user agents, this attack surface would essentially be\n exposed to the untrusted content, as arbitrary bytes would be controllable by the\n renderer, unless a very narrow and well defined API is used and can be audited\n carefully.

\n\n

For example, compared to the\n WebAudio\n API, Bluetooth drivers are probably handle data in a much more complex way and with more\n complicated abstractions. This leads to a much larger kernel surface area for\n attackers.

\n\n

XSS and CSRF attacks on a device

\n\n

Even if a user only exposes a device to the correct origin, if that origin is not\n correctly protected, they are exposing the device to XSS and CSRF attacks, where an\n attacker could modify, delete, or read data from the device, not just the origin.\n Expressing these risks to users will be a difficult task. This potentially could be\n mitigated by requiring a user interaction for any explicit code to be executed, so in that\n way it couldn't at least happen silently.

\n\n

Currently, the Same Origin Policy basically makes it so even if a site is compromised,\n the damage is limited to that origin (that is to say, your local browsing instance and the\n server you're communicating with). With the addition of Bluetooth or similar permissions,\n all of a sudden, an XSS or CSRF potentially affects devices as well. In some ways, you can\n think of this as an entirely new and privileged domain. Or, alternatively, you could view\n the device as being added to the origin. In either case, communicating that to the user in\n a meaningful way is going to be tough/impossible. This changes the promise user agents\n have been making to users.

\n\n

A malicious website could exploit a vulnerable device

\n\n

Like with [[WebGL]], we should expect that many Bluetooth devices were designed to be accessed only by trusted code.\n Exposing them to the web will expose many more vulnerabilities which could result in anything from persistent misbehavior to complete reprogramming of the device's Bluetooth controller.\n A reprogrammed Bluetooth controller could potentially turn around and attack the user's computer, for example by pretending to be a Bluetooth keyboard.\n

\n\n

A website the user didn't expect gets access to personal data

\n\n

A user visits a news website and is shown articles based on data pulled from their diabetes monitor.\n

\n\n

A website learns the user's location by accessing devices that don't require pairing

\n\n

Some Bluetooth devices don't need to be paired in order for a computer to use them, often because they don't control any information that needs to be private from devices near them.\n Without pairing between the website and the otherwise non-pairing device, casual surfing may leak private data about the user such as location identifying information from non-paired devices.\n\n

Give a more detailed description here involving specific devices.\n

\n\n

A website tracks the user's location by pairing to and accessing an entire class of devices

\n\n

\n A store might offer details about an item using a Bluetooth device attached to a particular display.\n If the site asks for access to this entire class of devices rather than the individual device,\n and members of the device class are scattered around the environment,\n the site is likely to be able to discover the user's location in most cases that the site is opened.\n

\n Giving access in the background (in a Service Worker)\n would give the site the user's location even when it was closed.\n

\n\n

A website tracks a user across cookie reset using Bluetooth device IDs

\n\n

When a website with access to any Bluetooth device finds its cookies reset, it can connect the user back to their previous server data using the immutable, unique Bluetooth device ID.\n

\n\n

Certain active scan requests allow tracking a device's location

\n\n

\n When a BTLE Central or Observer device is scanning for advertising packets and receives one from a Peripheral or Broadcaster, it can send a \"scan request\" (SCAN_REQ) to the Peripheral in order to receive more data. ([[BLUETOOTH42]] 6.B.2.3.2.1)\n The scan request may contain a persistent ID for the Central device, which would allow a malicious Peripheral to report the location of the Central device.\n If a website causes enough active scanning and enough malicious Peripherals are scattered around the environment, this could allow tracking a device's location.\n The \"privacy feature\" ([[BLUETOOTH42]] 3.C.10.7)) makes it more difficult to track devices by rotating their address every T_GAP(private_addr_int) minutes (recommended to be 15 minutes: ([[BLUETOOTH42]] 3.C.17))).\n

\n\n

Security and Privacy Requirements

\n\n

The Bluetooth API must only expose those parts of the general Bluetooth protocol that present an acceptable risk of exploit.

\n\n

The spec should provide guidance to implementers on ways to mitigate exploits further. For example, a mechanism similar to the GPU Blacklist may be appropriate.\n

\n\n

Users must explicitly grant particular websites access to particular devices, even if the device does not intrinsically require pairing.

\n\n

The website-visible ID for any particular device must change when that website's cookies are reset.

\n\n

\n This doesn't completely mitigate the risk,\n since a malicious device can embed a unique ID in any other piece of the protocol it speaks.\n Check with privacy folks if there's anything better we can do.\n

\n\n

Scans must either enable the Bluetooth privacy feature or must use passive scanning until the user has indicated interest in information from the active scan.

\nTitle: Testing Web Bluetooth\nGroup: web-bluetooth-cg\nStatus: CG-DRAFT\nED: https://webbluetoothcg.github.io/web-bluetooth/tests\nShortname: testing-web-bluetooth\nLevel: 1\nEditor: See contributors on GitHub, , https://github.com/WebBluetoothCG/web-bluetooth/graphs/contributors\nAbstract: This document describes functions used in testing the Web Bluetooth API.\nStatus Text:\n  \n    This specification does not yet reflect the consensus of the Web Bluetooth\n    CG. It is presented by the Chromium developers in the hope that other\n    implementers will find it useful. It may be withdrawn if they don't.\n  \n  \n    This document is out of date.  It is a snapshot of the testing API as of\n    late 2015.  A\n    \n    test API redesign\n    is under active design and development as of August 2017.\n    Chromium developers are interested\n    in updating and collaborating on this document when the next tested\n    implementation begins development.\n  
\nMarkup Shorthands: css no, markdown yes\nLink Defaults: html (dfn) trusted event/the body element\nLink Defaults: web-bluetooth (dfn) valid uuid\n

\n{\n  \"BLUETOOTH42\": {\n    \"href\": \"https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=286439\",\n    \"title\": \"BLUETOOTH SPECIFICATION Version 4.2\",\n    \"publisher\": \"Bluetooth SIG\",\n    \"date\": \"2 December 2014\"\n  }\n}\n

\nspec: BLUETOOTH-ASSIGNED\n    type: enum; urlPrefix: https://developer.bluetooth.org/gatt/\n        urlPrefix: characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.\n            text: org.bluetooth.characteristic.gap.device_name; url: gap.device_name.xml#\n        urlPrefix: descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.\n            text: org.bluetooth.descriptor.gatt.characteristic_user_description; url: gatt.characteristic_user_description.xml#\n            text: org.bluetooth.descriptor.gatt.characteristic_extended_properties; url: gatt.characteristic_extended_properties.xml#\n        urlPrefix: services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.\n            text: org.bluetooth.service.battery_service; url: battery_service.xml#\n            text: org.bluetooth.service.glucose; url: glucose.xml#\n            text: org.bluetooth.service.generic_access; url: generic_access.xml#\n            text: org.bluetooth.service.heart_rate; url: heart_rate.xml#\nspec: ui-events; urlPrefix: https://www.w3.org/TR/uievents/#\n    type: event\n        text: keypress; url: event-type-keypress\n    type: attribute\n        for: KeyboardEvent; text: key; url: widl-KeyboardEvent-key\n

\n\n\n\n

Introduction

\n\nThis section is non-normative.\n\nWriting cross-browser tests for the\nWeb Bluetooth API is\ndifficult because it interacts with devices that live outside the browser. This\ndocument describes APIs that aid in this testing, and can be implemented by each\nbrowser to either mock out the external interaction, or to configure an external\ntest device to behave as the test needs.\n\nTests using these functions are currently in web-platform-tests\nand in Chromium's\nrepository.\n\n\n

Security considerations

\n\nIssue(575): See section.\n\n

Privacy considerations

\n\nThese functions MUST NOT be exposed to web content. Only trusted testing\ncode may access them.\n\n\n

Testing interfaces

\n  partial interface Window {\n    readonly attribute TestRunner testRunner;\n    readonly attribute EventSender eventSender;\n  };\n

\n\n\n

testRunner

\n\n

\n  callback BluetoothManualChooserEventsCallback = undefined(sequence<DOMString> events);\n\n  [Exposed=Window, SecureContext]\n  interface TestRunner {\n    undefined setBluetoothMockDataSet(DOMString dataSetName);\n    undefined setBluetoothManualChooser();\n    undefined getBluetoothManualChooserEvents(BluetoothManualChooserEventsCallback callback);\n    undefined sendBluetoothManualChooserEvent(DOMString event, DOMString argument);\n  };\n

\n\n

setBluetoothMockDataSet

\n\nWhen invoked, setBluetoothMockDataSet(dataSetName) MUST replace the\nuser prompt used in {{Bluetooth/requestDevice()}} with one that resolves the\npromise with the first discovered device, or rejects the promise if discovery\ncan't start or times out. Then it must configure the UA's Bluetooth system to\nrespond depending on the {{dataSetName}}:\n\n: \"NotPresentAdapter\"\n:: The UA has no Bluetooth implementation at all.\n: \"NotPoweredAdapter\"\n:: The UA's Bluetooth radio is disabled.\n: \"ScanFilterCheckingAdapter\"\n:: The UA may fail the test unless the test asks the adapter to start a\n Bluetooth scan filtered to the {{org.bluetooth.service.glucose}},\n {{org.bluetooth.service.heart_rate}}, and\n {{org.bluetooth.service.battery_service}} Service UUIDs. The adapter\n discovers a BatteryDevice.\n: \"EmptyAdapter\"\n:: No devices are nearby.\n: \"FailStartDiscoveryAdapter\"\n:: The UA fails to start a scan for devices.\n: \"FailStopDiscoveryAdapter\"\n:: Behaves like a GenericAccessAdapter, but the UA fails to stop the scan for\n devices.\n: \"GlucoseHeartRateAdapter\"\n:: The UA discovers a HeartRateDevice and a GlucoseDevice.\n: \"SecondDiscoveryFindsHeartRateAdapter\"\n:: In the first discovery session, the UA finds no devices. In the second, it\n discovers a HeartRateDevice.\n: \"MissingServiceGenericAccessAdapter\"\n:: The UA discovers a MissingServiceGenericAccessDevice.\n: \"MissingCharacteristicGenericAccessAdapter\"\n:: The UA discovers a MissingCharacteristicGenericAccessDevice.\n: \"MissingDescriptorGenericAccessAdapter\"\n:: The UA discovers a MissingDescriptorGenericAccessDevice.\n: \"GenericAccessAdapter\"\n:: The UA discovers a GenericAccessDevice.\n: \"FailingGATTOperationsAdapter\"\n:: The UA discovers a FailingGATTOperationsDevice.\n\n

BatteryDevice

\n\nHas a MAC address of\n00:00:00:00:00:01, the name \"Battery Device\", and\nadvertises {{org.bluetooth.service.battery_service}}.\n\n

GlucoseDevice

\n\nHas a MAC address of\n00:00:00:00:00:02, the name \"Glucose Device\", and\nadvertises {{org.bluetooth.service.glucose}}.\n\n

HeartRateDevice

\n\nHas a MAC address of\n00:00:00:00:00:03, the name \"Heart Rate Device\", and\nadvertises {{org.bluetooth.service.heart_rate}}.\n\n

MissingServiceGenericAccessDevice

\n\nHas a MAC address of\n00:00:00:00:00:00, the name \"Generic Access\nDevice\", and accepts GATT connections. Its GATT Server is empty.\n\n

MissingCharacteristicGenericAccessDevice

\n\nIn addition to the properties of a MissingServiceGenericAccessDevice, its\nGATT Server contains a primary {{org.bluetooth.service.generic_access}} service.\nThis service contains no characteristics.\n\n

MissingDescriptorGenericAccessDevice

\n\nIn addition to the properties of a\nMissingCharacteristicGenericAccessDevice, its\n{{org.bluetooth.service.generic_access}} service contains the\n{{org.bluetooth.characteristic.gap.device_name}} characteristic. This\ncharacteristic returns \"GenericAccessDevice\" when read, and\nresponds that writes have succeeded (without changing the value read).\n\n

GenericAccessDevice

\n\nIn addition to the properties of a\nMissingDescriptorGenericAccessDevice, its\n{{org.bluetooth.characteristic.gap.device_name}} characteristic contains the following descriptors:\n\n: {{org.bluetooth.descriptor.gatt.characteristic_extended_properties}}\n:: Has the Writable Auxiliaries bit set.\n: {{org.bluetooth.descriptor.gatt.characteristic_user_description}}\n:: Returns \"Device Name\" when read, and responds that writes\n have succeeded (without changing the value read).\n\n

FailingGATTOperationsDevice

\n\nLet errorUUID(unsigned long id) be the\nvalid UUID consisting of id.toString(16) left-padded with\n\"0\"s to 8 characters, and then concatenated with\n\"-97e5-4cd7-b9f1-f5a427670c59\". (These lower 96 bits were generated\nas a type 4 (random) UUID.)\n\nThe\nFailingGATTOperationsDevice has a MAC address of\n00:00:00:00:00:00, the name \"Errors Device\", and\naccepts GATT connections. Its GATT Server contains one service with UUID\n[$errorUUID$](0x100). This service contains 255 characteristics\nwith UUIDs [$errorUUID$](0x101) through\n[$errorUUID$](0x1ff). When read or written, the characteristic with\nUUID [$errorUUID$](which) returns an Error Response\n([[!BLUETOOTH42]] 3.F.3.4.1.1) with an error code of which - 0x100.\n\n\n

setBluetoothManualChooser()

\n\nWhen invoked, {{TestRunner/setBluetoothManualChooser()}} MUST replace the user\nprompt used in {{Bluetooth/requestDevice()}} with a \"manual chooser\"\nthat records events that would otherwise be shown to the user (see\n{{TestRunner/getBluetoothManualChooserEvents()}}), and which can simulate user\ninteraction with the prompt (see\n{{TestRunner/sendBluetoothManualChooserEvent()}}).\n\n

getBluetoothManualChooserEvents(callback)

\n\nWhen invoked, {{TestRunner/getBluetoothManualChooserEvents(callback)}} MUST call `callback` with the\nlist of events that have been recorded by the manual chooser since\n{{TestRunner/getBluetoothManualChooserEvents()}} was last called. Each event is\nencoded as string, as follows:\n\n: The chooser is opened following a request by origin O.\n:: \"chooser-opened(O)\"\n: The Bluetooth adapter is removed from the UA.\n:: \"adapter-removed\"\n: The Bluetooth adapter becomes present but disabled.\n:: \"adapter-disabled\"\n: The Bluetooth adapter becomes present and enabled.\n:: \"adapter-enabled\"\n: The Bluetooth adapter begins scanning for nearby devices.\n:: \"discovering\"\n: The Bluetooth adapter stops scanning for nearby devices.\n:: \"discovery-idle\"\n: The Bluetooth adapter attempts to begin scanning for nearby devices, but fails.\n:: \"discovery-failed-to-start\"\n: A device is added to the user prompt with {{BluetoothDevice/id}}\n device-id and {{BluetoothDevice/name}} device-name.\n:: \"add-device(device-name)=device-id\"\n\n Note: The device-id might not be the device's MAC address. For\n example, MacOS and iOS generate a random ID when testing against physical\n devices.\n\n: The UA discovers that a device with {{BluetoothDevice/id}}\n device-id is no longer nearby.\n:: \"remove-device(device-id)\"\n\n\n

sendBluetoothManualChooserEvent(event, argument)

\n\nWhen invoked, {{TestRunner/sendBluetoothManualChooserEvent(event, argument)}}\nMUST cause the manual chooser to inform the UA that the user has taken an\naction corresponding to the {{event}}:\n\n: \"cancelled\"\n:: The user cancelled the prompt.\n: \"selected\"\n:: The user selected the device with an {{BluetoothDevice/id}} of {{argument}}.\n: \"rescan\"\n:: The user requested another bluetooth scan.\n\n\n

eventSender

\n\n

\n  [Exposed=Window, SecureContext]\n  interface EventSender {\n    undefined keyDown(DOMString code);\n  };\n

\n\nkeyDown(code) must fire an event\nnamed {{keypress}} to the body element, with its\n{{KeyboardEvent/key}} attribute initialized to {{code}}.

\nTitle: Web Bluetooth Scanning\nRepository: WebBluetoothCG/web-bluetooth\nStatus: CG-DRAFT\nED: https://webbluetoothcg.github.io/web-bluetooth/scanning.html\nShortname: web-bluetooth-scanning\nLevel: 1\nEditor: See contributors on GitHub, , https://github.com/WebBluetoothCG/web-bluetooth/graphs/contributors\nAbstract: This document describes an API to scan for nearby Bluetooth Low Energy devices in real time.\n\nGroup: web-bluetooth-cg\n!Participate: Join the W3C Community Group\n!Participate: Fix the text through GitHub\n!Participate: public-web-bluetooth@w3.org (archives)\n!Participate: IRC: #web-bluetooth on W3C's IRC\n\nMarkup Shorthands: css no, markdown yes\n

\n\n

\n{\n  \"BLUETOOTH42\": {\n    \"href\": \"https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=286439\",\n    \"title\": \"BLUETOOTH SPECIFICATION Version 4.2\",\n    \"publisher\": \"Bluetooth SIG\",\n    \"date\": \"2 December 2014\"\n  },\n  \"BLUETOOTH-SUPPLEMENT6\": {\n    \"href\": \"https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=302735\",\n    \"title\": \"Supplement to the Bluetooth Core Specification Version 6\",\n    \"date\": \"14 July 2015\",\n    \"publisher\": \"Bluetooth SIG\"\n  }\n}\n

\n\n

\nspec: ECMAScript; urlPrefix: https://tc39.github.io/ecma262/#\n    type: method\n        text: Array.prototype.map; url: sec-array.prototype.map\n        text: [[OwnPropertyKeys]]; for: Object; url: sec-ordinary-object-internal-methods-and-internal-slots-ownpropertykeys\n    type: interface\n        text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror\n\nspec: WebIDL; urlPrefix: https://heycam.github.io/webidl/#\n    type: dfn\n        text: a copy of the bytes held; url: dfn-get-buffer-source-copy\n\nspec: web-bluetooth; urlPrefix: index.html#\n    type: interface\n        text: BluetoothDevice\n

\nspec:dom\n    type:dfn\n        for:/\n            text:document\nspec: html\n    type: dfn\n        text: allowed to use; for :/\nspec: webidl\n    type: dfn\n        text: resolve\nspec:web-bluetooth\n    type: dfn\n        text: read only arraybuffer\n    type: permission\n        text: \"bluetooth\"\n

\n\n\n\n

Introduction

\n\n This section is non-normative.\n\n

\n Bluetooth Low Energy (BLE)\n allows devices to broadcast advertisements to nearby observers.\n These advertisements can contain small amounts of data\n of a variety of types defined in [[BLUETOOTH-SUPPLEMENT6]].\n

\n\n

\n For example, a beacon might announce that it's next to a particular museum exhibit\n and is advertising with 1mW of power,\n which would let nearby observers know their approximate distance to that exhibit.\n

\n\n

\n This specification extends [[web-bluetooth]] to allow websites to\n receive these advertisements from nearby BLE devices,\n with the user's permission.\n

\n\n

Examples

\n\n

\n To discover what iBeacons are nearby and measure their distance,\n a website could use code like the following:\n

\n        function recordNearbyBeacon(major, minor, pathLossVs1m) { ... }\n        navigator.bluetooth.requestLEScan({\n          filters: [{manufacturerData: {0x004C: {dataPrefix: new Uint8Array([\n            0x02, 0x15, // iBeacon identifier.\n            0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15  // My beacon UUID.\n          ])}}}],\n          keepRepeatedDevices: true\n        }).then(() => {\n          navigator.bluetooth.addEventListener('advertisementreceived', event => {\n            let appleData = event.manufacturerData.get(0x004C);\n            if (appleData.byteLength != 23) {\n              // Isn't an iBeacon.\n              return;\n            }\n            let major = appleData.getUint16(18, false);\n            let minor = appleData.getUint16(20, false);\n            let txPowerAt1m = -appleData.getInt8(22);\n            let pathLossVs1m = txPowerAt1m - event.rssi;\n\n            recordNearbyBeacon(major, minor, pathLossVs1m);\n          });\n        })\n

\n\n

Privacy considerations

\n\n This section is non-normative.\n\n

\n Actively scanning for advertisements\n broadcasts a device address of the scanning device.\n If the UA's Bluetooth system supports the privacy feature,\n this address rotates periodically,\n which prevents remote radios from tracking the user's device.\n However, if the UA's Bluetooth system does not support the privacy feature,\n this address is a stable unique identifier that's difficult to change.\n To mitigate this, UAs should either use passive scanning,\n use the privacy feature in an observer,\n or warn the user that nearby devices will learn the identity of their device.\n

\n\n

\n The ambient advertisements in a user's area are unlikely to directly include GPS coordinates,\n but are likely to contain unique identifiers\n that could be manually correlated with particular physical locations\n or with particular other people.\n Given that, the user needs to give permission\n before a website gets access to nearby advertisements.\n

\n\n

\n If a user has already given a site permission to know their location,\n it might be ok to implicitly grant access to BLE advertisements.\n However, BLE advertisements give away\n strictly less location information than full [[geolocation]] access,\n so UAs should allow users to grant that intermediate level of access.\n

\n\n

\n BLE advertisements are usually fully public,\n since they're broadcast unencrypted on 2.4GHz radio waves.\n However, it's possible that a user would\n have a device broadcast private information in a radio-shielded room.\n This is probably an inappropriate use for BLE advertisements,\n but might argue for requiring explicit permission to scan,\n rather than inferring it from having permission to get a geolocation.\n

\n\n

Security considerations

\n\n This section is non-normative.\n\n

\n Because this API doesn't write anything,\n there are few if any security implications.\n A device in a shielded room might broadcast security-sensitive information,\n but we don't have any actual attack scenarios for that.\n

\n\n

Scanning for BLE advertisements

\n\n

\n    dictionary BluetoothLEScanOptions {\n      sequence<BluetoothLEScanFilterInit> filters;\n      boolean keepRepeatedDevices = false;\n      boolean acceptAllAdvertisements = false;\n    };\n\n    partial interface Bluetooth {\n      [SecureContext]\n      Promise<BluetoothLEScan> requestLEScan(optional BluetoothLEScanOptions options = {});\n    };\n

\n navigator.bluetooth.{{requestLEScan(options)}}\n starts scanning for BLE advertisements,\n asking the user for permission if they haven't yet granted it.\n

\n Because this could show a prompt, it requires a secure context.\n Additionally, UAs are likely to require a transient\n user activation on its [=relevant global object=] when\n {{requestLEScan}} is called.\n

\n Advertising events that match\n a {{BluetoothLEScanFilter}} in an active {{BluetoothLEScan}}\n cause {{advertisementreceived}} events to be dispatched\n to the sending {{BluetoothDevice}}.\n A filter matches if the advertisement includes data equal to each present member.\n Usually, you'll only include one member in each filter.\n

\n Normally scans will discard\n the second and subsequent advertisements from a single device\n to save power.\n If you need to receive them,\n set keepRepeatedDevices to `true`.\n Note that setting {{BluetoothLEScanOptions/keepRepeatedDevices}} to `false`\n doesn't guarantee you won't get redundant events;\n it just allows the UA to save power by omitting them.\n

\n In the rare case that you want to receive every advertisement without filtering them,\n use the acceptAllAdvertisements field.\n

\n\n

\n The requestLEScan(|options|)\n method, when invoked, MUST run the following steps:\n

\n Let |global| be [=this=]'s [=relevant global object=].\n
\n Let |document| be |global|'s [=associated Document=].\n
\n If |document| is not [=allowed to use=] the [=policy-controlled\n feature=] named `\"bluetooth\"`, return [=a promise rejected with=] a\n \"{{SecurityError}}\" {{DOMException}}.\n
\n If |options|.{{BluetoothLEScanOptions/acceptAllAdvertisements}} is\n `true`, and |options|.{{BluetoothLEScanOptions/filters}} is present,\n return [=a promise rejected with=] a \"{{TypeError}}\" {{DOMException}}.\n\n Note: There's no need to include filters if all advertisements are being accepted.\n
\n If |options|.{{BluetoothLEScanOptions/acceptAllAdvertisements}} is\n `false`, and |options|.{{BluetoothLEScanOptions/filters}} is either\n absent or empty, return [=a promise rejected with=] a {{TypeError}}.\n\n Note: An empty set of filters wouldn't return any advertisements.\n
\n Let |filters| be\n {{Array.prototype.map}}.call(|options|.filters,\n filter=>new {{BluetoothLEScanFilter/BluetoothLEScanFilter()|BluetoothLEScanFilter}}(filter))\n if |options|.{{BluetoothLEScanOptions/filters}} is present, or an empty\n {{FrozenArray}} otherwise. If this throws an exception,\n return [=a promise rejected with=] that exception.\n

\n Let |scan| be a [=new=] {{BluetoothLEScan}} instance\n whose fields are initialized as in the following table:\n \n \n \n \n \n \n \n \n \n \n \n \n

Field	Initial value
{{BluetoothLEScan/filters}}	\|filters\|
{{BluetoothLEScan/keepRepeatedDevices}}	\|options\|.{{BluetoothLEScanOptions/keepRepeatedDevices}}
{{BluetoothLEScan/acceptAllAdvertisements}}	\|options\|.{{BluetoothLEScanOptions/acceptAllAdvertisements}}
{{BluetoothLEScan/active}}	`true`

\n Let |promise| be [=a new promise=].\n
\n Run the following steps [=in parallel=].\n
1. \n Request permission to use\n
```
\n              {\n                name: \"bluetooth-le-scan\",\n                filters: options.filters,\n                keepRepeatedDevices: options.keepRepeatedDevices,\n                acceptAllAdvertisements: options.acceptAllAdvertisements,\n              }\n            
```
  \n\n Note: This may require that this algorithm has a transient\n activation on its [=relevant global object=] when triggered.\n
2. \n If the result is \"{{PermissionState/denied}}\", [=queue a global\n task=] on the [=Bluetooth task source=] given |global| to\n [=reject=] |promise| with a \"{{NotAllowedError}}\" {{DOMException}}\n and abort these steps.\n
3. \n Ensure the UA is scanning for BLE advertisements\n in a mode that will receive at least\n all advertisements matching |scan| (in\n addition to any {{[[activeScans]]}} set in the whole UA).\n\n
  \n Find wording that allows the UA to limit its scan to only certain periods of time,\n to save power.\n
  \n
4. \n [=Queue a global task=] on the [=Bluetooth task source=] given\n |global| to run the following steps.\n
  1. \n If the UA failed to start scanning, [=reject=] |promise| with\n one of the following errors, and abort these steps:\n\n
    \n
    The UA doesn't support scanning for advertisements
    \n
    \"{{NotSupportedError}}\" {{DOMException}}
    \n\n
    Bluetooth is turned off
    \n
    \"{{InvalidStateError}}\" {{DOMException}}
    \n\n
    Other reasons
    \n
    \"{{UnknownError}}\" {{DOMException}}
    \n
    \n
  2. \n Let |bluetooth| be |document|'s [=associated Bluetooth=].\n
  3. \n Add |scan| to |bluetooth|.{{[[activeScans]]}}.\n
  4. \n [=Resolve=] |promise| with |scan|.\n
  \n
\n
\n Return |promise|.\n

\n\n

Controlling a BLE scan

\n\n

\n      [Exposed=Window, SecureContext]\n      interface BluetoothDataFilter {\n        constructor(optional BluetoothDataFilterInit init = {});\n        readonly attribute ArrayBuffer dataPrefix;\n        readonly attribute ArrayBuffer mask;\n      };\n\n      [Exposed=Window, SecureContext]\n      interface BluetoothManufacturerDataFilter {\n        constructor(optional object init);\n        readonly maplike<unsigned short, BluetoothDataFilter>;\n      };\n\n      [Exposed=Window, SecureContext]\n      interface BluetoothServiceDataFilter {\n        constructor(optional object init);\n        readonly maplike<UUID, BluetoothDataFilter>;\n      };\n\n      [Exposed=Window, SecureContext]\n      interface BluetoothLEScanFilter {\n        constructor(optional BluetoothLEScanFilterInit init = {});\n        readonly attribute DOMString? name;\n        readonly attribute DOMString? namePrefix;\n        readonly attribute FrozenArray<UUID> services;\n        readonly attribute BluetoothManufacturerDataFilter manufacturerData;\n        readonly attribute BluetoothServiceDataFilter serviceData;\n      };\n\n      [Exposed=Window, SecureContext]\n      interface BluetoothLEScan {\n        readonly attribute FrozenArray<BluetoothLEScanFilter> filters;\n        readonly attribute boolean keepRepeatedDevices;\n        readonly attribute boolean acceptAllAdvertisements;\n\n        readonly attribute boolean active;\n\n        undefined stop();\n      };\n

\n\n

\n {{BluetoothLEScan/stop()|BluetoothLEScan.stop()}}\n stops a previously-requested scan.\n Sites should do this as soon as possible to avoid wasting power.\n

\n\n

\n The BluetoothLEScanFilter(|init|)\n constructor, when invoked MUST perform the following steps:\n

\n Initialize all nullable fields to `null`.\n
\n If no member of |init| is present, throw a {{TypeError}}.\n\n Note: A filter can't implicitly allow all advertisements.\n Use {{BluetoothLEScanOptions/acceptAllAdvertisements}} to explicitly do it.\n
\n Initialize this.{{BluetoothLEScanFilter/manufacturerData}} as\n new BluetoothManufacturerDataFilter(|init|.{{BluetoothLEScanFilterInit/manufacturerData}}).\n
\n Initialize this.{{BluetoothLEScanFilter/serviceData}} as\n new BluetoothServiceDataFilter(|init|.{{BluetoothLEScanFilterInit/serviceData}}).\n
\n Initialize this.{{BluetoothLEScanFilter/services}} as\n {{Array.prototype.map}}.call(|init|.{{BluetoothLEScanFilterInit/services}},\n service=>{{BluetoothUUID/getService()|BluetoothUUID.getService}}(service))\n if |init|.{{BluetoothLEScanFilterInit/services}} is present,\n or an empty {{FrozenArray}} otherwise.\n
\n For each other present member in |init|,\n set `this`'s attribute with a matching identifier to the value of the member.\n
\n If any of the above calls threw an exception,\n propagate that exception from this constructor.\n

\n\n

\n The stop() method, when invoked,\n MUST perform the following steps:\n

Set this.{{BluetoothLEScan/active}} to `false`.
Remove `this` from navigator.bluetooth.{{[[activeScans]]}}.
\n The UA SHOULD reconfigure or stop its BLE scan to save power\n while still receiving any advertisements that\n match any scan\n in any {{[[activeScans]]}} set in the whole UA.\n

\n\n

\n The BluetoothManufacturerDataFilter(|init|)\n constructor, when invoked, MUST perform the following steps:\n

\n If |init| is not present\n or |init|.{{Object/[[OwnPropertyKeys]]}}() is empty,\n then `this` has no map entries.\n Abort these steps.\n
\n Let |canonicalInit| be the `manufacturerData` field of the result of\n canonicalizing {manufacturerData: |init|}.\n If this throws an exception,\n propagate that exception from this constructor and abort these steps.\n
\n `this`'s map entries map from each |key| in\n |canonicalInit|.{{Object/[[OwnPropertyKeys]]}}(),\n
```
\nTitle: Web Bluetooth\nRepository: WebBluetoothCG/web-bluetooth\nStatus: CG-DRAFT\nED: https://webbluetoothcg.github.io/web-bluetooth/\nShortname: web-bluetooth\nLevel: 1\nTranslation: ja https://tkybpp.github.io/web-bluetooth-jp/\nEditor: Reilly Grant 83788, Google LLC https://www.google.com, reillyg@google.com\nEditor: Ovidio Ruiz-Henríquez 106543, Google LLC https://www.google.com, odejesush@google.com\nEditor: See contributors on GitHub, , https://github.com/WebBluetoothCG/web-bluetooth/graphs/contributors\nAbstract: This document describes an API to discover and communicate with devices\nAbstract: over the Bluetooth 4 wireless standard using the Generic Attribute Profile (GATT).\n\nGroup: web-bluetooth-cg\n!Participate: Join the W3C Community Group\n!Participate: Fix the text through GitHub\n!Participate: public-web-bluetooth@w3.org (archives)\n!Participate: IRC: #web-bluetooth on W3C's IRC\n\nMarkup Shorthands: css no, markdown yes\n
```
\n\n
```
\n{\n  \"BLUETOOTH42\": {\n    \"href\": \"https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=286439\",\n    \"title\": \"BLUETOOTH SPECIFICATION Version 4.2\",\n    \"publisher\": \"Bluetooth SIG\",\n    \"date\": \"2 December 2014\"\n  },\n  \"BLUETOOTH-ASSIGNED\": {\n    \"href\": \"https://www.bluetooth.com/specifications/assigned-numbers/\",\n    \"title\": \"Assigned Numbers\",\n    \"status\": \"Living Standard\",\n    \"publisher\": \"Bluetooth SIG\"\n  },\n  \"BLUETOOTH-SUPPLEMENT6\": {\n    \"href\": \"https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=302735\",\n    \"title\": \"Supplement to the Bluetooth Core Specification Version 6\",\n    \"date\": \"14 July 2015\",\n    \"publisher\": \"Bluetooth SIG\"\n  }\n}\n
```
\n\n
```
\nspec: assigned-numbers\n    type: enum; urlPrefix: https://github.com/WebBluetoothCG/registries/\n        urlPrefix: blob/master/gatt_assigned_characteristics.txt\n            text: body_sensor_location; url: #:~:text=body_sensor_location\n            text: gap.appearance; url: #:~:text=gap.appearance\n            text: heart_rate_control_point; url: #:~:text=heart_rate_control_point\n            text: heart_rate_measurement; url: #:~:text=heart_rate_measurement\n            text: ieee_11073-20601_regulatory_certification_data_list; url: #:~:text=ieee_11073-20601_regulatory_certification_data_list\n        urlPrefix: blob/master/gatt_assigned_descriptors.txt\n            text: gatt.characteristic_presentation_format; url: #:~:text=gatt.characteristic_presentation_format\n            text: gatt.client_characteristic_configuration; url: #:~:text=gatt.client_characteristic_configuration\n        urlPrefix: blob/master/gatt_assigned_services.txt\n            text: cycling_power; url: #:~:text=cycling_power\n            text: heart_rate; url: #:~:text=heart_rate\n\nspec: BLUETOOTH-ASSIGNED\n    type: dfn\n        text: Shortened Local Name; url: https://www.bluetooth.com/specifications/assigned-numbers/#:~:text=Generic%20Access%20Profile\n\nspec: ECMAScript; urlPrefix: https://tc39.github.io/ecma262/#\n    type: dfn\n        text: current realm; url: current-realm\n        text: fulfilled; url: sec-promise-objects\n        text: internal slot; url: sec-object-internal-methods-and-internal-slots\n        text: realm; url: sec-code-realms\n    type: method\n        text: Array.prototype.map; url: sec-array.prototype.map\n    type: interface\n        text: Array; url: sec-array-objects\n        text: ArrayBuffer; url: sec-arraybuffer-constructor\n        text: DataView; url: sec-dataview-constructor\n        text: Map; url: sec-map-constructor\n        text: Promise; url:sec-promise-objects\n        text: Set; url: sec-set-objects\n        text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror\n        text: TypedArray; url: sec-typedarray-constructors\n\nspec: fingerprinting-guidance; urlPrefix: https://w3c.github.io/fingerprinting-guidance/#\n    type: dfn\n        text: fingerprinting surface; url: dfn-fingerprinting-surface\n\nspec: html; urlPrefix: https://html.spec.whatwg.org/multipage/browsing-the-web.html#\n    type: dfn\n        text: initializing the Document object; url: initialise-the-document-object\n\nspec: html; urlPrefix: https://html.spec.whatwg.org/multipage/document-sequences.html#\n    type: dfn\n        text: navigable; url: navigable\n\nspec: WebIDL; urlPrefix: https://heycam.github.io/webidl/#\n    type: dfn\n        text: a copy of the bytes held; url: dfn-get-buffer-source-copy\n\nspec: html; urlPrefix: https://html.spec.whatwg.org/multipage/browsing-the-web.html/#\n    type: dfn\n        text: initializing a new Document object; url: dfn-initialise-the-document-object\n\nspec: PAGE-VISIBILITY; urlPrefix: https://www.w3.org/TR/page-visibility-2/#\n    type: dfn\n        text: document visibility state; url: dom-visibilitystate\n\nspec: WEBDRIVER; urlPrefix: https://w3c.github.io/webdriver/\n    type: dfn\n        text: error; url: dfn-error\n        text: local end; url: dfn-local-ends\n        text: invalid element state; url: dfn-invalid-element-state\n\n
```
\n
```
\nspec:dom\n    type:dfn\n        text:children\n        for:/\n            text:document\nspec: fingerprinting-guidance\n    type: dfn\n        text: fingerprinting surface\nspec: html\n    type: dfn\n        text: allowed to use; for :/\n        text: associated navigator; for: /\n        text: browsing context; for: /\n        text: global object; for: /\n        text: navigable; for: /\nspec: webidl\n    type: dfn\n        text: resolve\nspec: webdriver\n    type: dfn\n        text: remote end steps\n    type: dfn\n        text: current browsing context\n\n
```
\n\n\n\n# Introduction # {#introduction}\n\n*This section is non-normative.*\n\nBluetooth is a standard for\nshort-range wireless communication between devices. Bluetooth \"Classic\" (
BR/EDR)\ndefines a set of binary protocols and supports speeds up to about 24Mbps.\nBluetooth 4.0 introduced a new \"Low Energy\" mode known as \"Bluetooth Smart\",\nBLE, or just LE\nwhich is limited to about 1Mbps but allows devices to leave their transmitters\noff most of the time. BLE provides most of its functionality through key/value\npairs provided by the Generic Attribute\nProfile (GATT).\n\nBLE defines multiple roles that devices can play. The Broadcaster and\nObserver roles are for transmitter- and receiver-only applications,\nrespectively. Devices acting in the Peripheral role can receive\nconnections, and devices acting in the Central role can connect to\nPeripheral devices.\n\nA device acting in either the Peripheral or Central role can host\na GATT Server, which exposes a hierarchy of Services,\nCharacteristics, and Descriptors. See [[#information-model]] for\nmore details about this hierarchy. Despite being designed to support BLE\ntransport, the GATT protocol can also run over BR/EDR transport.\n\nThe first version of this specification allows web pages, running on a UA in the\nCentral role, to connect to GATT Servers over either a BR/EDR or\nLE connection. While this specification cites the [[BLUETOOTH42]] specification,\nit intends to also support communication among devices that only implement\nBluetooth 4.0 or 4.1.\n\n## Examples ## {#introduction-examples}\n\n
\nTo discover and retrieve data from a standard heart rate monitor,\na website would use code like the following:\n\n
```
\n  let chosenHeartRateService = null;\n\n  navigator.bluetooth.requestDevice({\n    filters: [{\n      services: ['heart_rate'],\n    }]\n  }).then(device => device.gatt.connect())\n  .then(server => server.getPrimaryService('heart_rate'))\n  .then(service => {\n    chosenHeartRateService = service;\n    return Promise.all([\n      service.getCharacteristic('body_sensor_location')\n        .then(handleBodySensorLocationCharacteristic),\n      service.getCharacteristic('heart_rate_measurement')\n        .then(handleHeartRateMeasurementCharacteristic),\n    ]);\n  });\n\n  function handleBodySensorLocationCharacteristic(characteristic) {\n    if (characteristic === null) {\n      console.log(\"Unknown sensor location.\");\n      return Promise.resolve();\n    }\n    return characteristic.readValue()\n    .then(sensorLocationData => {\n      const sensorLocation = sensorLocationData.getUint8(0);\n      switch (sensorLocation) {\n        case 0: return 'Other';\n        case 1: return 'Chest';\n        case 2: return 'Wrist';\n        case 3: return 'Finger';\n        case 4: return 'Hand';\n        case 5: return 'Ear Lobe';\n        case 6: return 'Foot';\n        default: return 'Unknown';\n      }\n    }).then(location => console.log(location));\n  }\n\n  function handleHeartRateMeasurementCharacteristic(characteristic) {\n    return characteristic.startNotifications()\n    .then(char => {\n      characteristic.addEventListener('characteristicvaluechanged',\n                                      onHeartRateChanged);\n    });\n  }\n\n  function onHeartRateChanged(event) {\n    const characteristic = event.target;\n    console.log(parseHeartRate(characteristic.value));\n  }\n
```
\n\nparseHeartRate() would be defined using the\n\nheart_rate_measurement documentation\nto read the {{DataView}} stored in a {{BluetoothRemoteGATTCharacteristic}}'s\n{{BluetoothRemoteGATTCharacteristic/value}} field.\n\n
```
\n  function parseHeartRate(data) {\n    const flags = data.getUint8(0);\n    const rate16Bits = flags & 0x1;\n    const result = {};\n    let index = 1;\n    if (rate16Bits) {\n      result.heartRate = data.getUint16(index, /*littleEndian=*/true);\n      index += 2;\n    } else {\n      result.heartRate = data.getUint8(index);\n      index += 1;\n    }\n    const contactDetected = flags & 0x2;\n    const contactSensorPresent = flags & 0x4;\n    if (contactSensorPresent) {\n      result.contactDetected = !!contactDetected;\n    }\n    const energyPresent = flags & 0x8;\n    if (energyPresent) {\n      result.energyExpended = data.getUint16(index, /*littleEndian=*/true);\n      index += 2;\n    }\n    const rrIntervalPresent = flags & 0x10;\n    if (rrIntervalPresent) {\n      const rrIntervals = [];\n      for (; index + 1 < data.byteLength; index += 2) {\n        rrIntervals.push(data.getUint16(index, /*littleEndian=*/true));\n      }\n      result.rrIntervals = rrIntervals;\n    }\n    return result;\n  }\n
```
\n\nonHeartRateChanged() might log an object like\n
```
\n  {\n    heartRate: 70,\n    contactDetected: true,\n    energyExpended: 750,     // Meaning 750kJ.\n    rrIntervals: [890, 870]  // Meaning .87s and .85s.\n  }\n
```
\n\nIf the heart rate sensor reports the energyExpended field, the web\napplication can reset its value to 0 by writing to the\n{{heart_rate_control_point}}\ncharacteristic:\n\n
```
\n  function resetEnergyExpended() {\n    if (!chosenHeartRateService) {\n      return Promise.reject(new Error('No heart rate sensor selected yet.'));\n    }\n    return chosenHeartRateService.getCharacteristic('heart_rate_control_point')\n    .then(controlPoint => {\n      const resetEnergyExpended = new Uint8Array([1]);\n      return controlPoint.writeValue(resetEnergyExpended);\n    });\n  }\n
```
\n
\n\n# Security considerations # {#security-and-privacy}\n\nIssue(575): See section.\n\n# Privacy considerations # {#privacy}\n\n## Device access is powerful ## {#device-access-is-powerful}\n\nWhen a website requests access to devices using {{Bluetooth/requestDevice()}},\nit gets the ability to access all GATT services mentioned in the call. The UA\nMUST inform the user what capabilities these services give the website before\nasking which devices to entrust to it. If any services in the list aren't known\nto the UA, the UA MUST assume they give the site complete control over the\ndevice and inform the user of this risk. The UA MUST also allow the user to\ninspect what sites have access to what devices and revoke these pairings.\n\nThe UA MUST NOT allow the user to pair entire classes of devices with a website.\nIt is possible to construct a class of devices for which each individual device\nsends the same Bluetooth-level identifying information. UAs are not required to\nattempt to detect this sort of forgery and MAY let a user pair this\npseudo-device with a website.\n\nTo help ensure that only the entity the user approved for access actually has\naccess, this specification requires that only secure contexts can access\nBluetooth devices.\n\n## Trusted servers can serve malicious code ## {#server-takeovers}\n\n*This section is non-normative.*\n\nEven if the user trusts an origin, that origin's servers or developers could be\ncompromised, or the origin's site could be vulnerable to XSS attacks. Either\ncould lead to users granting malicious code access to valuable devices. Origins\nshould define a Content Security Policy ([[CSP3]]) to reduce the risk of XSS\nattacks, but this doesn't help with compromised servers or developers.\n\nThe ability to retrieve granted devices after a page reload, provided by , makes this risk worse. Instead of\nhaving to get the user to grant access while the site is compromised, the\nattacker can take advantage of previously-granted devices if the user simply\nvisits while the site is compromised. On the other hand, when sites can keep\naccess to devices across page reloads, they don't have to show as many\npermission prompts overall, making it more likely that users will pay attention\nto the prompts they do see.\n\n## Attacks on devices ## {#attacks-on-devices}\n\n*This section is non-normative.*\n\nCommunication from websites can break the security model of some devices, which\nassume they only receive messages from the trusted operating system of a remote\ndevice. Human Interface Devices are a prominent example, where allowing a\nwebsite to communicate would allow that site to log keystrokes. This\nspecification includes a GATT blocklist of such vulnerable services,\ncharacteristics, and descriptors to prevent websites from taking advantage of\nthem.\n\nWe expect that many devices are vulnerable to unexpected data delivered to their\nradio. In the past, these devices had to be exploited one-by-one, but this API\nmakes it plausible to conduct large-scale attacks. This specification takes\nseveral approaches to make such attacks more difficult:\n\n* Pairing individual devices instead of device classes requires at least a user\n action before a device can be exploited.\n\n* Constraining access to GATT, as opposed to generic byte-stream access,\n denies malicious websites access to most parsers on the device.\n\n On the other hand, GATT's Characteristic and Descriptor values\n are still byte arrays, which may be set to lengths and formats the device\n doesn't expect. UAs are encouraged to validate these values when they can.\n\n* This API never exposes Bluetooth addressing, data signing or encryption keys\n (Definition of Keys and Values) to websites. This makes it more\n difficult for a website to predict the bits that will be sent over the\n radio, which blocks packet-in-packet\n injection attacks. Unfortunately, this only works over encrypted links,\n which not all BLE devices are required to support.\n\n* The integration with [[#permissions-policy]] provides protection against unwanted\n access to Bluetooth capabilities, which requires the top-level document to\n explicitly allow a cross-origin iframe to use the API's methods.\n\nUAs can also take further steps to protect their users:\n\n* A web service may collect lists of malicious websites and vulnerable devices.\n UAs can deny malicious websites access to any device and any website access to\n vulnerable devices.\n\n## Bluetooth device identifiers ## {#bluetooth-device-identifiers}\n\n*This section is non-normative.*\n\nEach Bluetooth BR/EDR device has a unique 48-bit MAC address known as the\nBD_ADDR. Each Bluetooth LE device has at least one of a Public Device\nAddress and a Static Device Address. The Public Device Address\nis a MAC address. The Static Device Address may be regenerated on each\nrestart. A BR/EDR/LE device will use the same value for the BD_ADDR and\nthe Public Device Address (specified in the Read BD_ADDR Command).\n\nAn LE device may also have a unique, 128-bit Identity Resolving Key,\nwhich is sent to trusted devices during the bonding process. To avoid leaking a\npersistent identifier, an LE device may scan and advertise using a random\nResolvable or Non-Resolvable Private Address instead of its Static or\nPublic Address. These are regenerated periodically (approximately every 15\nminutes), but a bonded device can check whether one of its stored IRKs\nmatches any given Resolvable Private Address using the Resolvable Private\nAddress Resolution Procedure.\n\nEach Bluetooth device also has a human-readable Bluetooth Device Name.\nThese aren't guaranteed to be unique, but may well be, depending on the device\ntype.\n\n### Identifiers for remote Bluetooth devices ### {#remote-device-identifiers}\n\n*This section is non-normative.*\n\nIf a website can retrieve any of the persistent {\n \"src_file\": \"index.bs\",\n \"type\": \"bikeshed\",\n \"params\": {\n \"force\": 1\n }\n}","url","link_url","/p/_9pg0p4m2afqedoiqw1a","versioned_link_url","/p/_9pg0p4m2afqedoiqw1a/1","yapping","**Analyzing Web Bluetooth Spec**\n\nI'm currently digesting the Bikeshed documentation, focusing on the Web Bluetooth API. I'm prioritizing the functional aspects, as requested. The scanning and use-case sections are helpful in grasping the desired outcome. The testing interfaces will be crucial for validating my work.\n\n\n\n**Developing Functional Examples**\n\nI'm now prioritizing the \"Examples\" section of the main specification document (`index.bs`) to translate the spec into working code. I'm focusing on demonstrating actual Bluetooth interactions, not just presenting the documentation. The example code snippet is a good starting point for building a functional web page. My focus now is understanding how to integrate the API calls into a practical implementation for scanning, connecting, and reading data from a Bluetooth device.\n\n\n**Translating Examples to Code**\n\nHaving thoroughly reviewed the spec, I'm now making concrete progress on translating the provided example code into a functional web page. The goal is a tangible demonstration of Bluetooth device interaction. I've begun to break down the example into logical components for scanning, connection, and data reading. I am prioritizing a simple use case like the heart rate sensor, which will be relatively easy to get started with.\n\n\n**Developing Concrete Implementation**\n\nMy focus has shifted towards the actual implementation details. I'm building the `index.html` structure with a button for initiating the Bluetooth connection and a display area for results. The `script.js` file is where the core Web Bluetooth API interactions will be coded, starting with the heart rate monitor example. I'm also considering the integration of error handling to make it robust. Basic styling is being added in `style.css` for visual clarity and user-friendliness.\n\n\n**Initiating Code Construction**\n\nI'm now fully immersed in the code implementation. The HTML structure is underway, with the necessary buttons and display areas in place. The core logic in `script.js` is shaping up nicely, building upon the heart rate monitor example. I've initiated error handling for robustness and am actively considering how to visually represent the connection and data readings. I've started adding the core functions from the example code to handle connection, sensor reading, and heart rate updates, with an initial focus on the connection flow and sensor location.\n\n\n**Building the Core Functionality**\n\nI've progressed to the fundamental functions, beginning with device discovery using the `requestDevice` method. I'm focusing on the heart rate service and its associated characteristics. Currently, I'm working on integrating the example code into the application's structure to handle device connections, service discovery, and characteristic retrieval.\n\n\n**Developing Fundamental Structure**\n\nI've progressed to the fundamental structure of the HTML page and the initialization of the `script.js` file. The primary goal is to establish a clear user interface with essential elements, like the \"Connect to Heart Rate Monitor\" button and areas for displaying connection status, sensor location, and heart rate readings. Now I am defining the necessary global variables and setting up references to crucial HTML elements, such as buttons and display sections, within the Javascript file, to facilitate interactive communication between the application and the user.\n\n\n**Building the UI Structure**\n\nI'm presently building the `index.html` file, structuring the page with a dedicated connection button, display areas for sensor location and heart rate data, and a log to track Bluetooth interactions. The supporting `script.js` file is coming along nicely, with initial error handling added to ensure a more robust and user-friendly experience.\n\n\n**Implementing Connection Logic**\n\nI've completed the initial HTML structure and started building the necessary functions in `script.js` to handle the Bluetooth connection. I'm focusing on the core connection flow: initiating the device request, establishing the GATT server connection, and discovering the Heart Rate service. The progress includes defining global variables for service and characteristic objects and setting up event listeners for managing the state of connection. Now I am constructing the code responsible for the device request, ensuring all the user's necessary interactions are present.\n\n\n**Building Fundamental UI/UX**\n\nI've progressed to the fundamental structure of the UI elements. Specifically, the \"index.html\" is taking shape with the foundational elements such as a connection button, data display areas for sensor location and heart rate, as well as a log for Bluetooth interactions. The supporting `script.js` file is coming along nicely, with initial error handling added to ensure a more robust and user-friendly experience.\n\n\n**Developing UI/UX Integration**\n\nI've progressed to the fundamental structure of the UI elements. Specifically, the \"index.html\" is taking shape with the foundational elements such as a connection button, data display areas for sensor location and heart rate, as well as a log for Bluetooth interactions. The supporting `script.js` file is coming along nicely, with initial error handling added to ensure a more robust and user-friendly experience.\n\n\n**Building Connection and UI**\n\nI'm presently building the `index.html` file, structuring the page with a dedicated connection button, display areas for sensor location and heart rate data, and a log to track Bluetooth interactions. The supporting `script.js` file is coming along nicely, with initial error handling added to ensure a more robust and user-friendly experience. Now I have added the essential CSS styles as well as the initial `script.js` content.\n\n\n**Constructing the Core Functionality**\n\nI'm making progress on the core functionality, focusing on integrating the example code for device connections, service discovery, and data retrieval. The focus is now on connecting to the service using the Bluetooth API. I'm actively working on the integration of the example code into the application's structure.\n\n\n**Building Fundamental Functionality**\n\nI'm presently building the `index.html` file, structuring the page with a dedicated connection button, display areas for sensor location and heart rate data, and a log to track Bluetooth interactions. The supporting `script.js` file is coming along nicely, with initial error handling added to ensure a more robust and user-friendly experience. Now I am constructing the code responsible for the device request, ensuring all the user's necessary interactions are present.\n\n\n**Building the Functional Core**\n\nI'm presently building the functional core of the application, focusing on the core logic and error handling. I'm building on the example code from the Web Bluetooth specification (`index.bs`). Now, the connection flow has been coded. The focus is on integrating the example code into the application's structure.\n\n\n**Implementing UI and Connection**\n\nI've crafted `index.html` and `style.css` for a functional UI, and `script.js` now houses core Bluetooth connection functions. It includes device discovery and characteristic retrieval for the heart rate service. The focus is on robust connection handling, with detailed status updates and logging. I've initiated error handling for resilience. The connection logic handles GATT server connection and Heart Rate service retrieval. Now, I'm constructing the code responsible for the device request, ensuring all the user's necessary interactions are present.\n\n\n**Developing Fundamental Implementation**\n\nMy focus has shifted to the `index.html` structure. It now has the necessary UI elements. I've also added basic styling and the initial `script.js` content. It contains event handlers, connection logic, and a foundation for updating UI and managing Bluetooth connections. The basic logging function is fully integrated, which makes debugging much easier.\n\n\n\n**Developing Full Functionality**\n\nI'm presently building the full functionality of the UI and connection functions, focusing on integrating example code for device connections, service discovery, and characteristic retrieval. The main effort is now constructing the function `resetEnergyExpended()` to set it up, along with the logic for the \"Reset Energy Expended\" button, and building an efficient and intuitive UI to improve user interaction.\n\n\n**Implementing Bluetooth Functionality**\n\nI've crafted a functional web page, with UI elements in `index.html` and core Bluetooth logic within `script.js`. The page includes connection, sensor display, and a log, with the `script.js` file now including all necessary features and functions, and error management is implemented. I've successfully written a script to implement Bluetooth and link the UI together.\n\n\n**Implementing Bluetooth Connection**\n\nI've completed the initial structure of the Web Bluetooth application, ensuring compatibility with the Web Bluetooth API. I've designed the user interface, incorporating essential elements for a smooth user experience. The `script.js` file now includes the core Bluetooth logic, setting the foundation for future functionalities. The fundamental `index.html` structure and the initial `script.js` are ready for further development.\n\n\n**Implementing Robust Connection Flow**\n\nMy recent efforts have focused on enhancing the connection flow for the Web Bluetooth application, specifically within `script.js`. I've added comprehensive error handling throughout the connection process. This includes handling potential issues during device discovery, GATT server connection, service discovery, and characteristic retrieval, offering a more resilient user experience. The logging mechanism has been optimized to provide detailed status updates and error messages.\n\n\n**Implementing Complete Functionality**\n\nI'm now fully focused on error management and ensuring a smooth user experience. This involves robust connection handling and detailed status updates. UI refinements and improved logging will enhance usability. I am now focused on a successful demo, from start to finish. I am also implementing the function and logic to write \"1\" to reset the `Heart Rate Control Point` characteristic for the `Reset Energy Expended` button.\n\n\n\nThe user wants a functional web page that demonstrates Bluetooth capabilities. I will create a simple web application that connects to a Heart Rate Monitor (HRM) using the Web Bluetooth API, displays its status, sensor location, live heart rate, and energy expended, with an option to reset the energy expended value.\n\nThis involves:\n1. **`index.html`**: The main HTML structure for the UI, including buttons and display areas.\n2. **`style.css`**: Basic styling for a user-friendly interface.\n3. **`script.js`**: The JavaScript code that implements the Web Bluetooth API calls based on the provided specifications and examples, handling device discovery, connection, service/characteristic access, notifications, and error handling.\n\nThis solution focuses on the Heart Rate Monitor example from the `index.bs` specification, as it provides a clear, interactive use case for Web Bluetooth.\n\n**Note on \"JS libraries from a CDN and an import map\":** The Web Bluetooth API is a native browser API and does not require external JavaScript libraries for its core functionality. Therefore, I have not included any CDN-based libraries or import maps, as they are not necessary for this specific implementation.\n\nindex.html\n\n```index.html\n```\n\nstyle.css\n```style.css\n```\n\nscript.js\n```script.js\n```","page_description","This page provides a demonstration of connecting to and reading data from a Bluetooth Low Energy (BLE) Heart Rate Monitor using the Web Bluetooth API. It…","cursor","eyJpZCI6Il85cGcwcDRtMmFmcWVkb2lxdzFhIn0","token","included",[],"about",{"_185":-5},"parent","routes/browser/layout","actionData","errors"]