Skip to content

Bandwidth Upgrade

Jump to bottom
kidfromjupiter edited this page Jan 23, 2026 · 1 revision

This document summarizes how Nearby Connections negotiates and performs bandwidth upgrades (e.g. Bluetooth -> Wi‑Fi).

Protocol sequence (from connections/implementation/bwu_manager.h):

  • Initiator sets up an upgrade path and sends BANDWIDTH_UPGRADE_NEGOTIATION.UPGRADE_PATH_AVAILABLE to the Responder over the prior EndpointChannel.
  • Responder joins the upgrade path, sends (possibly without encryption) BANDWIDTH_UPGRADE_NEGOTIATION.CLIENT_INTRODUCTION over the newly-established EndpointChannel, and sends BANDWIDTH_UPGRADE_NEGOTIATION.LAST_WRITE_TO_PRIOR_CHANNEL over the prior EndpointChannel.
  • Initiator receives CLIENT_INTRODUCTION on the new EndpointChannel and replies with LAST_WRITE_TO_PRIOR_CHANNEL on the prior channel.
  • Both sides wait to receive LAST_WRITE_TO_PRIOR_CHANNEL from the other, then each sends SAFE_TO_CLOSE_PRIOR_CHANNEL to the other.
  • After exchanging SAFE_TO_CLOSE_PRIOR_CHANNEL messages, both sides close the prior EndpointChannel and continue on the upgraded channel.

Key components

  • BwuManager (connections/implementation/bwu_manager.*)

    • Picks candidate upgrade mediums (using Medium selection rules and feature flags).
    • Tracks in-progress upgrades, implements retry/backoff, and records analytics for upgrade results.
    • Processes negotiation frames (UPGRADE_PATH_AVAILABLE, CLIENT_INTRODUCTION, LAST_WRITE_TO_PRIOR_CHANNEL, SAFE_TO_CLOSE_PRIOR_CHANNEL).
    • Holds temporary previous_endpoint_channels_ until it's safe to close them.

  • BwuHandler / BaseBwuHandler (connections/implementation/base_bwu_handler.h and the concrete handlers)

    • Per-medium handler responsible for: initializing upgraded medium, producing upgrade path info (e.g. SSID/password/port for SoftAP), accepting incoming upgraded connections, and reverting initiator state on failure.
    • Concrete handlers include: BluetoothBwuHandler, WebrtcBwuHandler, WifiLanBwuHandler, WifiHotspotBwuHandler, WifiDirectBwuHandler, AwdlBwuHandler (see connections/implementation/*_bwu_handler.h).

  • EndpointChannelManager

    • ReplaceChannelForEndpoint() performs the channel swap and may transfer the encryption context to the new channel (see endpoint_channel_manager.*).

Notable details

  • Feature flags control behavior (e.g. support_multiple_bwu_mediums, dynamic role switching).
  • BWU can be retried with exponential backoff; BwuManager keeps retry alarms and per-endpoint retry state.
  • Safe-to-disconnect semantics and "last write"/"safe to close" handshake ensure no data is lost while switching channels.

References in code

  • connections/implementation/bwu_manager.h, bwu_manager.cc
  • connections/implementation/base_bwu_handler.h
  • Concrete handlers in connections/implementation/*_bwu_handler.h

Clone this wiki locally