pw_bluetooth_sapphire#

Battle-tested Bluetooth with rock-solid reliability

Unstable C++17 Code Size Impact: 1.5 to 2 mB

Attention

This module is still under construction. There is no public API yet. Please contact the Pigweed team if you are interested in using this module.

The pw_bluetooth_sapphire module provides a dual-mode Bluetooth Host stack that will implement the pw_bluetooth APIs. Sapphire originated as the Fuchsia operating system’s Bluetooth stack and is used in production. The Sapphire Host stack has been migrated into the Pigweed project for use in embedded projects. However, as it was not written in an embedded context, there is a lot of work to be done to optimize memory usage.

Why use Sapphire?

  • Open source, unlike vendor Bluetooth stacks. This makes debugging and fixing issues much easier!

  • Integrated with Pigweed. Logs, asserts, randomness, time, async, strings, and more are all using Pigweed modules.

  • Excellent test coverage, unlike most Bluetooth stacks. This means fewer bugs and greater maintainability.

  • Certified. Sapphire was certified by the Bluetooth SIG after passing all conformance tests.

  • A great API. Coming 2024. See pw_bluetooth.

Fuchsia support#

//pw_bluetooth_sapphire/fuchsia currently contains a stub bt-host to demonstrate building, running, and testing Fuchsia components and packages with the Fuchsia SDK.

It will eventually be filled with the real bt-host component once that’s migrated. See https://fxbug.dev/321267390.

Build the package#

To build the bt-host package, use one of the following commands:

bazel build //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.x64
# OR
bazel build //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.arm64

Start an emulator#

To run an emulator, use one of the following commands:

bazel run @fuchsia_products//:core.x64.emu -- --headless
# OR
bazel run @fuchsia_products//:minimal.arm64.emu -- --headless

Flash a device#

To flash a vim3, use the following command:

bazel run @fuchsia_products//:core.vim3.flash -- --target <device_serial_num>

Run the component#

To run the bt-host component, first provision a Fuchsia target and then use one of the following command:

bazel run //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.x64.component
# OR
bazel run //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.arm64.component

Run unit tests#

To run the bt-host unit tests, first start an emulator and then use the following command:

bazel run //pw_bluetooth_sapphire/fuchsia/bt_host:test_pkg

Stop the emulator#

To stop the running emulator, use the following command:

pw ffx emu stop --all

Add a target test to presubmits#

To add new test packages to presubmits, add the test package targets to //pw_bluetooth_sapphire/fuchsia/BUILD.bazel.

Example:

# pw_bluetooth_sapphire/fuchsia/BUILD.bazel

qemu_tests = [
    "//pw_bluetooth_sapphire/fuchsia/bt_host:integration_test_pkg",
    ...
]

Run Fuchsia presubmit tests#

Presubmits for bt-host are captured in a dedicated separate builder, rather than existing ones such as pigweed-linux-bazel-noenv. These presubmits can be replicated with the following command:

bazel run //pw_bluetooth_sapphire/fuchsia:infra.test_all

Note

You do not need to start an emulator beforehand to to run all tests this way. This test target will automatically provision one before running all tests.

Uploading to CIPD#

Pigweed infrastructure uploads bt-host’s artifacts to fuchsia/prebuilt/bt-host by building bt-host’s top level infra target:

# Ensure all dependencies are built.
bazel build //pw_bluetooth_sapphire/fuchsia:infra

# Get builder manifest file.
bazel build --output_groups=builder_manifest //pw_bluetooth_sapphire/fuchsia:infra

The resulting file contains a cipd_manifests json field which references a sequence of json files specifying the CIPD package path and package file contents.

Roadmap#

  • Support Bazel (In Progress)

  • Support CMake

  • Implement pw_bluetooth APIs

  • Optimize memory footprint

  • Add snoop log capture support

  • Add metrics

  • Add configuration options (LE only, Classic only, etc.)

  • Add CLI for controlling stack over RPC