Audio Agent Commands

When in Command mode, the module accepts commands from the host via the UART interface. The generic syntax for commands is:

COMMAND (parameter_1) (parameter_2) … (parameter_n)\r

with a space between each parameter and a Carriage Return (‘r’ or 0x0D) at the end of each command.

The different commands to control the Bluetooth link are listed in alphabetical order below. Mandatory parameters are listed in “( )” optional parameters are listed in “[ ]”.

The maximum length for a command is 150 characters, if a command larger than this is provided, Audio Agent will return an error.

UART Command

Description

$$$$

Exit Data mode. Must be sent through the UART interface.

ADVERTISING (value)

BLE Advertising. This command is allowed in Peripheral or Beacon mode.

value:

ON/OFF: to start/stop advertising. Returns OK if success.

or

size: size is the size of the advertising data (0 to 31 bytes). Returns PENDING. The data received after this command is used to set the advertising data. Returns OK when the data is fully retrieved.

AT (link_ID) (command to send)

Send a command over the HFP link to the remote device. AT commands must be enabled in HFP_CONFIG.

AVRCP_META_DATA

(link_ID)[(type)(data)]

This command can be used to get or set the AVRCP Meta Data depending on the A2DP role of Audio Agent:

In sink mode, if ‘type’ and ‘data’ are not provided, Audio Agent will request the AVRCP Meta Data specified in the remote device and reply OK. The attributes received are notified with the AVRCP_MEDIA events. Note that AVRCP Meta Data must be enabled in MUSIC_META_DATA).

In source mode, if ‘type’ and ‘data’ are provided, Audio Agent will send a notification (track changed) to inform that the AVRCP Meta Data has changed. The result will be PENDING until the remote device sends a request to get the new attribute. Audio Agent will respond with the data provided and reply OK.

link_id: AVRCP link

type: attribute type

  1. Title

  2. Artist

  3. Album

  4. Number

  5. Total number

  6. Genre

  7. Playing time

data: attribute data (string)

BATTERY_STATUS

Returns the battery status of the battery attached to the module by detecting the voltage level

BC_SMART_COMMAND (link)(command)

Send a command to a peripheral device over BLE.

BC_SMART_NOTIF (link)(data)(cmd)

Enable/disable notifications for the BC smart characteristics of a peripheral device.

BLE_GET_CHAR (link)[handle_start][handle_end]

Discover the characteristics of a peripheral device between handle_start and handle_end in. Lists all the characteristics if handles are not provided. BLE_CHAR notifications are received for each characteristics discovered and OK is returned when the discovery is completed.

BLE_GET_SERV (link)

Discover all the primary services of a peripheral device. BLE_SERV notifications are received for each services discovered and OK is returned when the discovery is completed.

BLE_INDICATION (link)(handle)(size_value)

Sends a indication to the central device for the handle.

link_id: link of the central device

handle: handle of the characteristic

size_value: length of the characteristic value to be indicated in bytes

Returns PENDING. The characteristic value is filled with size_value octets received after this command. Returns OK when fully retrieved.

BLE_NOTIFICATION (link)(handle)(size_value)

Sends a notification to the central device for the handle.

link_id: link of the central device

handle: handle of the characteristic

size_value: length of the characteristic value to be notified in bytes

Returns PENDING. The characteristic value is filled with size_value octets received after this command. Returns OK when fully retrieved.

BLE_READ (link)(handle)

Send a request to read a characteristic value from a peripheral device for the handle.

link: link of the peripheral device

handle: handle of the characteristic Returns PENDING. A BLE_READ_RES notification with the characteristic value is received when the remote device reply.

BLE_READ_RES (link)(handle)(size_value)

Respond to a read request from a central device (BLE_READ notification).

link: link of the central device

handle: handle of the characteristic

size_value: length of the characteristic value in bytes

Returns PENDING. The characteristic value is filled with size_value octets received after this command. Returns OK when fully retrieved.

BLE_SET_DB (size_db)

Change the GATT database for a peripheral device in BLE IDLE state.

size_db: size of the GATT database in hex.

Returns PENDING. The database is filled with size_db words received after this command. Returns OK when fully retrieved or an error if not enough memory to store the database.

BLE_WRITE (link)(handle)(size_value)

Write a characteristic value to a peripheral device for the handle.

link: link of the peripheral device

