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.
271 lines
5.0 KiB
Markdown
271 lines
5.0 KiB
Markdown
---
|
|
title: OBEX File Transfer
|
|
description: 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](/guides/phonebook-messages/)) |
|
|
| **MAP** | Message Access | Read SMS/MMS (see [Phonebook guide](/guides/phonebook-messages/)) |
|
|
|
|
## Prerequisites
|
|
|
|
OBEX requires the `obexd` daemon:
|
|
|
|
<Tabs>
|
|
<TabItem label="Arch Linux">
|
|
```bash
|
|
sudo pacman -S bluez-obex
|
|
```
|
|
</TabItem>
|
|
<TabItem label="Debian/Ubuntu">
|
|
```bash
|
|
sudo apt install bluez-obex
|
|
```
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Verify installation:
|
|
|
|
```
|
|
bt_obex_status
|
|
```
|
|
|
|
If obexd isn't running:
|
|
|
|
```
|
|
bt_obex_start_daemon
|
|
```
|
|
|
|
<Aside type="note">
|
|
obexd runs on the session D-Bus and requires an active desktop session.
|
|
</Aside>
|
|
|
|
## 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:
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{
|
|
"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 | ✓ | ✗ |
|
|
|
|
<Aside type="note">
|
|
FTP support varies by Android version and manufacturer. Some require enabling "File Transfer" mode in Bluetooth settings.
|
|
</Aside>
|
|
|
|
## 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.
|