Skip to content

Mediums

Jump to bottom
Lasan Mahaliyana edited this page Feb 4, 2026 · 4 revisions

This page summarizes each medium implementation, responsibilities, and where to find the code.

Common pattern

  • Each medium exposes these responsibilities: advertise, scan/discover, accept incoming connections (server socket), connect (client socket), and provide credentials if needed for BWU.
  • Mediums live under connections/implementation/mediums/ and call into platform-specific wrappers in internal/platform/.

List of major mediums

  • Bluetooth Classic

    • Files: connections/implementation/mediums/bluetooth_classic.*
    • Uses platform BluetoothAdapter/BluetoothClassicMedium wrappers.
    • Supports discoverability (device name + scan mode), scanning, accept loops, and client Connect.

  • BLE (Bluetooth Low Energy)

    • Files: connections/implementation/mediums/ble.*, ble_v2.*
    • Supports advertising (legacy/extended), scanning, peripheral/server accept loops, and connecting to peripherals.
    • Linux caveats: BLE fast advertising (Android-specific) vs extended advertising on Linux.

  • Wi‑Fi LAN

    • Files: connections/implementation/mediums/wifi_lan.*
    • Uses mDNS / NsdServiceInfo for discovery and advertises service info.
    • Accepts TCP-like sockets (WifiLanSocket) and can connect by IP+port; used for high-bandwidth data.
    • Supports multiplex sockets for combining logical channels.

  • Wi‑Fi Hotspot (SoftAP)

    • Files: connections/implementation/mediums/wifi_hotspot.*
    • Can start a SoftAP, provide SSID/password and accept incoming connections on a hotspot interface; often used as a BWU path.

  • Wi‑Fi Direct

    • Files: connections/implementation/mediums/wifi_direct.*
    • Uses platform Wi‑Fi Direct APIs (Group Owner, Group Client) to create P2P connections and accept sockets.

  • WebRTC

    • Files: connections/implementation/mediums/webrtc/* and connections/implementation/mediums/webrtc.h
    • Uses a signaling messenger (Tachyon / WebRtcSignalingMessenger) to exchange offers/answers/candidates; creates a data channel socket for upgrade or direct data.

  • AWDL (Apple Wireless Direct Link)

    • Files: connections/implementation/mediums/awdl.*
    • Apple-specific medium used on macOS/iOS; exposed when platform supports AWDL.

  • Multiplex layer

    • Files: connections/implementation/mediums/multiplex/*
    • Provides logical multiplexing on top of physical sockets when enabled by flags.

Where BWU handlers live

  • connections/implementation/*_bwu_handler.h implement per-medium BWU logic (e.g. wifi_lan_bwu_handler.h, webrtc_bwu_handler.h, bluetooth_bwu_handler.h).

Platform support notes

  • See nearby_latest/README.md for a per-platform capabilities table (Android, ChromeOS, Windows, iOS/macOS, Linux).

References in code

  • connections/implementation/mediums/* and internal/platform/* (platform adapters)

Honorable mentions

Wi‑Fi Aware (Wi‑Fi NAN)

I can't really find any implementations on this. BUT it should be implementable. Since both android and linux uses the same wpa_supplicant under the hood and wpa_supplicant implements wifi aware.

  • Code locations (protocol & error enums, frame mappings):
    • proto/connections_enums.proto (Medium enum includes WIFI_AWARE)
    • proto/errorcode/error_code_enums.proto (Wi‑Fi Aware error/result codes)
    • connections/implementation/proto/offline_wire_formats.proto and connections/implementation/offline_frames.cc (UpgradePathInfo/ConnectionRequestFrame include WIFI_AWARE)
    • connections/implementation/service_controller_router.cc (GetMediumQuality returns high for WIFI_AWARE)
    • Compiled protos under compiled_proto/* reference WIFI_AWARE.
  • Notes:
    • The repository contains protocol-level support (enums, wire formats, and error codes) for WIFI_AWARE and BWU upgrade paths, but no medium implementation file like connections/implementation/mediums/wifi_aware.* or platform adapters under internal/platform/implementation/* in this tree.
    • On Android, Wi‑Fi Aware refers to the Wi‑Fi NAN APIs (publish/subscribe, attach/peer discovery). The connections layer supports the protocol frames and error codes but requires platform glue (not present here) to provide sockets and lifecycle management.

BLE L2CAP (LE Connection-Oriented Channels)

Has some quirks with requiring pairing/bonding with linux. Doesn't really suit the 'it just works' paradigm when you need to pair each time you send a file does it?

  • Code locations:
    • connections/implementation/ble_l2cap_endpoint_channel.h / .cc (BleL2capEndpointChannel wraps platform L2CAP sockets into an EndpointChannel)
    • connections/implementation/mediums/ble_v2/ble_l2cap_packet.* and connections/implementation/mediums/ble_v2.cc (L2CAP packet handling and BLE v2 integration)
    • internal/platform/ble_v2.h (public BleV2 wrappers: BleL2capSocket, BleL2capServerSocket)
    • internal/platform/implementation/linux/ble_l2cap_socket.* and internal/platform/implementation/linux/ble_l2cap_server_socket.* (Linux platform impl)
    • Apple counterparts: internal/platform/implementation/apple/ble_l2cap_socket.mm and server socket variants
    • Feature flag: connections/implementation/flags/nearby_connections_feature_flags.h (kEnableBleL2cap)
  • Notes:
    • L2CAP CoC is modelled as an EndpointChannel that uses a PSM (protocol service multiplexer) when creating server sockets or connecting.
    • Although the platform layer exposes lower-security options, Linux/BlueZ and kernel configurations often require pairing/bonding for L2CAP CoC.
    • Interop note (anecdata): L2CAP works fine Linux<->Linux, but Linux<->Android has not worked for me so far. My current assumption is that the Android side relies on a closed-source/privileged stack (or a higher-level protocol layered on top) that isn't directly compatible with the raw sockets approach on Linux. I could reverse engineer this, but it's not a priority right now.

Clone this wiki locally