handle: handle of the characteristic. Note that in Audio Agent the handle of a client characteristic config is equal to the handle of the characteristic + 1.

size_value: length of the characteristic value to be written in bytes

Returns PENDING. The characteristic value is filled with size_value octets received after this command. Returns OK when fully retrieved.

CALL (link) (action) [param]

Call interactions with the specified HFP or AGHFP link.

For an HFP link, action can be any of the following:

  • REDIAL: Notifies the AG that the HF wants to establish an outgoing call with the last number dialled.

  • MEMORY: Notifies the AG that the HF wants to establish an outgoing call using memory dialling. In this case, param is a combination of alphanumeric characters supplied to the AG by the HF. The memory string is AG specific.

  • OUTGOING: Notifies the AG that the HF wants to establish a call with the number specified in param

  • ANSWER: Answer an incoming call from the HF.

  • REJECT: Reject an incoming call from the HF.

  • TRANSFER: Performs an audio connection transfer towards the HF (when value is ON_HF) or an audio connection transfer towards the AG (when value is ON_AG). If param is not provided, Audio Agent will decide depending on where the audio is currently routed.

  • TWC: Three way calling. Send a request to the AG to perform an action based on param. param can be:

    • 0 Reject

    • 1 Hold & Accept / Swap

    • 2 End & Accept

    • 3 Merge calls (multiparty)

    • 4 Hang up calls (multiparty)

  • END: Terminate an outgoing or active call from the HF.

    For an AGHFP link, action can be any of the following:

  • ANSWER: For an incoming call, answer the call from the AG. For an outgoing call, notify the AG that the remote side has answered.

  • END: Terminate an incoming, outgoing or active call.

  • TRANSFER: Performs an audio connection transfer towards the HF (when value is ON_HF) or an audio connection transfer towards the AG (when value is ON_AG). If param is not provided, Audio Agent will decide depending on where the audio is currently routed.

  • INCOMING: Setups the AG in incoming call mode for the number specified in param. Number can by any combination of alphanumeric characters.

  • OUTGOING: Setups the AG in outgoing call mode for the number specified in param. Number can be any combination of alphanumeric characters.

CLOSE (link/device)

Terminates the Bluetooth Profile connection. link is a number that defines the connection ID. all closes all links. It is also possible to give the device number as parameter to close all the connections for with this device.

CONFIG

Shows all configuration registers

CONNECTABLE (mode)

ON puts the module in connectable mode.

OFF makes the device non connectable.

CVC_CFG (type) [(key) (length)]

Read or write the CVC configuration stored on the module.

type can be WB or NB. If only type parameter is supplied all 4 config keys for this type will be displayed.

If key and length parameters are also present, the key indicated will be written with a value of size length.

key can be 0 - 3

length is in 16 bits word and can be 0 - 64. 0 will delete the key.

The CVC_CFG command will reply with PENDING. The value of the pskey is expected, each word in hexadecimal space separated. A carriage return has to be supplied at the end. OK will be returned if the operation is a success and error code otherwise.

Note that you can send the data into chunks. After each, if Audio Agent is still expecting data, it will reply PENDING. When all data has been received, it replies OK.

DFU

Causes a reset to make the device boot in DFU 1 mode

DISCOVERABLE (mode)

ON puts the module in discoverable mode

OFF makes the device non discoverable.

ENTER_DATA_MODE (link)

Configure the behaviour of the specified link to be in Data mode. The parameter link can be any active BLE, iAP or SPP link. In Data mode, Audio Agent sends the data received through the UART interface directly to the remote device and prints the data received without handling it. Note that hardware flow control on the UART interface should be enabled in Data mode.

HID_DESC (size)

Sets the USB descriptor to use when acting as a hid device. Size is the length of binary data following (similar to Send when using raw data). By default a USB descriptor for a simple keyboard is loaded. When using this command any previously loaded USB descriptor is deleted. Any USB descriptor loaded with this command is not persistent across a reset.

HID_READ (BT_addr)

Reads USB descriptor from SDP of the remote HID device with address BT_addr.

HELP

Returns available list of commands.

GET (config_name)

Reads the value of a configuration parameter.

IAP [Parameter=value]

Set iAP parameters. These are the parameters that identify the device for iOS and iOS application. Maximum sizes of configurations in bytes/chars:

ACCESSORY_NAME 48 characters

MANUFACTURER_NAME 48 characters

