Linux + iPhone Continuity / iMessage / SMS
#!/usr/bin/env bash
# Report whether this machine can carry Tether's iPhone Bluetooth features.
#
# Full mode = MAP + PBAP (messages, contacts) + ANCS (notifications)
# Compatibility = MAP + PBAP only; no notification mirroring
#
# Read-only unless --set-class is given.
#
# --set-class set the adapter's Class of Device to A/V Hands-Free
# --calls probe the call path; run it while a call is connected
set -uo pipefail
ADAPTER=${ADAPTER:-hci0}
ADAPTER_PATH="/org/bluez/$ADAPTER"
# A/V Hands-Free. iOS only offers the Messages/Contacts permission toggles to a
# device presenting this class. BlueZ ORs service bits on top, so only the low
# 13 bits (format + major + minor) are comparable.
TARGET_COD_LOW=0x0408
COD_MASK=0x1fff
set_class=0
calls_only=0
case ${1:-} in
--set-class) set_class=1 ;;
--calls) calls_only=1 ;;
esac
red=$'\e[31m'; grn=$'\e[32m'; ylw=$'\e[33m'; dim=$'\e[2m'; rst=$'\e[0m'
[[ -t 1 ]] || { red=; grn=; ylw=; dim=; rst=; }
blockers=0 # hardware/stack cannot do the job at all
degraded=0 # capable of MAP/PBAP but not ANCS
conflicts=0 # capable, but something else is in the way right now
ok() { printf ' %s✓%s %s\n' "$grn" "$rst" "$1"; }
warn() { printf ' %s!%s %s\n' "$ylw" "$rst" "$1"; degraded=$((degraded + 1)); }
clash() { printf ' %s!%s %s\n' "$ylw" "$rst" "$1"; conflicts=$((conflicts + 1)); }
bad() { printf ' %s✗%s %s\n' "$red" "$rst" "$1"; blockers=$((blockers + 1)); }
note() { printf ' %s%s%s\n' "$dim" "$1" "$rst"; }
prop() {
busctl --system get-property org.bluez "$ADAPTER_PATH" "$1" "$2" 2>/dev/null |
awk '{ $1=""; sub(/^ /,""); gsub(/"/,""); print }'
}
# Where the call audio goes is decided by whoever owns the hands-free profile,
# and only an active call proves it. Run this while a call is connected.
probe_calls() {
echo
echo "Call audio probe (run this while a call is CONNECTED)"
echo "====================================================="
echo
echo "BlueZ telephony objects"
local tree
tree=$(busctl --system tree org.bluez 2>/dev/null)
if grep -q '/telephony' <<<"$tree"; then
grep -o '/org/bluez/[^ ]*/telephony[0-9]*[^ ]*' <<<"$tree" | sort -u | while read -r path; do
ok "$path"
# Only the telephony interface; the generic D-Bus ones are noise.
busctl --system introspect org.bluez "$path" 2>/dev/null |
awk '/^org\.bluez\.(Telephony|Call)1/ { p = 1; next }
/^org\./ { p = 0 }
p && /^\./ { printf " %s\n", $0 }'
done
else
bad "no telephony object — HFP is not connected, or bluetoothd lacks --experimental"
fi
# The whole question: does BlueZ hand the SCO link to an audio server?
echo
echo "Media transports (a transport here would mean the audio can reach the desktop)"
if grep -qE '/fd[0-9]+' <<<"$tree"; then
grep -oE '/org/bluez/[^ ]*/fd[0-9]+' <<<"$tree" | sort -u | while read -r path; do
clash "$path"
busctl --system get-property org.bluez "$path" org.bluez.MediaTransport1 UUID 2>/dev/null |
awk '{ printf " UUID %s\n", $2 }'
done
note "Unexpected: report this, it changes what Tether can do."
else
ok "none — BlueZ exports no transport, so the audio stays on the phone"
fi
echo
echo "Audio server view"
if command -v pactl >/dev/null; then
if pactl list cards short 2>/dev/null | grep -q bluez; then
clash "a bluez_card exists:"
pactl list cards short 2>/dev/null | grep bluez | awk '{ printf " %s\n", $2 }'
else
ok "no bluez_card — nothing for the desktop to play through"
fi
else
note "pactl not installed; skipping"
fi
echo
echo "bluetoothd, last 40 lines"
journalctl -u bluetooth -n 40 --no-pager 2>/dev/null |
grep -iE 'sco|transport|codec|hfp' | tail -10 |
awk '{ printf " %s\n", $0 }' || note "no matching log lines"
echo
echo "Verdict"
if grep -qE '/fd[0-9]+' <<<"$tree"; then
printf ' %sTRANSPORT PRESENT%s — the call audio can reach this machine.\n' "$ylw" "$rst"
else
printf ' %sCONTROL ONLY%s — BlueZ signals the call but never opens the voice link.\n' "$grn" "$rst"
printf ' The audio plays on the phone. See "Calls" in docs/BLUETOOTH.md.\n'
fi
exit 0
}
(( calls_only == 1 )) && probe_calls
echo
echo "Tether Bluetooth capability probe"
echo "================================="
# --- tools ---------------------------------------------------------------
echo
echo "Tooling"
for t in busctl btmgmt bluetoothctl; do
if command -v "$t" >/dev/null; then ok "$t"; else bad "$t not found"; fi
done
command -v btmon >/dev/null || note "btmon not installed; useful for debugging pairing"
# --- bluez ---------------------------------------------------------------
echo
echo "BlueZ"
bluez_ver=$(bluetoothctl --version 2>/dev/null | awk '{print $2}')
if [[ -z $bluez_ver ]]; then
bad "could not determine BlueZ version"
elif [[ $(printf '%s\n5.86\n' "$bluez_ver" | sort -V | head -1) == "5.86" ]]; then
ok "version $bluez_ver (>= 5.86)"
else
warn "version $bluez_ver is older than 5.86 — ANCS unavailable"
note "MAP and PBAP still work; notification mirroring does not"
fi
# org.bluez.Bearer.LE1 appears only on bonded devices, and only when bluetoothd
# runs with --experimental (short form -E). A live interface on an existing bond
# is ground truth; the daemon command line is the fallback before anything is
# paired. Do not test for the long form alone, Arch's packaging uses -E.
bearer_seen=$(busctl --system call org.bluez / org.freedesktop.DBus.ObjectManager \
GetManagedObjects 2>/dev/null | grep -c 'org\.bluez\.Bearer\.LE1')
if (( bearer_seen > 0 )); then
ok "Bearer.LE1 present on a bonded device (Bearer API confirmed live)"
elif pgrep -af 'bluetoothd' | grep -qE -- '(^|[[:space:]])(-E|--experimental)([[:space:]]|$)'; then
ok "bluetoothd running with --experimental (Bearer API available)"
else
warn "bluetoothd is NOT running with --experimental — Bearer.LE1 unavailable"
note "ANCS needs it to drive the LE half of the bond. To enable:"
note " sudo mkdir -p /etc/systemd/system/bluetooth.service.d"
note " printf '[Service]\\nExecStart=\\nExecStart=/usr/lib/bluetooth/bluetoothd --experimental\\n' \\"
note " | sudo tee /etc/systemd/system/bluetooth.service.d/experimental.conf"
note " sudo systemctl daemon-reload && sudo systemctl restart bluetooth"
fi
# --- adapter -------------------------------------------------------------
echo
echo "Adapter ($ADAPTER)"
if ! busctl --system introspect org.bluez "$ADAPTER_PATH" >/dev/null 2>&1; then
bad "adapter $ADAPTER not present on the system bus"
echo
echo "Set ADAPTER=hciN to probe a different adapter."
exit 1
fi
addr=$(prop org.bluez.Adapter1 Address)
name=$(prop org.bluez.Adapter1 Alias)
ok "$addr ($name)"
# The chip, which BlueZ never reports: Adapter1.Modalias is BlueZ's own device id
# and reads the same on every machine. Bug reports need the hardware named.
controller=$(cat "/sys/class/bluetooth/$ADAPTER/device/modalias" 2>/dev/null || true)
[[ -n $controller ]] && note "controller $controller"
[[ $(prop org.bluez.Adapter1 Powered) == true ]] && ok "powered on" || bad "powered off (bluetoothctl power on)"
roles=$(prop org.bluez.Adapter1 Roles)
# BR/EDR is implied by a working Adapter1; LE requires both GATT roles. Peripheral
# is what lets us broadcast the post-bond ANCS solicitation advert that makes iOS
# surface its permission toggles.
[[ $roles == *central* ]] && ok "LE central role" || bad "no LE central role — ANCS impossible"
[[ $roles == *peripheral* ]] && ok "LE peripheral role" || warn "no LE peripheral role — cannot solicit ANCS"
instances=$(prop org.bluez.LEAdvertisingManager1 SupportedInstances)
if [[ -n ${instances:-} && $instances -gt 0 ]]; then
ok "advertising supported ($instances instances)"
else
warn "no advertising instances — iOS may never show the permission toggles"
fi
# --- class of device -----------------------------------------------------
echo
echo "Class of Device"
cod=$(prop org.bluez.Adapter1 Class)
if [[ -z ${cod:-} ]]; then
warn "could not read adapter class"
else
printf -v cod_hex '0x%06x' "$cod"
low=$(( cod & COD_MASK ))
if (( low == TARGET_COD_LOW )); then
ok "$cod_hex — A/V Hands-Free (major 4, minor 8)"
else
major=$(( (cod >> 8) & 0x1f ))
warn "$cod_hex — major $major, expected A/V Hands-Free (major 4, minor 8)"
note "iOS will not treat this machine as an eligible accessory."
if (( set_class )); then
echo
note "running: btmgmt class 4 8"
if echo | sudo btmgmt --index "${ADAPTER#hci}" class 4 8; then
note "class set; re-run this probe to confirm"
note "Make it stick: sudo systemctl enable --now tether-btclass@$ADAPTER"
else
note "failed — run 'sudo btmgmt class 4 8' by hand"
fi
else
note "Fix with: $0 --set-class (or: sudo btmgmt class 4 8)"
note "That lasts until bluetoothd restarts. To make it stick:"
note " sudo systemctl enable --now tether-btclass@$ADAPTER"
fi
fi
fi
# --- bonded devices ------------------------------------------------------
# A bond pinned to PreferredBearer=bredr refuses the inbound LE link the iPhone
# opens in answer to the ANCS solicitation, so notifications never arrive while
# messages and contacts look perfect.
echo
echo "Bonded devices"
dev_paths=$(busctl --system tree org.bluez 2>/dev/null |
grep -o "$ADAPTER_PATH/dev_[0-9A-F_]*$" | sort -u)
if [[ -z $dev_paths ]]; then
note "none bonded on $ADAPTER"
else
while read -r dev; do
[[ -n $dev ]] || continue
devprop() {
busctl --system get-property org.bluez "$dev" "$1" "$2" 2>/dev/null |
awk '{ $1=""; sub(/^ /,""); gsub(/"/,""); print }'
}
[[ $(devprop org.bluez.Device1 Paired) == true ]] || continue
alias=$(devprop org.bluez.Device1 Alias)
bearer=$(devprop org.bluez.Device1 PreferredBearer)
le_conn=$(devprop org.bluez.Bearer.LE1 Connected)
if [[ -z $bearer ]]; then
note "$alias — PreferredBearer not exposed by this BlueZ"
elif [[ $bearer == bredr && $le_conn != true ]]; then
warn "$alias — PreferredBearer=bredr with LE down; the bond is refusing the LE link"
note "Clear it: busctl set-property org.bluez $dev org.bluez.Device1 PreferredBearer s le"
else
ok "$alias — PreferredBearer=$bearer"
fi
done <<<"$dev_paths"
fi
# --- conflicts -----------------------------------------------------------
# The iPhone serves exactly one MAP session at a time. Any other local process
# holding it makes Tether's MAP connect fail with "Connection refused (111)",
# which looks nothing like a permissions problem and wastes a lot of debugging.
echo
echo "Conflicts"
if systemctl --user is-active --quiet obex.service 2>/dev/null; then
ok "obexd active (required for MAP and PBAP)"
else
warn "obexd is not active — MAP and PBAP will not connect"
note "It is socket-activated; 'systemctl --user start obex' forces it up."
fi
# obexd opens MAP and PBAP over L2CAP in ERTM mode; with ERTM disabled the
# kernel refuses it and obexd reports "Unable to find service record".
if [[ $(cat /sys/module/bluetooth/parameters/disable_ertm 2>/dev/null) == [Y1] ]]; then
warn "kernel has L2CAP ERTM disabled — MAP and PBAP will fail with no_record"
note "Fix for this boot: echo N | sudo tee /sys/module/bluetooth/parameters/disable_ertm"
note "Persist: remove disable_ertm from the kernel command line or /etc/modprobe.d"
else
ok "L2CAP ERTM enabled"
fi
# --- verdict -------------------------------------------------------------
echo
echo "Verdict"
if (( blockers > 0 )); then
printf ' %sBLOCKED%s — %d hard problem(s) above must be resolved first.\n' "$red" "$rst" "$blockers"
exit 1
fi
if (( degraded > 0 )); then
printf ' %sCOMPATIBILITY MODE%s — messages and contacts (MAP/PBAP) should work;\n' "$ylw" "$rst"
printf ' notification mirroring (ANCS) will not, until the %d capability gap(s) above are fixed.\n' "$degraded"
else
printf ' %sFULL MODE%s — this machine can carry MAP, PBAP, and ANCS.\n' "$grn" "$rst"
fi
if (( conflicts > 0 )); then
printf ' %s%d conflict(s)%s must be cleared before Tether can connect right now.\n' "$ylw" "$conflicts" "$rst"
fi
exit 0