OBEX Profiles

import { Aside } from ‘@astrojs/starlight/components’;

OBEX (Object Exchange) is a protocol for transferring objects over Bluetooth. Four profiles build on OBEX for specific use cases.

What is OBEX?

OBEX is a binary protocol originally designed for infrared (IrDA) that was adapted for Bluetooth. It provides:

Session-based connections
Request/response pattern
Headers for metadata (name, type, length)
Support for large object transfers

Think of it as “HTTP for Bluetooth” — a simple way to push and pull objects between devices.

The Four OBEX Profiles

┌──────────────────────────────────────────────────────────────┐
│                         OBEX Protocol                        │
├──────────────────────────────────────────────────────────────┤
│    OPP     │    FTP     │    PBAP    │    MAP               │
│  (Push)    │  (Files)   │ (Contacts) │ (Messages)           │
└──────────────────────────────────────────────────────────────┘

OPP — Object Push Profile

Purpose: Simple file sending, like handing someone a file.

Characteristics

No session management needed
One-shot transfers
Receiver can accept or reject
Minimal device interaction required

Operations

Operation	Description
Push	Send a file to device
Pull	Get device’s business card

Use Cases

Send a photo to a friend
Share a document
Exchange contact cards

mcbluetooth Tools

bt_obex_send_file address="..." file_path="~/photo.jpg"
bt_obex_get_vcard address="..." save_path="~/contact.vcf"

Compatibility

Almost universal — OPP is the most widely supported OBEX profile.

Device	Support
Android	✓
iPhone	✓
Feature phones	✓
Windows	✓
macOS	✓

FTP — File Transfer Profile

Purpose: Browse and manage remote file systems.

Characteristics

Session-based (connect → browse → disconnect)
Full file system operations
Folder navigation
Two-way transfers

Operations

Operation	Description
Connect	Create FTP session
List	Get folder contents
Get	Download file
Put	Upload file
Delete	Remove file/folder
Mkdir	Create folder
Setpath	Navigate folders

Use Cases

Backup phone photos
Browse device storage
Manage files on remote device

mcbluetooth Tools

bt_obex_connect address="..." target="ftp"
bt_obex_browse session_id="ftp_..."
bt_obex_get session_id="..." remote_path="photo.jpg" local_path="~/photo.jpg"
bt_obex_put session_id="..." local_path="~/doc.pdf" remote_path="doc.pdf"
bt_obex_disconnect session_id="ftp_..."

Compatibility

More limited than OPP:

Device	Support
Android	Varies by version/manufacturer
iPhone	✗
Feature phones	✓ Usually
Windows	✓
macOS	✗

PBAP — Phonebook Access Profile

Purpose: Read contacts from a phone.

Characteristics

Read-only access (mostly)
Standardized folder structure
vCard format output
Search capabilities

Folder Structure

telecom/
├── pb/     ← Main phonebook
├── ich/    ← Incoming call history
├── och/    ← Outgoing call history
├── mch/    ← Missed call history
└── cch/    ← Combined call history

SIM1/
└── telecom/
    └── pb/ ← SIM card contacts

Operations

Operation	Description
PullAll	Download entire phonebook
List	Get contact handles
Pull	Get specific contact
Search	Find contacts by field

Use Cases

Sync contacts to car system
Backup phone contacts
Contact management applications

mcbluetooth Tools

bt_phonebook_pull address="..." save_path="~/contacts.vcf"
bt_phonebook_list address="..." folder="telecom/pb"
bt_phonebook_search address="..." field="name" value="Smith"
bt_phonebook_count address="..."

Compatibility

Device	Support
Android	✓ Full
iPhone	✓ (when properly paired)
Feature phones	✓ Usually
Car systems	✓ Often

MAP — Message Access Profile

Purpose: Access SMS/MMS messages.

Characteristics

Read messages from phone
Some devices support sending
Folder-based organization
Notification of new messages

Folder Structure

telecom/
└── msg/
    ├── inbox/
    ├── outbox/
    ├── sent/
    ├── drafts/
    └── deleted/

Operations

Operation	Description
GetFolderListing	List message folders
GetMessagesListing	List messages in folder
GetMessage	Download message content
PushMessage	Send message (if supported)
SetMessageStatus	Mark read/unread

Use Cases

Read texts through car system
Message backup
SMS integration applications

mcbluetooth Tools

bt_messages_folders address="..."
bt_messages_list address="..." folder="inbox" unread_only=true
bt_messages_get address="..." handle="msg001" save_path="~/message.txt"
bt_messages_send address="..." recipient="+1555..." message="Hello"

Compatibility

Most limited of the OBEX profiles:

Device	Read	Send
Android	✓	Varies
iPhone	✗	✗
Car systems	✓ (receive)	✗

Session Architecture

OPP (Stateless)

Client                    Server
   │                         │
   │────── CONNECT ─────────→│
   │←───── SUCCESS ──────────│
   │────── PUT file ────────→│
   │←───── SUCCESS ──────────│
   │────── DISCONNECT ──────→│
   │                         │

OPP creates temporary sessions for each transfer.

FTP/PBAP/MAP (Session-Based)

Client                    Server
   │                         │
   │────── CONNECT ─────────→│  ← Session created
   │←───── SUCCESS ──────────│
   │                         │
   │────── LIST ────────────→│
   │←───── folder contents ──│
   │                         │
   │────── GET file ────────→│
   │←───── file data ────────│
   │                         │
   │────── DISCONNECT ──────→│  ← Session closed
   │                         │

Sessions persist for multiple operations.

obexd Architecture

mcbluetooth uses BlueZ’s obexd daemon:

┌─────────────────────────────────────────────────────┐
│                   mcbluetooth                       │
│                        │                            │
│                   D-Bus (session)                   │
│                        │                            │
└────────────────────────┼────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────┐
│                      obexd                          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │   OPP   │ │   FTP   │ │  PBAP   │ │   MAP   │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
│                        │                            │
│                   RFCOMM/L2CAP                      │
└────────────────────────┼────────────────────────────┘
                         ▼
                  Bluetooth Stack

obexd runs on the session D-Bus (not system bus), which means:

Requires active desktop session
Per-user isolation
Integrates with user’s file permissions

Transfer Progress

OBEX transfers report progress via D-Bus properties:

{
  "Status": "active",
  "Transferred": 52428800,
  "Size": 104857600,
  "Filename": "large_file.mp4"
}

mcbluetooth polls these properties to provide progress updates.

Error Handling

Common OBEX errors:

Error	Meaning
`NotSupported`	Profile not available on device
`NotAuthorized`	Permission denied
`NotFound`	File/folder doesn’t exist
`Forbidden`	Operation not allowed
`Failed`	Generic failure

Security Notes

OBEX uses Bluetooth encryption (if paired)
Phone typically prompts for permission on first access
Permission can be revoked in phone settings
Sessions are tied to pairing relationship