quoije/yaris-obd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bc29a013379647f15ff9bcbe38eab178ebef03f7
yaris-obd/poc/yaris-mediacenter-plan.md
T

18 KiB
Raw Blame History

yaris-mediacenter — Bluetooth Audio Bridge for the Car

Status: PLANNING — do not start building without owner approval.

A new Pi-side service that acts as a transparent Bluetooth middleman between a phone (Spotify, any audio app) and the car radio. The Pi broadcasts as a Bluetooth A2DP sink that the phone connects to (phone thinks it's the car stereo), receives the audio stream, then re-broadcasts it as an A2DP source that the car radio connects to. Media controls (play, pause, skip, volume) relay bidirectionally through the Pi via AVRCP.

The car radio sees a normal Bluetooth audio device. The phone sees a normal Bluetooth speaker. The Pi sits invisibly in the middle, bridging them.

The Problem (why this exists)

  • The 2013 Yaris radio likely has either no Bluetooth at all, or an older Bluetooth module that only supports hands-free calling (HFP), not music streaming (A2DP).
  • Even if the radio does support Bluetooth A2DP, there's no way to have the phone simultaneously connected to the radio for audio AND the Pi for the local web UI over WiFi without manual reconnection each time.
  • This service makes the Pi the one permanent Bluetooth connection for the radio, and the phone connects to the Pi instead — the Pi becomes the car's infotainment hub.

Architecture Overview

┌──────────┐    Bluetooth A2DP/AVRCP     ┌──────────┐    Bluetooth A2DP/AVRCP     ┌───────────┐
│  Phone   │ ──────────────────────────▶ │    Pi    │ ──────────────────────────▶ │ Car Radio │
│ (Spotify)│ ◀────────────────────────── │(mediacntr)│ ◀────────────────────────── │           │
│          │   audio stream (SBC/AAC)    │          │   re-encoded audio (SBC)    │           │
│          │   media controls (AVRCP)    │          │   media controls (AVRCP)    │           │
└──────────┘                             └──────────┘                             └───────────┘
                                               │
                                     WiFi hotspot (existing)
                                     "yaris 911" @ 10.42.0.1
                                               │
                                    ┌──────────────────────┐
                                    │ Existing yaris-obd UI │
                                    │ (dashboard, dashcam,  │
                                    │  status — unchanged)  │
                                    └──────────────────────┘

Bluetooth profiles involved

Profile Role (Phone side) Role (Radio side) Purpose
A2DP Pi is Sink (receives audio from phone) Pi is Source (sends audio to radio) Stereo audio streaming
AVRCP Pi is Target (receives commands from phone) Pi is Controller (sends commands to radio) Play/pause/skip/track metadata relay

Audio pipeline

Phone → [Bluetooth A2DP Sink] → PulseAudio source → PulseAudio loopback → PulseAudio sink → [Bluetooth A2DP Source] → Radio
  • BlueZ registers the Pi as a connectable A2DP sink (for the phone).
  • BlueZ also connects the Pi to the car radio as an A2DP source.
  • PulseAudio bridges the two: module-loopback routes audio from the phone's A2DP source (in PulseAudio) to the radio's A2DP sink (in PulseAudio).
  • No audio file is ever written to disk — it's a live stream pipeline, minimal latency.

Hardware Considerations

Pi 3's built-in Bluetooth

The Pi 3's BCM43438 combo chip provides both WiFi and Bluetooth on the same physical radio. This has two implications:

  1. Coexistence: 2.4 GHz WiFi (especially the AP/hotspot on wlan0) shares spectrum with Bluetooth. This can cause audio dropouts. Mitigations:

    • Bluetooth uses adaptive frequency hopping (AFH), which avoids WiFi channels — this is built into the BCM43438 firmware and normally works well.
    • If dropouts are a problem in practice, a USB Bluetooth 5.0 dongle (~$10) can offload the phone or radio connection to a separate radio entirely, eliminating WiFi/BT contention.
    • The Phase 23.5 wlan1 (TP-Link Archer T3U, 5 GHz-capable) is already installed — moving the hotspot to 5 GHz would completely eliminate 2.4 GHz WiFi/Bluetooth interference. This is a configuration change, not new hardware.

  2. Disable-bt overlay: The Pi currently uses dtoverlay=disable-bt in /boot/firmware/config.txt to free the PL011 UART for the SIM868 GPS module (see Phase 1 bring-up notes). This completely disables the onboard Bluetooth controller. To use Bluetooth for mediacenter:

    • Option A: Use a USB Bluetooth dongle instead (preserves GPS UART routing, cleaner separation, likely better range/audio quality with BT 5.0).
    • Option B: Use the mini-UART (/dev/ttyS0) for the SIM868 at a lower, core-frequency-dependent baud rate, re-enable the onboard Bluetooth for the PL011 UART. Riskier — mini-UART is less stable and baud rate depends on the core clock, which can drift.

    Recommendation: Option A (USB dongle). The onboard Bluetooth is disabled for GPS, and a USB dongle is cheap, isolated, and doesn't require touching the already-working GPS UART config.

Phases

Phase M1: Bluetooth stack validation (research spike)

Goal: Prove the Pi can simultaneously be an A2DP sink + A2DP source with audio passing through, before writing any production code.

  • Install BlueZ + PulseAudio + pulseaudio-module-bluetooth on the Pi.
  • Pair and connect the Pi as an A2DP sink from a real phone.
    • Verify pactl list sources shows the phone's A2DP stream as an audio source.
  • Pair and connect the Pi as an A2DP source to a real Bluetooth speaker/radio.
    • Verify pactl list sinks shows the radio/speaker as an audio sink.
  • Set up a PulseAudio loopback: pactl load-module module-loopback source=<phone_source> sink=<radio_sink>.
  • Play audio on the phone, confirm it comes out of the radio/speaker.
    • Measure rough latency (video-sync test: watch a video on the phone, observe lip sync).
  • Test AVRCP relay: play/pause/skip from the radio's controls should affect the phone.
    • This may require a custom DBus script (BlueZ exposes org.bluez.MediaPlayer1 on both the sink and source sides — commands received on the source side need to be forwarded to the target/sink side).
  • Document: what exact BlueZ/PulseAudio commands, what worked, what didn't, latency numbers, codec info, audio quality observations.

Estimated time: 2-3 hours of hands-on Pi tinkering. Deliverable: A markdown file in poc/ with raw terminal logs, commands, and findings.

Go/No-go decision after M1: If audio passes through with acceptable latency (< ~300ms additional) and AVRCP relay is feasible via DBus scripts, proceed to M2. If the onboard Bluetooth is too flaky or latency is unusable, re-evaluate USB dongle or shelve.

Phase M2: yaris-mediacenter service scaffold

Goal: Package the M1 proof-of-concept into a proper Python service that auto-starts alongside yaris-obd, with persistent configuration.

  • Create modules/app_mediacenter.py:
    • BluetoothBridge class managing the dual-role Bluetooth session.
    • Config loaded from config/mediacenter.json (device names, PIN codes, auto-connect MAC addresses, codec preferences).
    • Subprocess management of bluetoothctl, pactl, parec/pacat or direct DBus calls via pydbus/dasbus to avoid shelling out.
    • Health check: are both connections alive? Reconnect logic on disconnect.
  • PulseAudio loopback management:
    • Create/destroy the loopback module programmatically.
    • Handle dynamically appearing/disappearing sources and sinks (phone connects, radio connects — the loopback needs to adapt).
  • AVRCP relay via DBus:
    • Listen for org.bluez.MediaPlayer1.PropertiesChanged on the source side (radio).
    • Forward Play, Pause, Next, Previous, FastForward, Rewind to the target side (phone).
    • Relay track metadata (Title, Artist, Album, Duration) from the phone to the radio side — the radio's display can show "now playing" info.
  • systemd unit: deploy/yaris-mediacenter.service
    • Requires bluetooth.service and pulseaudio.service (user-mode pulseaudio for the yaris user).
    • Wants=yaris-obd.service (co-located, not strictly dependent).
  • Install script: deploy/install_mediacenter.sh
    • Installs required apt packages (BlueZ, PulseAudio, pulseaudio-module-bluetooth, Python DBus bindings).
    • Configures PulseAudio for the yaris user (systemd user service).
    • Enables Bluetooth discoverable/connectable mode permanently.
  • UI: minimal status indicator on the existing /status page:
    • Phone connected? (MAC, device name, codec)
    • Radio connected? (MAC, device name, codec)
    • Audio flowing? (PulseAudio loopback state)
    • Latency estimate.

Deliverable: Running service on the Pi, phone → Pi → radio audio chain verified. Dependencies: M1 must be complete (Bluetooth stack proven).

Phase M3: Pairing & auto-connect UX

Goal: Make pairing practical — not a manual bluetoothctl sequence every time the car starts.

  • Phone pairing (persistent):

    • Pi always discoverable as "yaris-mediacenter" (or configurable name).
    • First-time phone pairing is manual (phone scans, finds Pi, pairs — standard).
    • Pi remembers paired phones via BlueZ's trusted-device store.
    • Auto-connect: when a trusted phone comes in range, Pi automatically accepts the A2DP connection. No user action needed after the first pairing.

  • Radio pairing (persistent):

    • If the car radio supports Bluetooth scanning, the radio finds "yaris-media" (separate name from phone side — the two A2DP roles need distinct names).
    • Pair once, Pi remembers the radio's MAC.
    • Auto-connect: on service start, Pi actively connects to the radio's MAC as an A2DP source (the radio is the "speaker" from the Pi's perspective).

  • Reconnection ordering:

    • On ignition-on (Pi boots): mediacenter starts → connects to radio first (A2DP source) → then enables discoverability for the phone (A2DP sink).
    • If radio isn't in range yet (radio boots slower than the Pi), retry with exponential backoff.
    • If phone disconnects (user walks away), audio pipeline gracefully pauses, reconnects when phone returns.

  • Settings page (new section on existing /settings):

    • Radio MAC address (manual entry or scan-and-select).
    • Phone-side Bluetooth device name.
    • Radio-side Bluetooth device name.
    • Auto-connect toggle (on/off).
    • Preferred codec (auto / SBC / AAC if supported).

  • Quick-access control widget:

    • A small "Now Playing" card on the dashboard showing track metadata (Title, Artist) when audio is flowing.
    • Play/pause/skip buttons (passenger-safe, not for driver use while moving).

