Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bluetooth: CCP: Add read bearer provider name for the CCP client #79462

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

Bluetooth: CCP: Add read bearer provider name for the CCP client #79462

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ad74b1d
Bluetooth: CCP: Introduce new CCP API
Thalley Aug 15, 2024
d13c6f3
Bluetooth: CCP: Initial CCP Client implemenation
Thalley Aug 15, 2024
605ccf5
Bluetooth: CCP: Add support for set/get provider name
Thalley Oct 2, 2024
0902ef0
Bluetooth: CCP: Client: Add get_bearers
Thalley Oct 8, 2024
07a26bd
Bluetooth: CCP: Client: Add support for get provider name
Thalley Oct 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions MAINTAINERS.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,7 @@ Bluetooth Host:
- doc/connectivity/bluetooth/shell/audio/
- samples/bluetooth/bap*/
- samples/bluetooth/cap*/
- samples/bluetooth/ccp*/
- samples/bluetooth/hap*/
- samples/bluetooth/hci_*/
- samples/bluetooth/pbp*/
Expand Down Expand Up @@ -481,6 +482,7 @@ Bluetooth Audio:
- doc/connectivity/bluetooth/shell/audio/
- samples/bluetooth/bap*/
- samples/bluetooth/cap*/
- samples/bluetooth/ccp*/
- samples/bluetooth/hap*/
- samples/bluetooth/pbp*/
- samples/bluetooth/tmap*/
Expand Down
11 changes: 7 additions & 4 deletions doc/connectivity/bluetooth/api/audio/bluetooth-le-audio-arch.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,7 @@ GAF and the top layer profiles gave been implemented in Zephyr with the followin
cluster=true;
label="CCP";
style=solid;
CCP_H [label="ccp.h"];
TBS_H [label="tbs.h"];
}
}
Expand Down Expand Up @@ -331,6 +332,7 @@ GAF and the top layer profiles gave been implemented in Zephyr with the followin
CAP_H -> MCS_H;
CAP_H -> MCC_H;
CAP_H -> MP_H;
CAP_H -> CCP_H;
CAP_H -> TBS_H;
CAP_H -> BAP_H;
CAP_H -> BAP_PRESET_H;
Expand All @@ -341,6 +343,7 @@ GAF and the top layer profiles gave been implemented in Zephyr with the followin
CSIP_H -> MCS_H;
CSIP_H -> MCC_H;
CSIP_H -> MP_H;
CSIP_H -> CCP_H;
CSIP_H -> TBS_H;
CSIP_H -> BAP_H;
CSIP_H -> BAP_PRESET_H;
Expand Down Expand Up @@ -719,12 +722,12 @@ Bluetooth Audio Stack.
| | | | | - Shell Module | |
| | | | | - BSIM test | |
+--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
| CCP | Call Control Server | 1.0 | 3.0 | - Feature complete | - API refactor |
| | | | | - Shell Module | - Sample Application |
| CCP | Call Control Server | 1.0 | 3.0 | - Feature complete | - API refactor (in progress) |
| | | | | - Shell Module | - Sample Application (in progress) |
| | | | | - BSIM test | |
| +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
| | Call Control Client | 1.0 | 3.0 | - Feature complete | - API refactor |
| | | | | - Shell Module | - Sample Application |
| | Call Control Client | 1.0 | 3.0 | - Feature complete | - API refactor (in progress) |
| | | | | - Shell Module | - Sample Application (in progress) |
| | | | | - BSIM test | |
+--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
| MCP | Media Control Server | 1.0 | 3.0 | - Feature complete | - API refactor |
Expand Down
1 change: 1 addition & 0 deletions doc/connectivity/bluetooth/bluetooth-shell.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ For specific Bluetooth functionality see also the following shell documentation
shell/audio/csip.rst
shell/audio/gmap.rst
shell/audio/mcp.rst
shell/audio/tbs.rst
shell/audio/tmap.rst
shell/audio/pbp.rst
shell/classic/a2dp.rst
Expand Down
266 changes: 60 additions & 206 deletions doc/connectivity/bluetooth/shell/audio/ccp.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,89 +1,32 @@
Bluetooth: Call Control Profile Shell
#####################################

This document describes how to run the call control functionality, both as
a client and as a (telephone bearer service (TBS)) server. Note that in the
examples below, some lines of debug have been removed to make this shorter
and provide a better overview.
Call Control Server
*******************
The Call Control Server is a role that typically resides on devices that can make calls,
including calls from apps such as Skype, e.g. (smart)phones and PCs,
which are typically GAP Central devices.

Telephone Bearer Service Client
*******************************
Using the Call Control Server
=============================
The Server can be controlled locally, or by a remote device (when in a call). For
example a remote device may initiate a call to the server,
or the Server may initiate a call to remote device, without a client.

The telephone bearer service client will typically exist on a resource
restricted device, such as headphones, but may also exist on e.g. phones or
laptops. The call control client will also thus typically be the advertiser.
The client can control the states of calls on a server using the call control
point.

It is necessary to have :kconfig:option:`CONFIG_BT_TBS_CLIENT_LOG_LEVEL_DBG`
enabled for using the client interactively.

