Ryan Malloy
9d1c0f3e0f
23-page docs site following diataxis principles with guides, reference, and explanation sections covering all 61 MCP tools. Bluetooth-themed design with Pagefind search.
369 lines
12 KiB
Markdown
369 lines
12 KiB
Markdown
# 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`:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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](https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/obex-api.txt)
|
|
- [OBEX Specification](https://www.bluetooth.com/specifications/specs/object-exchange-obex/)
|
|
- [vCard Format](https://en.wikipedia.org/wiki/VCard)
|