1

Bandwidth Upgrade

kidfromjupiter edited this page 2026-01-23 08:55:39 +05:30

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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