mcbluetooth/docs/obex.md

OBEX Profile Support

OBEX (Object Exchange) enables file transfer and data synchronization over Bluetooth. mcbluetooth provides full support for the four major OBEX profiles through the obexd daemon.

Profiles Overview

Profile	UUID	Purpose	Typical Use
OPP (Object Push)	0x1105	Simple file sending	"Send this photo to my laptop"
FTP (File Transfer)	0x1106	Full file browsing	"Browse phone storage, download DCIM"
PBAP (Phonebook Access)	0x112F	Contact/call history	"Download my contacts"
MAP (Message Access)	0x1132	SMS/MMS/email	"Show unread messages"

Prerequisites

OBEX requires the obexd daemon, which is separate from the main bluetoothd:

# Arch Linux
sudo pacman -S bluez-obex

# Debian/Ubuntu
sudo apt install bluez-obex

# Fedora
sudo dnf install bluez-obex

Check your setup with:

bt_obex_status

If obexd isn't running, start it:

bt_obex_start_daemon

Note

: obexd runs as a user service on the session D-Bus, not the system bus. It requires a desktop session to be active.

---

Quick Start

Send a File (OPP)

The simplest OBEX operation — push a file to any device:

bt_obex_send_file address="C8:7B:23:55:68:E8" file_path="~/Documents/report.pdf"

The receiving device will show an accept/reject prompt. The tool waits for completion and reports success/failure.

Download Contacts (PBAP)

Pull all contacts from a paired phone:

bt_phonebook_pull address="AA:BB:CC:DD:EE:FF" save_path="~/contacts.vcf"

This creates a vCard file with all contacts. You can import it into any contacts app.

Browse Phone Storage (FTP)

For full file system access, create an FTP session:

# Connect
bt_obex_connect address="AA:BB:CC:DD:EE:FF" target="ftp"
# Returns: session_id="ftp_AABBCCDDEEFF"

# Browse root
bt_obex_browse session_id="ftp_AABBCCDDEEFF" path="/"

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

# Download a photo
bt_obex_get session_id="ftp_AABBCCDDEEFF" remote_path="photo.jpg" local_path="~/Downloads/"

# Disconnect when done
bt_obex_disconnect session_id="ftp_AABBCCDDEEFF"

---

How-To Guides

How to Transfer Files Between Devices

Scenario: You want to send multiple files to your phone.

1. For single files, use OPP (no session needed):

   bt_obex_send_file address="..." file_path="file1.pdf"
   bt_obex_send_file address="..." file_path="file2.jpg"
   

2. For multiple files or browsing, use FTP:

   bt_obex_connect address="..." target="ftp"
   bt_obex_browse session_id="..." path="/"
   bt_obex_put session_id="..." local_path="file1.pdf" remote_path="file1.pdf"
   bt_obex_put session_id="..." local_path="file2.jpg" remote_path="file2.jpg"
   bt_obex_disconnect session_id="..."
   

How to Backup Phone Contacts

Scenario: Create a backup of all contacts from your phone.

# Pull main phonebook
bt_phonebook_pull address="..." save_path="~/backup/contacts.vcf"

# Also backup call history
bt_phonebook_pull address="..." save_path="~/backup/calls_incoming.vcf" phonebook="ich"
bt_phonebook_pull address="..." save_path="~/backup/calls_outgoing.vcf" phonebook="och"
bt_phonebook_pull address="..." save_path="~/backup/calls_missed.vcf" phonebook="mch"

Phonebook types:

• pb — Main contacts (default)
• ich — Incoming call history
• och — Outgoing call history
• mch — Missed call history
• cch — Combined call history

How to Search Contacts

Scenario: Find a contact by name or phone number.

# Search by name
bt_phonebook_search address="..." field="name" value="John"

# Search by phone number
bt_phonebook_search address="..." field="number" value="555"

How to Read Text Messages

Scenario: Check unread SMS messages on your phone.

# List unread messages
bt_messages_list address="..." folder="inbox" unread_only=true

# Get full message content
bt_messages_get address="..." handle="msg001" save_path="~/message.txt"

How to Manage FTP Sessions

Scenario: You have a long-running file transfer workflow.

# List active sessions
bt_obex_sessions

# Check session details
bt_obex_connect address="..." target="ftp"

# Navigate folder structure
bt_obex_browse session_id="..." path="/"      # Root
bt_obex_browse session_id="..." path="DCIM"   # Enter folder
bt_obex_browse session_id="..." path=".."     # Go up

# Create/delete
bt_obex_mkdir session_id="..." folder_name="Backup"
bt_obex_delete session_id="..." remote_path="old_file.txt"

# Always disconnect when done
bt_obex_disconnect session_id="..."

How to Monitor Transfer Progress

Scenario: You're transferring a large file and want to check progress.

# Start transfer without waiting
bt_obex_send_file address="..." file_path="large_video.mp4" wait=false
# Returns: transfer_path="/org/bluez/obex/client/session0/transfer0"