MODEL_NAME 48 characters

SERIAL_NO 16 characters

SEED_ID 10 characters

PROTOCOL_STRING 48 characters

HARDWARE_VER 3 characters

FIRMWARE_VER 3 characters

If no parameter is provided, all parameters are displayed.

Refer to the Application Note on iAP for more information.

IAP_APP_REQ [protocol]

This command will send a request to the iOs device to open an application with the specified protocol (works only with iAP2)s. If no protocol is specified, the default protocol set with the IAP command will be used.

INQUIRY [timeout] [(filter) (value)] [max_results]

Searches Bluetooth devices in the area. The command will return PENDING and an INQUIRY notification will be received for each device found.

All parameters are optional. If not provided, default values are used.

timeout: Inquiry stops after timeout x1.28s. (value between 1 and 48. 10 by default)

filter and value: Filter inquiry notifications. No filter by default.

  • 0 - No filter. value is ignored.

  • 1 - Filter the results by name. value is a string, for example, if the string is “BC-“, only devices with a name starting with “BC-“ will be shown. Spaces are not allowed.

  • 2 - Filter the results by class of device. value is the COD.

  • 3 - Filter the results by RSSI. For example 72 to filter the device with an RSSI value inferior to -72dB.

  • 4 - Show only TWS devices. value is the ON or OFF.

max_results: Maximum number of inquiry results. 16 by default. Set to zero to indicate unlimited number of devices.

LICENSE [type] [=value]

Sets or returns the APTX or CVC license.

Type can be any of the following:

  • CVC: Sets or gets the CVC license.

  • APTX: Sets or gets the APTX license.

If parameter value is provided along with parameter type, the command updates the specified license to the one provided by the user in the value parameter.

A valid license has the following format: XXXX XXXX XXXX XXXX XXXX Where X is any hexadecimal digit. If no parameters are provided, the current CVC and APTX licenses are returned.

LINK_POLICY (device) (nb_entries)

Sets a link policy power table for a connection. By default Audio Agent uses its own default values. But theses can be changed with this command. The link policy power table allows the device to switch between different power modes.

device: index of the remote device

nb_entries: Number of entries in the power table (max. 8)

This command will return PENDING and expect the entries separated by <CR>.

Each entry shall have the following format in hex: (state) (min_interval) (max_interval) (attempt) (timeout) (time)

state: The power mode

  • 00 : active mode

  • 01 : sniff mode

  • FF : passive mode

min_interval: Sniff minimum interval Time = N x 0.625. Range 0x0002 to 0xFFFE. Only even values are valid. Only used if state is sniff mode.

max_interval: Sniff maximum interval Time = N x 0.625. Range 0x0002 to 0xFFFE. Only even values are valid. Only used if state is sniff mode.

attempt: Number of baseband receive slots for sniff attempt. Length = N * 1.25 msec. Range 0x0001 to 0x7FFF. Only used if state is sniff mode.

timeout: Number of baseband receive slots for sniff timeout. Length = N * 1.25 msec. Range 0x0001 to 0x7FFF. Only used if state is sniff mode.

time: The time spent in this state of the power table, in seconds. This must be 0 for the last entry in the table.

The command returns OK when all the entries have been successfully retrieved (see example).

LIST

Lists paired devices in the format LIST (BT addr) (Space separated list of supported profiles).

MM_CFG (key) [(length)]

Read or write the Music Manager configuration stored on the module.

key is the number of the DSP PSKey. It can be between 24 and 38. If only key is supplied the value of the key is displayed.

If length is also present, the key indicated will be written with a value of size length. length is in 16 bits word and can be 0 - 64. 0 will delete the key. The MM_CFG command will reply with PENDING. The value of the pskey is expected, each word in hexadecimal space separated. A carriage return has to be supplied at the end. OK will be returned if the operation is a success and error code otherwise. Note that you can send the data into chunks. After each, if Audio Agent is still expecting data, it will reply PENDING. When all data has been received, it replies OK.

MUSIC (link_ID)(instruction)

Controls the music stream state and sends AVRCP instructions (PLAY, PAUSE, STOP, FORWARD, BACKWARD, FF_PRESS, FF_RELEASE, REW_PRESS and REW_RELEASE).

NAME (BT_addr)

Returns the friendly name of device with the provided Bluetooth address

OPEN (BT_addr) (profile) [type]

