# 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)