Deliverable: Phone and radio pair once, reconnect automatically every drive. Dependencies: M2 service scaffold complete.

Phase M4: Audio quality & latency tuning

Goal: Make it sound good and feel responsive.

  • Codec selection:

    • Phone → Pi: negotiate the best available codec (AAC preferred on iPhone, aptX if the USB dongle supports it, SBC as fallback).
    • Pi → Radio: most car radios only support SBC. SBC bitpool tuning (higher bitpool = better quality, more bandwidth).
    • Document negotiated codecs per connection in the status endpoint.

  • Latency measurement & reduction:

    • Measure end-to-end latency (phone speaker → Pi → radio speaker) with a clap test or audio sync video.
    • Tune PulseAudio buffer sizes (latency_msec in module-loopback).
    • If latency > 500ms, consider:
      • Smaller Bluetooth packet sizes.
      • Lower PulseAudio fragment sizes.
      • Direct ALSA loopback (bypass PulseAudio entirely) as a fallback path.

  • Audio glitch handling:

    • Detect buffer underruns (audio dropouts), log them.
    • Automatic recovery: if the loopback module dies, recreate it.
    • Graceful handling of temporary Bluetooth interference.

  • Volume passthrough:

    • Phone volume → Pi's A2DP sink volume → Pi's A2DP source volume → Radio volume.
    • Keep the chain linear: phone volume controls the full path, radio volume is a secondary hardware trim.
    • AVRCP absolute volume if the radio supports it.

