---
title: OBEX File Transfer
description: Send files, browse phone storage, and download data using OBEX profiles
---

import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';

OBEX (Object Exchange) enables file transfer over Bluetooth. mcbluetooth supports four OBEX profiles:

| Profile | Code | Purpose |
|---------|------|---------|
| **OPP** | Object Push | Simple file sending |
| **FTP** | File Transfer | Full file browsing |
| **PBAP** | Phonebook Access | Read contacts (see [Phonebook guide](/guides/phonebook-messages/)) |
| **MAP** | Message Access | Read SMS/MMS (see [Phonebook guide](/guides/phonebook-messages/)) |

## Prerequisites

OBEX requires the `obexd` daemon:

<Tabs>
  <TabItem label="Arch Linux">
```bash
sudo pacman -S bluez-obex
```
  </TabItem>
  <TabItem label="Debian/Ubuntu">
```bash
sudo apt install bluez-obex
```
  </TabItem>
</Tabs>

Verify installation:

```
bt_obex_status
```

If obexd isn't running:

```
bt_obex_start_daemon
```

<Aside type="note">
obexd runs on the session D-Bus and requires an active desktop session.
</Aside>

## Quick File Send (OPP)

The simplest way to send a file:

```
bt_obex_send_file address="AA:BB:CC:DD:EE:FF" file_path="~/Documents/report.pdf"
```

- Creates a temporary OPP session
- Sends the file (recipient sees accept prompt)
- Waits for completion
- Closes the session

### Non-blocking Send

For large files, start transfer without waiting:

```
bt_obex_send_file address="..." file_path="large_video.mp4" wait=false
```

Returns a `transfer_path` to monitor progress:

```
bt_obex_transfer_status transfer_path="/org/bluez/obex/client/session0/transfer0"
```

## Pull Business Card (OPP)

Get the device's default vCard:

```
bt_obex_get_vcard address="AA:BB:CC:DD:EE:FF" save_path="~/contact.vcf"
```

## File Browsing (FTP)

For full file system access, create an FTP session:

### Create Session

```
bt_obex_connect address="AA:BB:CC:DD:EE:FF" target="ftp"
```

Returns:
```json
{
  "success": true,
  "session_id": "ftp_AABBCCDDEEFF",
  "address": "AA:BB:CC:DD:EE:FF",
  "target": "ftp"
}
```

### Browse Folders

```
# List root
bt_obex_browse session_id="ftp_AABBCCDDEEFF" path="/"

# Navigate to folder
bt_obex_browse session_id="ftp_AABBCCDDEEFF" path="DCIM"

# Go up
bt_obex_browse session_id="ftp_AABBCCDDEEFF" path=".."
```

Returns:
```json
{
  "entries": [
    {"name": "DCIM", "type": "folder"},
    {"name": "Download", "type": "folder"},
    {"name": "document.pdf", "type": "file", "size": 102400}
  ]
}
```

### Download Files

```
bt_obex_get session_id="ftp_..." remote_path="photo.jpg" local_path="~/Downloads/photo.jpg"
```

### Upload Files

```
bt_obex_put session_id="ftp_..." local_path="~/document.pdf" remote_path="document.pdf"
```

### Create Folder

```
bt_obex_mkdir session_id="ftp_..." folder_name="Backup"
```

### Delete Files

```
bt_obex_delete session_id="ftp_..." remote_path="old_file.txt"
```

### Close Session

Always close when done:

```
bt_obex_disconnect session_id="ftp_AABBCCDDEEFF"
```

## Session Management

### List Active Sessions

```
bt_obex_sessions
```

### Check OBEX Status

```
bt_obex_status
```

Returns:
```json
{
  "status": "ready",
  "obexd_installed": true,
  "obexd_running": true,
  "dbus_accessible": true,
  "active_sessions": [...]
}
```

## Transfer Monitoring

### Check Progress

```
bt_obex_transfer_status transfer_path="/org/bluez/obex/client/session0/transfer0"
```

Returns:
```json
{
  "status": "active",
  "size": 104857600,
  "transferred": 52428800,
  "progress_percent": 50
}
```

### Cancel Transfer

```
bt_obex_transfer_cancel transfer_path="..."
```

## Common Workflows

### Backup Phone Photos

```
# Connect FTP session
bt_obex_connect address="..." target="ftp"

# Navigate to photos
bt_obex_browse session_id="ftp_..." path="/"
bt_obex_browse session_id="ftp_..." path="DCIM"
bt_obex_browse session_id="ftp_..." path="Camera"

# Download each photo
bt_obex_get session_id="ftp_..." remote_path="IMG_001.jpg" local_path="~/backup/"
bt_obex_get session_id="ftp_..." remote_path="IMG_002.jpg" local_path="~/backup/"

# Close session
bt_obex_disconnect session_id="ftp_..."
```

### Share Document

```
# Simple send
bt_obex_send_file address="..." file_path="~/report.pdf"
```

## Device Compatibility

| Device Type | OPP | FTP |
|-------------|-----|-----|
| Android phones | ✓ | Varies |
| iPhones | ✓ | ✗ |
| Feature phones | ✓ | ✓ |
| Windows PCs | ✓ | ✓ |
| macOS | ✓ | ✗ |

<Aside type="note">
FTP support varies by Android version and manufacturer. Some require enabling "File Transfer" mode in Bluetooth settings.
</Aside>

## Troubleshooting

### "Device rejected connection"

- Ensure device is paired first
- Check device has OBEX enabled in Bluetooth settings
- Some devices require explicit file sharing permission

### "NotSupported"

The device doesn't support the requested profile. Try OPP instead of FTP.

### Transfer Stuck at 0%

The receiving device may be showing an accept prompt. Check its screen.

### Session Disappeared

Sessions are tied to obexd. If it restarts, create a new session.