pw_bluetooth_proxy#

Lightweight proxy for augmenting Bluetooth functionality

Unstable C++17

The pw_bluetooth_proxy module provides a lightweight proxy host that can be placed between a Bluetooth host and Bluetooth controller to add additional functionality or inspection. All without modifying the host or the controller.

An example use case could be offloading some functionality from a main host located on the application processor to instead be handled on the MCU (to reduce power usage).

The proxy acts as a proxy of all host controller interface (HCI) packets between the host and the controller.

pw::bluetooth::proxy::ProxyHost acts as the main coordinator for proxy functionality.

#include "pw_bluetooth_proxy/proxy_host.h"

  // Container creates ProxyHost .
  ProxyHost proxy = ProxyHost(std::move(containerSendToHostFn),
                              std::move(containerSendToControllerFn),
                              2);

  // Container passes H4 packets from host through proxy. Proxy will in turn
  // call the container-provided `containerSendToControllerFn` to pass them on
  // to the controller. Some packets may be modified, added, or removed.
  proxy.HandleH4HciFromHost(h4_span_from_host);

  // Container passes H4 packets from controller through proxy. Proxy will in
  // turn call the container-provided `containerSendToHostFn` to pass them on to
  // the controller. Some packets may be modified, added, or removed.
  proxy.HandleH4HciFromController(h4_span_from_controller);
Get Started

How to set up in your build system

API Reference

Reference information about the API

Roadmap

Upcoming plans

Code size analysis

Understand code footprint and savings potential

Get started#

  1. Add Emboss to your project as described in Emboss.

Bazel isn’t supported yet.

2. Then add $dir_pw_bluetooth_proxy to the deps list in your pw_executable() build target:

pw_executable("...") {
  # ...
  deps = [
    # ...
    "$dir_pw_bluetooth_proxy",
    # ...
  ]
}

2. Then add pw_bluetooth_proxy to the DEPS list in your cmake target:

API reference#

pw::bluetooth::proxy::ProxyHost#

class ProxyHost#

ProxyHost acts as the main coordinator for proxy functionality. After creation, the container then passes packets through the proxy.

Public Functions

ProxyHost(H4HciPacketSendFn &&send_to_host_fn, H4HciPacketSendFn &&send_to_controller_fn, uint16_t le_acl_credits_to_reserve)#

Creates an ProxyHost that will process HCI packets.

Parameters:

  • send_to_host_fn – [in] Callback that will be called when proxy wants to send HCI packet towards the host.

  • send_to_controller_fn – [in] - Callback that will be called when proxy wants to send HCI packet towards the controller.

void HandleH4HciFromHost(H4HciPacket h4_packet)#

Called by container to ask proxy to handle a H4 HCI packet sent from the host side towards the controller side. Proxy will in turn call the send_to_controller_fn provided during construction to pass the packet on to the controller. Some packets may be modified, added, or removed.

void HandleH4HciFromController(H4HciPacket h4_packet)#

Called by container to ask proxy to handle a H4 packet sent from the controller side towards the host side. Proxy will in turn call the send_to_host_fn provided during construction to pass the packet on to the host. Some packets may be modified, added, or removed.

uint16_t GetNumFreeLeAclPackets() const#

Returns the number of available LE ACL send credits for the proxy.

Code size analysis#

Delta when constructing a proxy and just sending packets through.

Label

Segment

Delta

Emboss not configured.

(ALL)

0

Roadmap#

  • ACL flow control

  • Sending GATT notifications

  • CMake support

  • Receiving GATT notifications

  • Taking ownership of a L2CAP channel

  • Bazel support

  • And more…