Peripheral Makers: Building Swift Pair Peripherals

02/02/2018

NOTE: We now have official MSDN documentation online, which we recommend you use to build against. This is where we will update you if we need to add or change anything for clarity.

Link to Official MSDN Documentation

This post will detail the requirements for a Bluetooth peripheral to support Swift Pair on Windows. There will be additional details on MSDN coupled with the next release of Windows 10.

A core pillar while we built this feature was to keep it as simple and easy to implement for others in the ecosystem. We’ve identified two sets of requirements needed to ensure your peripheral works well with Windows. One set is for the peripheral’s behavior, and another for the structure and values in a Microsoft defined vendor section. By meeting these requirements all peripheral makers should now be able to try this feature out using this latest Insider build.

Peripheral Behavior

Adhering to the core principle of making pairing easy and predictable for our users, we have identified the following set of peripheral behaviors.

Required

Support Bluetooth Low Energy (LE)
Add one of the vendor defined sections (Fig 1-3) to your main advertising packet while in pairing mode
Stop advertising the defined vendor section 30 seconds before you exit pairing mode
Remove the vendor section more than 30 seconds before the exiting pairing mode
- We do not want users to try to pair to peripherals that are no longer available
- The peripheral can continue to advertise without the vendor defined section afterwards
For peripherals that support multiple pairings, if there are no available pairings when Windows attempts to pair, remove the pairing that has not been connected to for the longest amount of time
- This is to keep the experience predictable for our users
For users to easily identify your peripheral, you must include either a name of the peripheral OR an icon for the type of peripheral in the same advertisement as the vendor section. This is required as we will not actively scan for both power and privacy concerns. You can implement this in the following ways:
- Peripheral Name:
  - It is recommended to use the Bluetooth friendly name section
  - If this is not possible we provide a fallback “Display Name” mechanism in the vendor section (Fig 1-3)
    - This field is uncapped in size, so all available space may be used
    - This name will show in all markets, so it is recommended to use model numbers, trademarks, or brands here
- Peripheral appearance:
  - For Bluetooth LE only peripherals: include the Bluetooth LE appearance section in the same advertisement that contains the vendor section
  - For Dual Mode peripherals, The vendor defined section already includes the 3 bytes the Bluetooth SIG defined for the Major and Minor Class of Device (CoD)
For Dual Mode peripherals, where you intend to pair over both Bluetooth LE and BR/EDR, support Secure Connections over both protocols
- This allows a peripheral to pair over both, by first pairing over Bluetooth LE
For peripherals that beacon without user consent, support Bluetooth LE privacy
- It is recommended to suspend rotating the Bluetooth LE address during the pairing session due to the privacy efforts associated with Bluetooth LE Privacy
- Each change to the public address will appear as a new Swift Pair request

Enter pairing mode on the very first power on
Do not beacon for this experience indefinitely or for an extended period before exiting paring mode
Beacon/advertise at a consistent rate while in a Swift Pair session. We've found every 100ms works best.
Dual mode peripherals should consider supporting pairing over both Bluetooth LE and BR/EDR using Secure Connections to save payload space

Payload Structures

Bluetooth LE is required, but that does not mean audio and other BR/EDR peripherals can’t get in on the action. We have 3 payloads which will trigger the seamless pairing experience; one for solely Bluetooth LE peripherals, and then two for dual mode peripherals. The dual mode payloads help address whether the peripheral in question will pair over both Bluetooth LE and BR/EDR using secure connections or is leveraging this Bluetooth LE advertisement to pair over only BR/EDR.

[caption id="attachment_266" align="alignnone" width="641"] Figure 1: Pairing over Bluetooth LE only[/caption]

[caption id="attachment_255" align="alignnone" width="836"] Figure 2: Paring over Bluetooth LE and BR/EDR with Secure Connections[/caption]

[caption id="attachment_235" align="alignnone" width="824"] Figure 3: Pairing over BR/EDR only, using Bluetooth LE for discovery[/caption]

Section Header

This is a Bluetooth SIG defined vendor section
The header consists of the Length, Vendor defined flag, and Microsoft Vendor ID 0x0006

Payload Content

Microsoft Beacon ID & Sub Scenario
- The Microsoft Beacon ID helps identify that the advertisement is for this experience
- The sub scenario helps detail how the peripheral will pair, each ID has a unique payload
Reserved RSSI Byte
- We’re asking to reserve this byte and set it to 0x80. This will help maintain forwards and backwards compatibility
- In future releases we will provide guidance on how to provide RSSI calibration values for improved proximity detection
Display Name
- As mentioned above, this variable size field can allow payload constrained peripherals to display the name of the peripheral on the notification
- This name will not be localized and will need to work for all markets

Classic BR/EDR Pairings

For BR/EDR peripheral icon appearance
- It is the same as the Major and Minor Class of Device(CoD) mapping provided by the Bluetooth SIG
BR/EDR Address
- If a peripheral will pair over BR/EDR only, the BR/EDR address must be included in the main advertising packet
  - Must be in little endian format
- Supporting Secure Connections and pairing over both Bluetooth LE and BR/EDR removes this requirement

Frequently Asked Questions

How does Windows detect if a peripheral is in range?

In addition to the new experience, we've also added a Bluetooth proximity service that reads the signal strength from a peripheral to determine its proximity to Windows. When determined to be close by, the notification will show.

Since the signal strength varies between hosts and peripherals, we are always looking to increase the precision of our proximity service to make our proximity detection more predictable. This is what the reserved Received Signal Strength (RSSI) byte in the payload will be used for.

How does Windows listen for these peripherals without draining power?

The pattern Windows is looking for will be offloaded to the radio via Hardware Offload. The offloaded pattern will listen for a match to the vendor section without waking Windows up or active scanning. If the radio does not support Hardware Offload, then the feature is not supported, and this is represented in Settings by not having the “Connect to certain Bluetooth devices quickly”.

How does Windows detect and display Bluetooth peripheral information?

The name and the type of peripheral need to be in the same advertisement that has the vendor section. We will not active scan for this feature, and all peripheral info must be included in this single advertisement. If friendly name section can’t fit in this advertisement, we provide the fallback mechanism at the end of the payload to have the peripheral name show.

There are competing implementations of this feature for other platforms, are there long-term plans to interop with them?

Currently, this is specific to Windows, however we are looking to standardize this functionality across all platforms in the future with the Bluetooth SIG.

Contact Us

If you’d like to take advantage of this great new feature and make a peripheral that supports Swift Pair, please reach out to a Microsoft representative, or leave a comment here and we'll get back to you. We would love to work together as we evolve this experience.