Meshtastic-Android/main/docs/user/connections.html

<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Connections</title>
  <link rel="stylesheet" href="../styles/docs.css">
</head>
<body data-page="connections" data-locale="en">
<pre class="markdown-content"># Connections

Meshtastic supports multiple transport methods to communicate between your phone or desktop and a radio.

## Bluetooth (BLE)

Bluetooth Low Energy is the default and most common connection method on Android.

### Pairing a Radio

1. Ensure your Meshtastic radio is powered on and in pairing mode.
2. Open the app and navigate to the **Connect** tab.
3. Tap **Scan for Bluetooth devices** — nearby Meshtastic radios will appear.
4. Select your radio from the list.
5. Accept the Bluetooth pairing prompt if shown.

![Scanning for Bluetooth devices, with a discovered radio in the list](../../assets/screenshots/connections_bluetooth_scan.png)

Use the transport selector — a segmented button row below the connection card — to switch between the Bluetooth, Network, and USB transports (one is active at a time):

![Connections screen with the transport selector showing Bluetooth, Network, and USB](../../assets/screenshots/connections_transport_filters.png)

&gt; 💡 **Tip:** If your radio doesn't appear, check that it isn't already connected to another phone, or out of range.

The screen names anything on the app's side that is blocking a scan, with the fix attached:

 What you see | What it means |
---|---|
 A card asking for **Nearby devices** | The permission has not been granted. **Grant permission** requests it; once Android stops prompting, the button becomes **Open settings**. |
 **Bluetooth is off** | The adapter is disabled — the card opens Bluetooth settings. |
 **Bluetooth scanning also needs location services** | Android 11 and older only: the permission is held but the system location toggle is off. |
 No card, empty list | Nothing on this side is blocking the scan — the radio is out of range, off, or already connected elsewhere. |

Tapping **Scan** after you have declined the permission once explains what it is for before asking again, and lets you decline again without being cornered.

### Connection Status

 Icon | State | Description |
------|-------|-------------|
 🟢 | Connected | Active radio link established |
 🟡 | Connecting | Handshake in progress |
 🔴 | Disconnected | No active connection; the app keeps trying to reconnect |
 ⚪ | Device sleeping | The radio is in light sleep — the app is waiting for it to wake and reconnect, not failing |

These are the four states the app models. "Device sleeping" is normal on power-saving configurations and needs no action.

When connecting, a status indicator shows the current connection state — tap **Stop Connecting** to abandon the attempt:

![Connecting status](../../assets/screenshots/connections_connecting.png)

If no devices are found, the app shows an empty state with instructions:

![No devices found](../../assets/screenshots/connections_empty_state.png)

### Troubleshooting Bluetooth

- **Device not found:** Toggle Bluetooth off/on, ensure location is enabled.
- **Connection drops:** Move closer to the radio; check for interference.
- **Pairing rejected:** Forget the device in Android Bluetooth settings and retry.

## USB Serial

USB connections provide a wired alternative, useful for desktop or when Bluetooth is unavailable.

### Setup

1. Connect your radio to your phone with a USB cable.
2. The app prompts for USB permission — tap **Allow**.
3. The connection is established automatically.

&gt; ℹ️ **Note:** USB connections require OTG support on Android devices.

## TCP/IP (Network)

Some Meshtastic radios support Wi-Fi/Ethernet connectivity, allowing TCP-based connections over your local network. Get the radio onto your network first — using the radio's own Wi-Fi settings (via the firmware web interface or another connection) — then connect to it from the app.

&gt; ℹ️ **Note:** **Settings → Wi-Fi Provisioning for mPWRD-OS** is a separate, narrower tool. It provisions Wi-Fi
&gt; credentials over Bluetooth to **mPWRD-OS** devices only, using their own protocol — it does not
&gt; configure Wi-Fi on an ordinary Meshtastic radio. It scans over BLE, lists the networks the device
&gt; can see (including an option for a hidden SSID), takes the password, and reports success or
&gt; failure. Available on both Android and Desktop.

### Connecting over the Network

1. Make sure the radio is on the same local network as your phone/desktop.
2. On the Connect screen, select **Network** in the transport selector.
3. Choose the radio one of two ways:
   - **Scan for network devices** — toggle this on to auto-discover radios that advertise themselves on the local network (mDNS / `_meshtastic._tcp`). Discovered devices appear in the list; tap one to connect.
   - **Add device manually…** — enter the radio's IP address (or hostname) and port (default: `4403`).
4. Previously-used network addresses are remembered under **Recent Network Devices** for quick reconnection (touch &amp; hold to remove one).

&gt; 💡 **Tip:** Network discovery uses mDNS, which only works when both devices are on the same subnet. On Android 17+ the app needs the local-network permission for scanning; if discovery finds nothing, add the device manually by IP.

### When to Use TCP

- Radio is on the same local network
- Testing with a simulated radio
- Environments where Bluetooth has interference issues

## Reconnection Behavior

The app reconnects to the last selected radio on startup. You can switch transports from the Connect screen at any time.

To disconnect, tap the disconnect button on the Connect screen:

![Disconnect from radio](../../assets/screenshots/connections_disconnect.png)

## Desktop Connections

On Desktop (Linux/macOS/Windows), the app supports:
- **Bluetooth (BLE)** — via the Kable library; works on macOS, Linux, and Windows
- **USB Serial** — primary wired connection method
- **TCP/IP** — for network-connected radios

See [Desktop App](desktop) for platform-specific details and keyboard shortcuts.

## Related Topics

- [Getting Started](onboarding) — first-launch setup and permissions
- [Settings — Radio &amp; User](settings-radio-user) — Bluetooth and network configuration
- [Desktop App](desktop) — desktop-specific connection details
- [Supported devices](https://meshtastic.org/docs/hardware/devices) — full list of compatible radios on meshtastic.org
</pre>
</body>
</html>