mcbluetooth/docs-site/src/content/docs/guides/obex.md

title	description
OBEX File Transfer	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)
MAP	Message Access	Read SMS/MMS (see Phonebook guide)

Prerequisites

OBEX requires the obexd daemon:

```bash sudo pacman -S bluez-obex ``` ```bash sudo apt install bluez-obex ```

Verify installation:

bt_obex_status

If obexd isn't running:

bt_obex_start_daemon

obexd runs on the session D-Bus and requires an active desktop session.

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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	✓	✗

FTP support varies by Android version and manufacturer. Some require enabling "File Transfer" mode in Bluetooth settings.

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.