OBEX Tools

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

Tools for OBEX profiles — file transfer (OPP/FTP), phonebook access (PBAP), and message access (MAP).

OBEX tools require the `obexd` daemon. Use `bt_obex_status` to check availability.

Setup Tools

bt_obex_status

Check OBEX subsystem status.

Parameters: None

Returns:

{
  "status": "ready",
  "obexd_installed": true,
  "obexd_running": true,
  "dbus_accessible": true,
  "active_sessions": []
}

Example:

bt_obex_status

---

bt_obex_start_daemon

Start the obexd daemon if not running.

Parameters: None

Returns:

{
  "status": "started",
  "pid": 12345
}

Example:

bt_obex_start_daemon

---

Session Management

bt_obex_connect

Create an OBEX session to a device.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
target	string	Yes	Profile: “opp”, “ftp”, “pbap”, “map”

Returns:

{
  "success": true,
  "session_id": "ftp_AABBCCDDEEFF",
  "address": "AA:BB:CC:DD:EE:FF",
  "target": "ftp"
}

Example:

bt_obex_connect address="AA:BB:CC:DD:EE:FF" target="ftp"

---

bt_obex_disconnect

Close an OBEX session.

Parameters:

Name	Type	Required	Description
session_id	string	Yes	Session ID from bt_obex_connect

Returns:

{
  "status": "disconnected",
  "session_id": "ftp_AABBCCDDEEFF"
}

Example:

bt_obex_disconnect session_id="ftp_AABBCCDDEEFF"

---

bt_obex_sessions

List active OBEX sessions.

Parameters: None

Returns:

{
  "sessions": [
    {
      "session_id": "ftp_AABBCCDDEEFF",
      "address": "AA:BB:CC:DD:EE:FF",
      "target": "ftp",
      "created": "2024-01-15T10:30:00"
    }
  ]
}

---

OPP Tools (Object Push)

bt_obex_send_file

Send a file via Object Push Profile.

Parameters:

Name	Type	Required	Default	Description
address	string	Yes	-	Device MAC address
file_path	string	Yes	-	Local file to send
wait	boolean	No	true	Wait for transfer completion

Returns:

{
  "status": "complete",
  "filename": "report.pdf",
  "size": 102400,
  "transferred": 102400
}

Or if wait=false:

{
  "status": "started",
  "transfer_path": "/org/bluez/obex/client/session0/transfer0"
}

Example:

bt_obex_send_file address="AA:BB:CC:DD:EE:FF" file_path="~/Documents/report.pdf"

---

bt_obex_get_vcard

Pull business card (vCard) from device.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
save_path	string	Yes	Where to save the vCard

Returns:

{
  "status": "complete",
  "save_path": "/home/user/contact.vcf",
  "size": 512
}

Example:

bt_obex_get_vcard address="AA:BB:CC:DD:EE:FF" save_path="~/contact.vcf"

---

FTP Tools (File Transfer)

bt_obex_browse

List files and folders at a path.

Parameters:

Name	Type	Required	Default	Description
session_id	string	Yes	-	FTP session ID
path	string	No	”/“	Path to list (”/” for root, ”..” to go up)

Returns:

{
  "path": "/DCIM",
  "entries": [
    {"name": "Camera", "type": "folder"},
    {"name": "photo.jpg", "type": "file", "size": 2048576}
  ]
}

Example:

bt_obex_browse session_id="ftp_..." path="/DCIM"

---

bt_obex_get

Download a file from the device.

Parameters:

Name	Type	Required	Description
session_id	string	Yes	FTP session ID
remote_path	string	Yes	File path on device
local_path	string	Yes	Where to save locally

Returns:

{
  "status": "complete",
  "remote_path": "photo.jpg",
  "local_path": "/home/user/Downloads/photo.jpg",
  "size": 2048576
}

Example:

bt_obex_get session_id="ftp_..." remote_path="photo.jpg" local_path="~/Downloads/photo.jpg"

---

bt_obex_put

Upload a file to the device.

Parameters:

Name	Type	Required	Description
session_id	string	Yes	FTP session ID
local_path	string	Yes	Local file to upload
remote_path	string	Yes	Destination path on device