Using the telephone bearer service client
=========================================

When the Bluetooth stack has been initialized (:code:`bt init`),
and a device has been connected, the telephone bearer service client can
discover TBS on the connected device calling :code:`tbs_client discover`, which
will start a discovery for the TBS UUIDs and store the handles, and optionally
subscribe to all notifications (default is to subscribe to all).

Since a server may have multiple TBS instances, most of the tbs_client commands
will take an index (starting from 0) as input. Joining calls require at least 2
call IDs, and all call indexes shall be on the same TBS instance.

A server will also have a GTBS instance, which is an abstraction layer for all
the telephone bearers on the server. If the server has both GTBS and TBS,
the client may subscribe and use either when sending requests if
:code:`BT_TBS_CLIENT_GTBS` is enabled.
For all commands that take an optional :code:`index`, if the index is not supplied then it defaults
to :code:`0` which is the GTBS bearer.

.. code-block:: console

tbs_client --help
tbs_client - Bluetooth TBS_CLIENT shell commands
ccp_call_control_server --help
ccp_call_control_server - Bluetooth CCP Call Control Server shell commands
Subcommands:
discover :Discover TBS [subscribe]
set_signal_reporting_interval :Set the signal reporting interval
[<{instance_index, gtbs}>] <interval>
originate :Originate a call [<{instance_index, gtbs}>]
<uri>
terminate :terminate a call [<{instance_index, gtbs}>]
<id>
accept :Accept a call [<{instance_index, gtbs}>] <id>
hold :Place a call on hold [<{instance_index,
gtbs}>] <id>
retrieve :Retrieve a held call [<{instance_index,
gtbs}>] <id>
read_provider_name :Read the bearer name [<{instance_index,
gtbs}>]
read_bearer_uci :Read the bearer UCI [<{instance_index, gtbs}>]
read_technology :Read the bearer technology [<{instance_index,
gtbs}>]
read_uri_list :Read the bearer's supported URI list
[<{instance_index, gtbs}>]
read_signal_strength :Read the bearer signal strength
[<{instance_index, gtbs}>]
read_signal_interval :Read the bearer signal strength reporting
interval [<{instance_index, gtbs}>]
read_current_calls :Read the current calls [<{instance_index,
gtbs}>]
read_ccid :Read the CCID [<{instance_index, gtbs}>]
read_status_flags :Read the in feature and status value
[<{instance_index, gtbs}>]
read_uri :Read the incoming call target URI
[<{instance_index, gtbs}>]
read_call_state :Read the call state [<{instance_index, gtbs}>]
read_remote_uri :Read the incoming remote URI
[<{instance_index, gtbs}>]
read_friendly_name :Read the friendly name of an incoming call
[<{instance_index, gtbs}>]
read_optional_opcodes :Read the optional opcodes [<{instance_index,
gtbs}>]


In the following examples, notifications from GTBS is ignored, unless otherwise
specified.

Example usage
init : Initialize CCP Call Control Server
set_bearer_name : Set bearer name [index] <name>
get_bearer_name : Get bearer name [index]


Example Usage
=============

Setup
Expand All @@ -92,147 +35,58 @@ Setup
.. code-block:: console

uart:~$ bt init
uart:~$ bt advertise on
Advertising started

When connected
--------------

Placing a call:

.. code-block:: console

uart:~$ tbs_client discover
<dbg> bt_tbs_client.primary_discover_func: Discover complete, found 1 instances (GTBS found)
<dbg> bt_tbs_client.discover_func: Setup complete for 1 / 1 TBS
<dbg> bt_tbs_client.discover_func: Setup complete GTBS
uart:~$ tbs_client originate 0 tel:123
<dbg> bt_tbs_client.notify_handler: Index 0
<dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the dialing state with URI tel:123
<dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the originate opcode for call 0x00
<dbg> bt_tbs_client.notify_handler: Index 0
<dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the alerting state with URI tel:123
<call answered by peer device, and status notified by TBS server>
<dbg> bt_tbs_client.notify_handler: Index 0
<dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the active state with URI tel:123

Placing a call on GTBS:

.. code-block:: console

uart:~$ tbs_client originate 0 tel:123
<dbg> bt_tbs_client.notify_handler: Index 0
<dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the dialing state with URI tel:123
<dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the originate opcode for call 0x00
<dbg> bt_tbs_client.notify_handler: Index 0
<dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the alerting state with URI tel:123
<call answered by peer device, and status notified by TBS server>
<dbg> bt_tbs_client.notify_handler: Index 0
<dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the active state with URI tel:123

It is necessary to set an outgoing caller ID before placing a call.

Accepting incoming call from peer device:

.. code-block:: console

<dbg> bt_tbs_client.incoming_uri_notify_handler: tel:123
<dbg> bt_tbs_client.in_call_notify_handler: tel:456
<dbg> bt_tbs_client.friendly_name_notify_handler: Peter
<dbg> bt_tbs_client.current_calls_notify_handler: Call 0x05 is in the incoming state with URI tel:456
uart:~$ tbs_client accept 0 5
<dbg> bt_tbs_client.call_cp_callback_handler: Status: success for the accept opcode for call 0x05
<dbg> bt_tbs_client.current_calls_notify_handler: Call 0x05 is in the active state with URI tel