Establishes a connection with a given Bluetooth address for a certain profile.

BT_addr: Bluetooth address formatted as 12 Hexadecimal digits with no separators (e.g.: 3859F9CCB893).

profile: Bluetooth profile. Can be: HFP, AGHFP, A2DP, AVRCP, BLE, SPP, MAP, HFP, PBAP 2 , HID or IAP. If profile is left blank, SPP will be assumed.

type (optional): Type of address

  • 0 – public address

  • 1 – random address

Note that type is only used for BLE connections. It corresponds to the type in the scan results.

Automatically put Audio Agent in connectable mode. Audio Agent will become also discoverable if attempting to connect to an unpaired device.

PAIR (BT_addr)

Enter connectable and discoverable mode and attempt to pair with the device that has the Bluetooth address given as parameter (without opening any profile).

PASSKEY (type) (key)

This function is used to respond to a SSP request (when SSP_CAPS is not equal to 3). Use type = 0 for a confirmation type and key = 0 to reject or key = 1 to accept the pairing. Use type = 1 and followed by 6 digit passkey to confirm the pairing with your key.

PIO (PIOx) (state)

Sets the specified PIO pin to the specified state.

  • PIO: Output PIO pin index.

  • State: ON to set (level high), OFF to reset (level low).

Before using this command, GPIO control must be disabled.

POWER (status) [status_ble]

Turn Bluetooth functionalities ON or OFF.

If one parameter is provided it will be applied to both Classic and BLE functionalities. If two parameters are given, the first one is for Classic and the second one is for BLE. Note that the second parameter is optional and has no effect if BLE is not enabled.

OFF Disconnects all active connections and puts the device in limbo mode, where it is not connectable, or discoverable. As a consequence, UART commands that cannot be executed are rejected.

ON Returns the device to a connectable state.

PB_PULL (link_id)<repository><phonebook> <maxlist><start index><filter> 3

Downloads the phonebook from the connected device. The default parameters are: Repository: 1 = local to the device (uint8) Phonebook: 1 = phonebook (uint8) Max list: 0x1000 entries (uint16) Start index: 0x0000 (uint16) Filter: 0x0087 = version, name, full name and phone number (uint16)

This command will send the downloaded phonebook in raw format to the host. Received data will be surrounded by: PB_PULL_START <link_id> and PB_PULL_END <link_id> When the download is finished or aborted the event PB_PULL_OK <link_id> will be sent.

For the full description of the parameters, look at the PBAP section.

Note that the phonebook download requires a baud rate of 115200 or above. Lower baud rates can cause the UART to stall and lose phonebook data.

PB_ABORT (link_id)

Aborts an active phonebook download. By default, the PBAP profile will not be closed if an active download is in process. Aborting the operation is required before closing the pbap profile. Link_id is the PBAP link id in status

RESET

Resets the device.

RESTORE

Resets and restores the configuration parameters to default factory settings.

ROLE (link_id)[role]

Changes the current role for a particularclassic connection. If role is not provided, a notification will be sent with the current role of the local device.

link id: A2DP, AVRCP, HFP, SPP or iAP link.

role(optional):

  • M - Change the role of the local device to be the master of the link.

  • S - Change the role of the local device to be the slave of the link.

A notification will be sent if the new role is different from the current role.

ROUTE (link_id/value) [link_2]

Select which audio routing to apply. When an audio routing is applied, automatic-routing is disabled. You can re-enable the automatic-routing using the value 0 as parameter.

The parameter(s) can be either a link_id (A2DP or AG/HFP) or two A2DP source link_id (Dual Stream) or one of the following special values to route the audio stream:

  • 0 – Automatic routing

  • 1 – Analog input to Analog output

  • 2 – Digital interface to Analog interface (bidirectional)

  • 3 – Digital input to Digital output

  • 4 – Digital input to Analog output

  • 5 – USB to Analogue out

  • 6 – USB to Digital out

Note: Music Manager and TONES features are not supported for the special case 2 and 3.

Note2: If a TWS connection is established, the audio will be automatically forwarded with ROUTE 1 or any A2DP link in Sink mode.

RSSI (link_id)

Returns the receiver signal Strength of the link. -70dBm is a good link, -80dBm is a poor link.
SCAN (timeout) [raw_data] [audio_agent_filter] | Searches BLE-enabled devices in the area for maximum period
of time (given in seconds).

