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.

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 :code:`BT_DEBUG_TBS_CLIENT` 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 may 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 :code:`BT_DEBUG_TBS` 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.

.. code-block:: console

   tbs --help
   tbs - Bluetooth TBS 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
-----

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

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