Returns:

{
  "status": "complete",
  "local_path": "/home/user/document.pdf",
  "remote_path": "document.pdf",
  "size": 102400
}

Example:

bt_obex_put session_id="ftp_..." local_path="~/document.pdf" remote_path="document.pdf"

---

bt_obex_delete

Delete a file or folder on the device.

Parameters:

Name	Type	Required	Description
session_id	string	Yes	FTP session ID
remote_path	string	Yes	File/folder to delete

Returns:

{
  "status": "deleted",
  "path": "old_file.txt"
}

Example:

bt_obex_delete session_id="ftp_..." remote_path="old_file.txt"

---

bt_obex_mkdir

Create a folder on the device.

Parameters:

Name	Type	Required	Description
session_id	string	Yes	FTP session ID
folder_name	string	Yes	Name of folder to create

Returns:

{
  "status": "created",
  "folder": "Backup"
}

Example:

bt_obex_mkdir session_id="ftp_..." folder_name="Backup"

---

Transfer Monitoring

bt_obex_transfer_status

Check progress of a transfer.

Parameters:

Name	Type	Required	Description
transfer_path	string	Yes	Transfer path from send/get operations

Returns:

{
  "status": "active",
  "filename": "large_file.mp4",
  "size": 104857600,
  "transferred": 52428800,
  "progress_percent": 50
}

Example:

bt_obex_transfer_status transfer_path="/org/bluez/obex/client/session0/transfer0"

---

bt_obex_transfer_cancel

Cancel an in-progress transfer.

Parameters:

Name	Type	Required	Description
transfer_path	string	Yes	Transfer path to cancel

Returns:

{
  "status": "cancelled",
  "transfer_path": "..."
}

---

PBAP Tools (Phonebook)

bt_phonebook_pull

Download entire phonebook as vCard file.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
save_path	string	Yes	Where to save

Returns:

{
  "status": "complete",
  "save_path": "/home/user/contacts.vcf",
  "count": 150
}

---

bt_phonebook_list

List phonebook entries with handles.

Parameters:

Name	Type	Required	Default	Description
address	string	Yes	-	Device MAC address
folder	string	No	”telecom/pb”	Phonebook folder

Folders:

• telecom/pb — Main phonebook
• telecom/ich — Incoming call history
• telecom/och — Outgoing call history
• telecom/mch — Missed call history

Returns:

{
  "entries": [
    {"handle": "1.vcf", "name": "Alice Smith"},
    {"handle": "2.vcf", "name": "Bob Jones"}
  ],
  "count": 150
}

---

bt_phonebook_get

Download single contact by handle.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
handle	string	Yes	Contact handle from list
save_path	string	Yes	Where to save vCard

---

bt_phonebook_search

Search phonebook by field.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
field	string	Yes	Field to search: “name”, “number”, “email”
value	string	Yes	Search value

---

bt_phonebook_count

Get total number of contacts.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address

Returns:

{
  "count": 150
}

---

MAP Tools (Messages)

bt_messages_folders

List message folders.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address

Returns:

{
  "folders": [
    {"name": "inbox"},
    {"name": "sent"},
    {"name": "drafts"},
    {"name": "outbox"},
    {"name": "deleted"}
  ]
}

---

bt_messages_list

List messages in a folder.

Parameters:

Name	Type	Required	Default	Description
address	string	Yes	-	Device MAC address
folder	string	No	”inbox”	Folder to list
unread_only	boolean	No	false	Only unread messages
max_count	integer	No	100	Maximum messages to return

Returns:

{
  "messages": [
    {
      "handle": "msg001",
      "subject": "Meeting tomorrow",
      "sender": "+15551234567",
      "timestamp": "2024-01-15T10:30:00",
      "read": false,
      "type": "SMS"
    }
  ]
}

---

bt_messages_get

Download message content.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
handle	string	Yes	Message handle from list
save_path	string	Yes	Where to save message

---

bt_messages_send

Send a message via MAP.

Parameters:

Name	Type	Required	Description
address	string	Yes	Device MAC address
recipient	string	Yes	Phone number to send to
message	string	Yes	Message text

Message sending support varies by device. Many phones only allow read access.