HFP Audio Gateway Tools

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

Tools for the HFP Audio Gateway role, allowing Linux to simulate a phone for testing Bluetooth headsets and hands-free devices.

bt_hfp_ag_enable

Enable HFP Audio Gateway mode on Linux.

Registers a custom HFP AG profile with BlueZ. After enabling, Bluetooth headsets (HF devices) can connect and Linux acts as the phone side.

Parameters: None

Returns:

{
  "status": "ok",
  "role": "audio_gateway",
  "profile": "HFP AG 1.7"
}

Example:

bt_hfp_ag_enable

Notes:

Must be called before headsets can connect via HFP
Registers on RFCOMM channel 13
Supports HFP 1.7 features including codec negotiation (CVSD/mSBC)

bt_hfp_ag_disable

Disable HFP Audio Gateway mode.

Unregisters the AG profile and disconnects any active HFP sessions.

Parameters: None

Returns:

{
  "status": "ok",
  "disabled": true
}

Example:

bt_hfp_ag_disable

bt_hfp_ag_status

Get HFP Audio Gateway status.

Parameters: None

Returns:

{
  "status": "ok",
  "registered": true,
  "connections": [
    {
      "address": "AA:BB:CC:DD:EE:FF",
      "slc_established": true,
      "codec": "msbc",
      "speaker_volume": 7,
      "mic_volume": 7,
      "calls": []
    }
  ],
  "indicators": {
    "service": 1,
    "call": 0,
    "callsetup": 0,
    "callheld": 0,
    "signal": 5,
    "roam": 0,
    "battchg": 5
  }
}

Example:

bt_hfp_ag_status

bt_hfp_ag_simulate_call

Simulate an incoming call to a connected HF device.

Sends RING and +CLIP (caller ID) notifications to the headset. The HF device sees an incoming call and can answer (ATA) or reject (AT+CHUP). Ringing repeats every 3 seconds until answered or ended.

Parameters:

Name	Type	Required	Description
`address`	string	Yes	Bluetooth address of connected HF device
`number`	string	No	Caller phone number to display (default: “5551234567”)

Returns:

{
  "status": "ok",
  "call_state": "ringing",
  "number": "5551234567"
}

Example:

bt_hfp_ag_simulate_call address="AA:BB:CC:DD:EE:FF" number="+15551234567"

Notes:

Device must have an established SLC (Service Level Connection)
The HF device will hear a ring tone (if in-band ring is supported)
Use bt_hfp_ag_end_call to stop ringing or terminate

bt_hfp_ag_end_call

End an active or ringing call from the AG side.

Parameters:

Name	Type	Required	Description
`address`	string	Yes	Bluetooth address of connected HF device

Returns:

{
  "status": "ok",
  "call_state": "ended"
}

Example:

bt_hfp_ag_end_call address="AA:BB:CC:DD:EE:FF"

bt_hfp_ag_set_volume

Set speaker or microphone volume on the HF device.

Sends +VGS (speaker) or +VGM (microphone) command to change volume remotely.

Parameters:

Name	Type	Required	Description
`address`	string	Yes	Bluetooth address of connected HF device
`type`	string	Yes	`"speaker"` for output volume, `"microphone"` for input
`level`	integer	Yes	Volume level 0-15 (0 = muted, 15 = maximum)

Returns:

{
  "status": "ok",
  "type": "speaker",
  "level": 12
}

Example:

# Set speaker volume
bt_hfp_ag_set_volume address="AA:BB:CC:DD:EE:FF" type="speaker" level=12

# Set microphone volume
bt_hfp_ag_set_volume address="AA:BB:CC:DD:EE:FF" type="microphone" level=10

bt_hfp_ag_set_signal

Update the signal strength indicator shown on the HF device.

Parameters:

Name	Type	Required	Description
`address`	string	Yes	Bluetooth address of connected HF device
`level`	integer	Yes	Signal strength 0-5

Returns:

{
  "status": "ok",
  "signal_strength": 4
}

Example:

bt_hfp_ag_set_signal address="AA:BB:CC:DD:EE:FF" level=4

bt_hfp_ag_set_battery

Update the battery level indicator shown on the HF device.

Parameters:

Name	Type	Required	Description
`address`	string	Yes	Bluetooth address of connected HF device
`level`	integer	Yes	Battery level 0-5

Returns:

{
  "status": "ok",
  "battery_level": 3
}

Example:

bt_hfp_ag_set_battery address="AA:BB:CC:DD:EE:FF" level=3