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.
266 lines
5.3 KiB
Markdown
266 lines
5.3 KiB
Markdown
---
|
|
title: Phonebook & Messages
|
|
description: Access contacts and SMS using PBAP and MAP profiles
|
|
---
|
|
|
|
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
|
|
|
|
PBAP (Phonebook Access Profile) and MAP (Message Access Profile) let you read contacts and messages from paired phones.
|
|
|
|
<Aside type="note">
|
|
Both profiles require the device to be paired first. See [Device Pairing](/guides/pairing/).
|
|
</Aside>
|
|
|
|
## Prerequisites
|
|
|
|
These profiles use OBEX. Ensure obexd is installed:
|
|
|
|
```
|
|
bt_obex_status
|
|
```
|
|
|
|
If not ready:
|
|
|
|
<Tabs>
|
|
<TabItem label="Arch Linux">
|
|
```bash
|
|
sudo pacman -S bluez-obex
|
|
```
|
|
</TabItem>
|
|
<TabItem label="Debian/Ubuntu">
|
|
```bash
|
|
sudo apt install bluez-obex
|
|
```
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Phonebook Access (PBAP)
|
|
|
|
### Download Entire Phonebook
|
|
|
|
```
|
|
bt_phonebook_pull address="AA:BB:CC:DD:EE:FF" save_path="~/contacts.vcf"
|
|
```
|
|
|
|
This downloads all contacts as a single vCard file.
|
|
|
|
### List Contacts
|
|
|
|
```
|
|
bt_phonebook_list address="AA:BB:CC:DD:EE:FF"
|
|
```
|
|
|
|
Returns:
|
|
```json
|
|
{
|
|
"entries": [
|
|
{"handle": "1.vcf", "name": "Alice Smith"},
|
|
{"handle": "2.vcf", "name": "Bob Jones"},
|
|
...
|
|
],
|
|
"count": 150
|
|
}
|
|
```
|
|
|
|
### Get Single Contact
|
|
|
|
```
|
|
bt_phonebook_get address="..." handle="1.vcf" save_path="~/alice.vcf"
|
|
```
|
|
|
|
### Search Contacts
|
|
|
|
```
|
|
# Search by name
|
|
bt_phonebook_search address="..." field="name" value="Smith"
|
|
|
|
# Search by phone number
|
|
bt_phonebook_search address="..." field="number" value="+1555"
|
|
```
|
|
|
|
### Count Contacts
|
|
|
|
```
|
|
bt_phonebook_count address="AA:BB:CC:DD:EE:FF"
|
|
```
|
|
|
|
Returns total number of contacts without downloading them.
|
|
|
|
### Phonebook Folders
|
|
|
|
PBAP provides access to different phonebook locations:
|
|
|
|
| Folder | Contents |
|
|
|--------|----------|
|
|
| `telecom/pb` | Main phonebook (default) |
|
|
| `telecom/ich` | Incoming call history |
|
|
| `telecom/och` | Outgoing call history |
|
|
| `telecom/mch` | Missed call history |
|
|
| `telecom/cch` | Combined call history |
|
|
| `SIM1/telecom/pb` | SIM card contacts |
|
|
|
|
```
|
|
bt_phonebook_list address="..." folder="telecom/ich"
|
|
```
|
|
|
|
## Message Access (MAP)
|
|
|
|
### List Message Folders
|
|
|
|
```
|
|
bt_messages_folders address="AA:BB:CC:DD:EE:FF"
|
|
```
|
|
|
|
Returns:
|
|
```json
|
|
{
|
|
"folders": [
|
|
{"name": "inbox"},
|
|
{"name": "sent"},
|
|
{"name": "drafts"},
|
|
{"name": "outbox"},
|
|
{"name": "deleted"}
|
|
]
|
|
}
|
|
```
|
|
|
|
### List Messages
|
|
|
|
```
|
|
# All inbox messages
|
|
bt_messages_list address="..." folder="inbox"
|
|
|
|
# Unread only
|
|
bt_messages_list address="..." folder="inbox" unread_only=true
|
|
|
|
# Limit results
|
|
bt_messages_list address="..." folder="inbox" max_count=50
|
|
```
|
|
|
|
Returns:
|
|
```json
|
|
{
|
|
"messages": [
|
|
{
|
|
"handle": "msg001",
|
|
"subject": "Meeting tomorrow",
|
|
"sender": "+15551234567",
|
|
"timestamp": "2024-01-15T10:30:00",
|
|
"read": false,
|
|
"type": "SMS"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Download Message
|
|
|
|
```
|
|
bt_messages_get address="..." handle="msg001" save_path="~/message.txt"
|
|
```
|
|
|
|
### Send Message
|
|
|
|
<Aside type="caution">
|
|
Message sending support varies by device. Many phones only allow read access.
|
|
</Aside>
|
|
|
|
```
|
|
bt_messages_send address="..." recipient="+15559876543" message="Hello from mcbluetooth!"
|
|
```
|
|
|
|
## Common Workflows
|
|
|
|
### Backup All Contacts
|
|
|
|
```
|
|
# Download as vCard (can import into any contact app)
|
|
bt_phonebook_pull address="AA:BB:CC:DD:EE:FF" save_path="~/phone_backup_$(date +%Y%m%d).vcf"
|
|
```
|
|
|
|
### Export Call History
|
|
|
|
```
|
|
# Get incoming calls
|
|
bt_phonebook_list address="..." folder="telecom/ich"
|
|
|
|
# Get missed calls
|
|
bt_phonebook_list address="..." folder="telecom/mch"
|
|
```
|
|
|
|
### Find Contact by Phone Number
|
|
|
|
```
|
|
bt_phonebook_search address="..." field="number" value="555-1234"
|
|
```
|
|
|
|
### Archive Text Messages
|
|
|
|
```
|
|
# List all sent messages
|
|
bt_messages_list address="..." folder="sent"
|
|
|
|
# Download specific message
|
|
bt_messages_get address="..." handle="msg042" save_path="~/messages/msg042.txt"
|
|
```
|
|
|
|
## Device Compatibility
|
|
|
|
### PBAP Support
|
|
|
|
| Device | Support |
|
|
|--------|---------|
|
|
| Android phones | ✓ Full |
|
|
| iPhones | ✓ Full (when paired) |
|
|
| Feature phones | ✓ Usually |
|
|
| Car systems | ✓ Often (receive only) |
|
|
|
|
### MAP Support
|
|
|
|
| Device | Read | Send |
|
|
|--------|------|------|
|
|
| Android | ✓ | Varies |
|
|
| iPhone | ✗ | ✗ |
|
|
| Feature phones | Varies | Varies |
|
|
|
|
<Aside type="note">
|
|
iPhone doesn't support MAP. Use iCloud or other sync methods for messages.
|
|
</Aside>
|
|
|
|
## Troubleshooting
|
|
|
|
### "NotAuthorized" Error
|
|
|
|
The phone is blocking access. Check:
|
|
1. Phone screen for permission prompt
|
|
2. Bluetooth settings → paired device → enable phonebook/message access
|
|
|
|
### Empty Phonebook
|
|
|
|
Some phones require explicit permission:
|
|
- **Android**: Settings → Apps → Bluetooth → Permissions → Contacts
|
|
- **iPhone**: Settings → Bluetooth → [device] → Allow Contact Access
|
|
|
|
### MAP Connection Fails
|
|
|
|
1. Verify device supports MAP: `bt_device_info adapter="hci0" address="..."`
|
|
2. Check for MAP UUID in the UUIDs list
|
|
3. Some devices need MAP enabled in Bluetooth settings
|
|
|
|
### Slow Downloads
|
|
|
|
Large phonebooks (1000+ contacts) take time:
|
|
- PBAP downloads are sequential
|
|
- Consider using `bt_phonebook_count` first to estimate
|
|
- vCard format is verbose
|
|
|
|
## Privacy Considerations
|
|
|
|
<Aside type="caution">
|
|
These tools access personal data. Use responsibly and only on devices you own or have explicit permission to access.
|
|
</Aside>
|
|
|
|
- Phonebook and message access requires active pairing
|
|
- Devices typically prompt for permission on first access
|
|
- Permission can be revoked on the phone at any time
|