Skip to content

Commit

Permalink
Bluetooth: CCP: Introduce new CCP API
Browse files Browse the repository at this point in the history 
The CCP API for the Call Control Profile works on top of the
TBS API, and will eventually replace parts of the TBS API.

Signed-off-by: Emil Gydesen <[email protected]>
  • Loading branch information
@Thalley
Thalley committed Sep 9, 2024
1 parent 5c4ce41 commit 1e8dcd7
Show file tree
Hide file tree
Showing 42 changed files with 1,700 additions and 221 deletions.
3 changes: 3 additions & 0 deletions doc/connectivity/bluetooth/api/audio/bluetooth-le-audio-arch.rst
View file
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
235 changes: 16 additions & 219 deletions doc/connectivity/bluetooth/api/audio/shell/ccp.rst
View file
Original file line number Diff line number Diff line change
@@ -1,208 +1,24 @@
Bluetooth: Call Control Profile
###############################

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
*******************************

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.

.. code-block:: console
tbs_client --help
tbs_client - Bluetooth TBS_CLIENT 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
=============

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
Terminate call:

.. 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.
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.

.. code-block:: console
tbs --help
tbs - Bluetooth TBS shell commands
ccp_server --help
ccp_server - Bluetooth CCP server 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
init : Initialize CCP server
Example Usage
=============
Expand All @@ -213,26 +29,7 @@ Setup
.. code-block:: console
uart:~$ bt init
uart:~$ ccp_server init
Registered GTBS bearer
Registered bearer[1]
uart:~$ bt connect xx:xx:xx:xx:xx:xx public
When connected
--------------

Answering a call for a peer device originated by a client:

.. 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:

.. 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
Loading

0 comments on commit 1e8dcd7

Please sign in to comment.