raw_data and audio_agent_filter are optional parameters. They are
set to OFF if they are not provided.
raw_data can be used to retrieve the raw advertising packets.

audio_agent_filter can be used to look only for Audio Agent devices.

Following this command, a SCAN notification is received when
an advertising device is found.

Please note that this command is only available when the device
is configured in central mode.

SEND (link) (string)

Sends a string to a device through the specified profile. The parameter link can be any active SPP, BLE link or iAP link.

SEND_RAW (link) (nb_bytes)

Define the number of bytes (up to 255) that will be sent to the device through the specified profile. The parameter link can be any active BLE, SPP, iAP or HID link. After this command, the next nb_bytes received over UART are sent to the remote device.

SET (config)=value

Sets a new value to a configuration parameter.

SPEECH_REC (value)

The value can be ON or OFF to respectively activate and deactivate the Speech Recognition.

SSRD (size)

Set the scan response data (BLE Peripheral mode only).

size: 0 to 31 bytes. 0 will delete the scan response data otherwise the returns PENDING and the data received after this command is used to overwrite the scan response data. Returns OK when the data is fully retrieved.

STATUS [param]

Returns the state of the device:

STATE CONNECTED[n] CONNECTABLE[ON/OFF] DISCOVERABLE[ON/OFF] BLE[ble_state]

Classic Bluetooth: Where n is the number of devices connected. The CONNECTABLE and DISCOVERABLE states can be ON or OFF.

BLE: ble_state can be OFF, IDLE, ADVERTISING or CONNECTED.

And a link status for each established links in the format:

LINK (link_id) (state) (profile) (BT_Addr) (Additional info)

Where state can be: CONNECTED, DISCONNECTED or LINK_LOSS. Additional information depends on the profile: Streaming status, codec and sample rate for A2DP/TWS. Call state and codec for AG/HFP. Playing status for AVRCP. MTU size for BLE.

param can be any of the following:

  • A link.

  • A profile identifier. (SPP, HFP, A2DP…)

  • A device identifier (RES, DEV0, DEV1, DEV2)

When param is supplied, the status command returns the relevant information associated to the value of param

TOGGLE_VR (link)

Start/Stop Voice call command on the phone. The link provided must be an HFP link.

TONE (flag) (value) (flag) (value)

Plays a tone based on the input. A tone must have at least 1 note. A note must have a length parameter.

Please refer to Appendix B for full information regarding, flags, accepted values and descriptions.

Flags :

  • Tempo TE 0 – 4095

  • Timbre TI 0 – 7

  • Volume V 0 – 255

  • Decay D 00 – FF (enter value in hex 4 )

  • Note N A – F + octave 0 – 9 eg AF7, A7, AS7

  • Length L 1,2,4…64 or 3,6,12…96 triplets

Please note that this command will return an error if you have used the ROUTE command to route the analog interface to the digital interface (ROUTE 2).

UNPAIR [addr]

If the Bluetooth address provided currently exists in the paired device list it is removed, otherwise the user is notified that the Bluetooth address provided could not be found in the PDL.

If no parameters are provided, clears all of the Bluetooth addresses from the paired devices list.

VOLUME [link] [command]

Get or set the volume.

When the VOLUME command is used without parameters, it lists the volumes of the A2DP, HFP and AGHFP links currently connected.

If a link is provided, it will display the volume of the link. Note that link can also be equal to 1 for the volume when using the ROUTE command (ROUTE 1/4).

The volume of a link can be changed when a command is also provided. The parameter command can be any of the following:

  • UP to increase the volume on the specified link by one.

  • DOWN to decrease the volume on the specified link by one.

  • An hexadecimal value between 0 and the maximum number of steps defined for the profile.

The number of volume steps can be configured for the A2DP profile in BT_VOL_CONFIG. Otherwise it is 15 steps.

VERSION

Returns information on the firmware version number and the Bluetooth address of the device.

WRITE

Store configurations.
1

DFU allows downloading a new firmware upgrades onto the Bluetooth module via the UART interface and allows users to upgrade audio agent to new releases.

2

PBAB requires an active HFP connection.

3

The phonebook download requires a baud rate of 115200 or above. Lower baud rates can cause the UART to stall and lose phonebook data.

4

Parsed as fixed point of the following format in binary bbbb.bbbb or hexadecimal X.X