When it comes up
A fast link comes up only when your app asks for it. The engine never brings one up on discovery: on iOS every join shows a system prompt and takes the phone off its own Wi-Fi, so whether a transfer is worth that is the app’s decision.requestFastLink(peerId) is accepted when all of these hold:
- the peer has a confirmed 1:1 session with this device and a live Bluetooth LE link to it;
- the peer runs v0.34.0 or later, so its key package advertises fast-link support;
- no peer stream already reaches the peer, for example over a shared home network;
- this device can host or join, and holds no link with another peer. A device holds one link at a time.
Platform support
So a link needs an Android 10+ device on at least one side: an Android phone with an iPhone, or two Android phones. Two iPhones cannot link. It is available in the React Native package and the Flutter plugin (
MeshSdk.requestFastLink({'peerId': peer}) and MeshSdk.closeFastLink({'peerId': peer})), with the Wi-Fi slot (transports.wifiDirect) enabled. Over the FFI the engine methods are request_fast_link and close_fast_link; a custom platform declares what it can do with wifi_direct_set_fast_link_roles, and one that declares nothing is never asked to host or join.
What your app does
- Enable the Wi-Fi slot:
transports: { wifiDirect: { enabled: true } }. - Set up the permissions below.
- Register a
fast_link_changedlistener, then callrequestFastLink(peerId)for a peer you are about to send something large to. - Start the transfer after
fast_link_changedreports stateupfor that peer. A file transfer keeps the carrier it started on, so one started over Bluetooth before the link came up stays on Bluetooth. - Call
closeFastLink(peerId)when you are done, or let the link end on its own.
requestFastLink resolves with a link id as soon as the first step is taken; the outcome arrives as fast_link_changed events. Match them by peer, not by that id: when the host answers with a network it already had, the link takes the host’s id. A rejected or closed link leaves Bluetooth LE as it was, so the app can still send over it.
Events
fast_link_changed carries peer_id, link_id, role (host or join), state and, on closed, reason. It never carries a network name or a passphrase.
Reasons include
declined (the joiner’s user said no, or the app is set to requestedOnly), idle, lost, expired, background, busy, cannot_host, cannot_join and superseded (another connection, such as a shared home network, reached the peer first and carries its traffic). Treat an unknown reason as a failure. Traffic moving onto the link is reported by transport_switched.
When a link ends
The engine ends a link when its offer expires unused (120 s), when the stream over it is lost, after 60 s with nothing large carried (a body of 16 KiB or more) and no transfer to the peer under way, oncloseFastLink from either side, and when the app pauses or stops the engine. On iOS the link ends when the app leaves the foreground. A file transfer that was on the link when it ended fails at once with media_send_failed; send it again and it goes over what remains.
Permissions and entitlements
iOS shows ““App” Wants to Join Wi‑Fi Network “DIRECT-…”?” on every join.
Choose how far your app takes part
wifiDirect.fastLink decides whether a peer’s app can start a link with yours:
wifiDirect.autoAccept) share the one group a device can own: while either holds it, the other is refused.
Security
The network name isDIRECT- plus random characters, with nothing derived from the app, the user or the device, and the passphrase is 128 random bits made fresh for every link. The offer travels once over the live Bluetooth link inside the confirmed MLS session, never through the outbox or a relay. The host admits only the peer it invited, and the joiner’s stream must prove the host’s address. The network’s name and existence are visible to anyone in radio range while it is up; see residual risk R34 in the threat model.
Reference
- Fast link state machine: every state, timer and frame.
- Mobile permissions, fast link.
requestFastLinkandcloseFastLinkin the generated reference.