# Check progress
bt_obex_transfer_status transfer_path="/org/bluez/obex/client/session0/transfer0"
# Returns: status="active", transferred=52428800, size=104857600, progress_percent=50

# Cancel if needed
bt_obex_transfer_cancel transfer_path="..."

---

Tool Reference

Setup & Status

Tool	Description
bt_obex_status	Check obexd installation and D-Bus connectivity
bt_obex_start_daemon	Start obexd if not running

Session Management

Tool	Parameters	Description
bt_obex_connect	address, target (opp/ftp/pbap/map)	Create OBEX session
bt_obex_disconnect	session_id	Close session
bt_obex_sessions	—	List active sessions

Object Push (OPP)

Tool	Parameters	Description
bt_obex_send_file	address, file_path, wait	Send file to device
bt_obex_get_vcard	address, save_path	Pull device's business card

File Transfer (FTP)

Tool	Parameters	Description
bt_obex_browse	session_id, path	List folder contents
bt_obex_get	session_id, remote_path, local_path	Download file
bt_obex_put	session_id, local_path, remote_path	Upload file
bt_obex_delete	session_id, remote_path	Delete file/folder
bt_obex_mkdir	session_id, folder_name	Create folder

Phonebook Access (PBAP)

Tool	Parameters	Description
bt_phonebook_pull	address, save_path, location, phonebook	Download full phonebook
bt_phonebook_list	address, location, phonebook	List entries with handles
bt_phonebook_get	address, handle, save_path	Download single entry
bt_phonebook_search	address, field, value	Search contacts
bt_phonebook_count	address, location, phonebook	Count entries

Parameters:

• location: "int" (internal memory) or "sim" (SIM card)
• phonebook: "pb", "ich", "och", "mch", "cch"
• field: "name", "number", "sound"

Message Access (MAP)

Tool	Parameters	Description
bt_messages_folders	address	List message folders
bt_messages_list	address, folder, unread_only, max_count	List messages
bt_messages_get	address, handle, save_path	Download message
bt_messages_send	address, recipient, message	Send SMS

Transfer Management

Tool	Parameters	Description
bt_obex_transfer_status	transfer_path	Check transfer progress
bt_obex_transfer_cancel	transfer_path	Cancel active transfer

---

Troubleshooting

"obexd not found"

Install the bluez-obex package:

# Arch
sudo pacman -S bluez-obex

# Debian/Ubuntu
sudo apt install bluez-obex

"Cannot connect to obexd D-Bus"

obexd runs on the session bus, which requires:

1. A graphical desktop session (X11 or Wayland)
2. D-Bus session daemon running

If running headless:

# Start a D-Bus session
eval $(dbus-launch --sh-syntax)
export DBUS_SESSION_BUS_ADDRESS

# Then start obexd
/usr/lib/bluetooth/obexd &

"Device rejected connection" / "NotAuthorized"

The target device must:

1. Be paired first (use bt_pair)
2. Have the profile enabled (check device settings)
3. Be connected for some profiles

Some devices require explicit authorization for OBEX access in their Bluetooth settings.

"Profile not supported"

Not all devices support all profiles:

Device Type	OPP	FTP	PBAP	MAP
Android phones	✓	varies	✓	varies
iPhones	✓	✗	✗	✗
Feature phones	✓	✓	✓	✓
Bluetooth speakers	✗	✗	✗	✗
Cars (infotainment)	✓	✗	✓	✓

"Transfer stuck at 0%"

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

Session disappeared

Sessions are tied to the obexd process. If obexd restarts, sessions are lost. Create a new session.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MCP Tools (tools/obex.py)               │
│  bt_obex_*, bt_phonebook_*, bt_messages_*                   │
├─────────────────────────────────────────────────────────────┤
│                   ObexClient (obex_client.py)               │
│  Session management, transfer monitoring, profile methods   │
├─────────────────────────────────────────────────────────────┤
│                      dbus-fast (async)                      │
│                      SESSION D-Bus                          │
├─────────────────────────────────────────────────────────────┤
│                         obexd                               │
│  /org/bluez/obex/client/sessionN/transferM                  │
├─────────────────────────────────────────────────────────────┤
│                        BlueZ                                │
│                    Bluetooth Stack                          │
└─────────────────────────────────────────────────────────────┘

D-Bus Object Paths

• Client: /org/bluez/obex
• Session: /org/bluez/obex/client/session0
• Transfer: /org/bluez/obex/client/session0/transfer0

Session Lifecycle

1. CreateSession(address, {Target: "ftp"}) → session path
2. Use profile interface (FileTransfer1, PhonebookAccess1, etc.)
3. Transfers create temporary objects with Status property
4. RemoveSession(session_path) when done

---

See Also

• BlueZ OBEX D-Bus API
• OBEX Specification
• vCard Format