Deliverable: Measured latency numbers, acceptable audio quality. Dependencies: M3 connection stability.

Phase M5: Hands-free calling (HFP) relay (stretch goal)

Goal: If the car radio has Bluetooth but only supports HFP (hands-free calling), not A2DP (music), the Pi can bridge phone calls too. If the radio has NO Bluetooth at all, this does nothing — the Pi would need a mic/speaker connected directly, which is a different scope.

  • Pi acts as HFP Audio Gateway (AG) for the radio.
  • Pi acts as HFP Hands-Free (HF) for the phone.
  • Call audio relay: same PulseAudio loopback pattern.
  • Call control relay: answer, hang up, dial.
  • Phonebook access relay (PBAP) — the radio can show incoming caller ID.

This phase is explicitly optional — most users will use A2DP music streaming, and HFP relay adds significant complexity (SCO audio routing, AT command handling, call state machine). Only build if M1-M4 are all solid and the user explicitly requests it.

Phase M6: Spotify Connect / media source integration (stretch goal)

Goal: Instead of the phone streaming Bluetooth audio, run a lightweight Spotify client directly on the Pi so the phone is only a remote control, not the audio source. This eliminates the phone→Pi Bluetooth hop entirely.

  • Install spotifyd or librespot on the Pi (headless Spotify Connect receiver).
  • Route Spotify audio directly to the A2DP source (Pi → Radio), no loopback needed.
  • Phone uses the Spotify app as a remote (Spotify Connect protocol — built into the Spotify app, no custom code needed).
  • Fallback: if the user isn't playing Spotify (e.g., YouTube, podcasts, navigation voice), fall back to the Bluetooth A2DP relay from M1-M3.