uart:~$ ccp_call_control_server init
Registered GTBS bearer
Registered bearer[1]
uart:~$ bt connect xx:xx:xx:xx:xx:xx public

Terminate call:
Setting and getting the bearer name
-----------------------------------

.. code-block:: console

uart:~$ tbs_client terminate 0 5
<dbg> bt_tbs_client.termination_reason_notify_handler: ID 0x05, reason 0x06
<dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the terminate opcode for call 0x05
<dbg> bt_tbs_client.current_calls_notify_handler:

Telephone Bearer Service (TBS)
******************************
The telephone bearer service is a service that typically resides on devices that
can make calls, including calls from apps such as Skype, e.g. (smart)phones and
PCs.

It is necessary to have :kconfig:option:`CONFIG_BT_TBS_LOG_LEVEL_DBG` enabled
for using the TBS server interactively.

Using the telephone bearer service
==================================
TBS can be controlled locally, or by a remote device (when in a call). For
example a remote device may initiate a call to the device with the TBS server,
or the TBS server may initiate a call to remote device, without a TBS_CLIENT client.
The TBS implementation is capable of fully controlling any call.
Omitting an index for commands where a :code:`<instance_index>` can be supplied, defaults to the
GTBS bearer.
uart:~$ ccp_call_control_server get_bearer_name
Bearer[0] name: Generic TBS
uart:~$ ccp_call_control_server set_bearer_name "New name"
Bearer[0] name: New name
uart:~$ ccp_call_control_server get_bearer_name
Bearer[0] name: New name
uart:~$ ccp_call_control_server get_bearer_name 1
Bearer[1] name: Telephone Bearer #1
uart:~$ ccp_call_control_server set_bearer_name 1 "New TBS name"
Bearer[1] name: New TBS name
uart:~$ ccp_call_control_server get_bearer_name 1
Bearer[1] name: New TBS name


Call Control Client
*******************
The Call Control Client is a role that typically resides on resource contrained devices such as
earbuds or headsets.

Using the Call Control Client
=============================
The Client can control a remote CCP server device.
For example a remote device may have an incoming call that can be accepted by the Client.

.. code-block:: console

tbs --help
tbs - Bluetooth TBS shell commands
uart:~$ ccp_call_control_client --help
ccp_call_control_client - Bluetooth CCP Call Control Client shell commands
Subcommands:
init :Initialize TBS
authorize :Authorize the current connection
accept :Accept call <call_index>
terminate :Terminate call <call_index>
hold :Hold call <call_index>
retrieve :Retrieve call <call_index>
originate :Originate call [<instance_index>] <uri>
join :Join calls <id> <id> [<id> [<id> [...]]]
incoming :Simulate incoming remote call [<{instance_index,
gtbs}>] <local_uri> <remote_uri>
<remote_friendly_name>
remote_answer :Simulate remote answer outgoing call <call_index>
remote_retrieve :Simulate remote retrieve <call_index>
remote_terminate :Simulate remote terminate <call_index>
remote_hold :Simulate remote hold <call_index>
set_bearer_provider_name :Set the bearer provider name [<{instance_index,
gtbs}>] <name>
set_bearer_technology :Set the bearer technology [<{instance_index,
gtbs}>] <technology>
set_bearer_signal_strength :Set the bearer signal strength [<{instance_index,
gtbs}>] <strength>
set_status_flags :Set the bearer feature and status value
[<{instance_index, gtbs}>] <feature_and_status>
set_uri_scheme :Set the URI prefix list <bearer_idx> <uri1 [uri2
[uri3 [...]]]>
print_calls :Output all calls in the debug log

Example Usage
=============

Setup
-----
discover : Discover GTBS and TBS on remote device

.. code-block:: console

uart:~$ bt init
uart:~$ bt connect xx:xx:xx:xx:xx:xx public

When connected
--------------

Answering a call for a peer device originated by a client:
Example Usage when connected
============================

.. code-block:: console

<dbg> bt_tbs.write_call_cp: Index 0: Processing the originate opcode
<dbg> bt_tbs.originate_call: New call with call index 1
<dbg> bt_tbs.write_call_cp: Index 0: Processed the originate opcode with status success for call index 1
uart:~$ tbs remote_answer 1
TBS succeeded for call_id: 1

Incoming call from a peer device, accepted by client:
uart:~$ ccp_call_control_client discover
Discovery completed with GTBS and 1 TBS bearers

.. code-block:: console

uart:~$ tbs incoming 0 tel:123 tel:456 Peter
TBS succeeded for call_id: 4
<dbg> bt_tbs.bt_tbs_remote_incoming: New call with call index 4
<dbg> bt_tbs.write_call_cp: Index 0: Processed the accept opcode with status success for call index 4
uart:~$ ccp_call_control_client read_bearer_name
Bearer 0x20046254 name: Generic TBS
uart:~$ ccp_call_control_client read_bearer_name 1
Bearer 0x20046256 name: Telephone Bearer #1
Loading
Loading