Trade-off vs. M1-M3 approach:

  • Pro: One fewer Bluetooth hop = less latency, better audio quality, lower battery drain on the phone (phone just sends control commands, not an audio stream).
  • Con: Only works for Spotify. Any other audio app (Apple Music, YouTube, podcast apps, navigation) still needs the Bluetooth relay.
  • Con: spotifyd/librespot requires a Spotify Premium account and the Pi needs internet access (phone hotspot uplink via wlan1 — already built in Phase 22).

Recommendation: Build M1-M3 (Bluetooth relay) first, since it works for ALL audio. Add M6 later as an optimization for Spotify specifically.

Open Questions (to resolve during M1)

# Question Impact
Q1 Does the 2013 Yaris radio have Bluetooth at all? If so, which profiles? Defines what the Pi needs to broadcast (A2DP vs HFP only)
Q2 Can the Pi's BCM43438 (or a USB dongle) maintain two simultaneous Bluetooth connections (phone + radio) without audio dropouts? Determines if USB dongle is required
Q3 What is the real end-to-end latency (phone → Pi → radio)? Determines if this is usable for video/navigation or music-only
Q4 Does dtoverlay=disable-bt permanently block the onboard Bluetooth, or can it be re-enabled while keeping the SIM868 on mini-UART? Determines if USB dongle is mandatory
Q5 Does the car radio support AVRCP metadata display (track title/artist on the radio screen)? Determines if Phase M2 metadata relay is worth building

Deployment Impact

  • New apt packages: pulseaudio, pulseaudio-module-bluetooth, bluez-tools, Python pydbus or dasbus.
  • New systemd units: yaris-mediacenter.service (possibly a user unit for PulseAudio).
  • New config files: config/mediacenter.json.
  • Existing services: no changes to yaris-obd.service, GPS, OBD, WiFi, or uplink paths. Mediacenter is an independent service that happens to run on the same Pi.
  • WiFi/Bluetooth coexistence: if using a USB dongle on a USB 3.0 port, be aware of USB 3.0 2.4 GHz interference (this is a known hardware issue with Pi 4; Pi 3 only has USB 2.0, so not a concern here).

Risk Assessment

Risk Likelihood Impact Mitigation
Audio latency too high for video/nav Medium High Phase M1 validates early; M6 (Spotify Connect) bypasses it for music
Bluetooth coexistence with WiFi hotspot causes dropouts Medium Medium USB dongle + 5 GHz WiFi on wlan1 (already available)
disable-bt overlay blocks all Bluetooth High (confirmed) Low USB dongle is the planned path anyway
AVRCP relay via DBus is unreliable or incomplete Medium Medium Fall back to phone-side controls only; M1 validates
Car radio has no Bluetooth at all ? High M1 clarifies; if no BT radio, this project needs a different approach (FM transmitter? aux cable? replace the head unit?)

Go/No-Go Checklist

Before starting Phase M2 (committed code):

  • M1 research spike complete with real hardware.
  • Latency measured and deemed acceptable by owner.
  • Audio quality confirmed acceptable.
  • Both A2DP sink + source roles confirmed working simultaneously.
  • Owner explicit approval to proceed past M1.
Reference in New Issue View Git Blame Copy Permalink