1Bluetooth: Call Control Profile Shell
2#####################################
3
4This document describes how to run the call control functionality, both as
5a client and as a (telephone bearer service (TBS)) server. Note that in the
6examples below, some lines of debug have been removed to make this shorter
7and provide a better overview.
8
9Telephone Bearer Service Client
10*******************************
11
12The telephone bearer service client will typically exist on a resource
13restricted device, such as headphones, but may also exist on e.g. phones or
14laptops. The call control client will also thus typically be the advertiser.
15The client can control the states of calls on a server using the call control
16point.
17
18It is necessary to have :kconfig:option:`CONFIG_BT_TBS_CLIENT_LOG_LEVEL_DBG`
19enabled for using the client interactively.
20
21Using the telephone bearer service client
22=========================================
23
24When the Bluetooth stack has been initialized (:code:`bt init`),
25and a device has been connected, the telephone bearer service client can
26discover TBS on the connected device calling :code:`tbs_client discover`, which
27will start a discovery for the TBS UUIDs and store the handles, and optionally
28subscribe to all notifications (default is to subscribe to all).
29
30Since a server may have multiple TBS instances, most of the tbs_client commands
31will take an index (starting from 0) as input. Joining calls require at least 2
32call IDs, and all call indexes shall be on the same TBS instance.
33
34A server will also have a GTBS instance, which is an abstraction layer for all
35the telephone bearers on the server. If the server has both GTBS and TBS,
36the client may subscribe and use either when sending requests if
37:code:`BT_TBS_CLIENT_GTBS` is enabled.
38
39.. code-block:: console
40
41   tbs_client --help
42   tbs_client - Bluetooth TBS_CLIENT shell commands
43   Subcommands:
44      discover                       :Discover TBS [subscribe]
45      set_signal_reporting_interval  :Set the signal reporting interval
46                                       [<{instance_index, gtbs}>] <interval>
47      originate                      :Originate a call [<{instance_index, gtbs}>]
48                                       <uri>
49      terminate                      :terminate a call [<{instance_index, gtbs}>]
50                                       <id>
51      accept                         :Accept a call [<{instance_index, gtbs}>] <id>
52      hold                           :Place a call on hold [<{instance_index,
53                                       gtbs}>] <id>
54      retrieve                       :Retrieve a held call [<{instance_index,
55                                       gtbs}>] <id>
56      read_provider_name             :Read the bearer name [<{instance_index,
57                                       gtbs}>]
58      read_bearer_uci                :Read the bearer UCI [<{instance_index, gtbs}>]
59      read_technology                :Read the bearer technology [<{instance_index,
60                                       gtbs}>]
61      read_uri_list                  :Read the bearer's supported URI list
62                                       [<{instance_index, gtbs}>]
63      read_signal_strength           :Read the bearer signal strength
64                                       [<{instance_index, gtbs}>]
65      read_signal_interval           :Read the bearer signal strength reporting
66                                       interval [<{instance_index, gtbs}>]
67      read_current_calls             :Read the current calls [<{instance_index,
68                                       gtbs}>]
69      read_ccid                      :Read the CCID [<{instance_index, gtbs}>]
70      read_status_flags              :Read the in feature and status value
71                                       [<{instance_index, gtbs}>]
72      read_uri                       :Read the incoming call target URI
73                                       [<{instance_index, gtbs}>]
74      read_call_state                :Read the call state [<{instance_index, gtbs}>]
75      read_remote_uri                :Read the incoming remote URI
76                                       [<{instance_index, gtbs}>]
77      read_friendly_name             :Read the friendly name of an incoming call
78                                       [<{instance_index, gtbs}>]
79      read_optional_opcodes          :Read the optional opcodes [<{instance_index,
80                                       gtbs}>]
81
82
83In the following examples, notifications from GTBS is ignored, unless otherwise
84specified.
85
86Example usage
87=============
88
89Setup
90-----
91
92.. code-block:: console
93
94   uart:~$ bt init
95   uart:~$ bt advertise on
96   Advertising started
97
98When connected
99--------------
100
101Placing a call:
102
103.. code-block:: console
104
105   uart:~$ tbs_client discover
106   <dbg> bt_tbs_client.primary_discover_func: Discover complete, found 1 instances (GTBS found)
107   <dbg> bt_tbs_client.discover_func: Setup complete for 1 / 1 TBS
108   <dbg> bt_tbs_client.discover_func: Setup complete GTBS
109   uart:~$ tbs_client originate 0 tel:123
110   <dbg> bt_tbs_client.notify_handler: Index 0
111   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the dialing state with URI tel:123
112   <dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the originate opcode for call 0x00
113   <dbg> bt_tbs_client.notify_handler: Index 0
114   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the alerting state with URI tel:123
115   <call answered by peer device, and status notified by TBS server>
116   <dbg> bt_tbs_client.notify_handler: Index 0
117   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the active state with URI tel:123
118
119Placing a call on GTBS:
120
121.. code-block:: console
122
123   uart:~$ tbs_client originate 0 tel:123
124   <dbg> bt_tbs_client.notify_handler: Index 0
125   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the dialing state with URI tel:123
126   <dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the originate opcode for call 0x00
127   <dbg> bt_tbs_client.notify_handler: Index 0
128   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the alerting state with URI tel:123
129   <call answered by peer device, and status notified by TBS server>
130   <dbg> bt_tbs_client.notify_handler: Index 0
131   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the active state with URI tel:123
132
133It is necessary to set an outgoing caller ID before placing a call.
134
135Accepting incoming call from peer device:
136
137.. code-block:: console
138
139   <dbg> bt_tbs_client.incoming_uri_notify_handler: tel:123
140   <dbg> bt_tbs_client.in_call_notify_handler: tel:456
141   <dbg> bt_tbs_client.friendly_name_notify_handler: Peter
142   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x05 is in the incoming state with URI tel:456
143   uart:~$ tbs_client accept 0 5
144   <dbg> bt_tbs_client.call_cp_callback_handler: Status: success for the accept opcode for call 0x05
145   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x05 is in the active state with URI tel
146
147
148Terminate call:
149
150.. code-block:: console
151
152   uart:~$ tbs_client terminate 0 5
153   <dbg> bt_tbs_client.termination_reason_notify_handler: ID 0x05, reason 0x06
154   <dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the terminate opcode for call 0x05
155   <dbg> bt_tbs_client.current_calls_notify_handler:
156
157Telephone Bearer Service (TBS)
158******************************
159The telephone bearer service is a service that typically resides on devices that
160can make calls, including calls from apps such as Skype, e.g. (smart)phones and
161PCs.
162
163It is necessary to have :kconfig:option:`CONFIG_BT_TBS_LOG_LEVEL_DBG` enabled
164for using the TBS server interactively.
165
166Using the telephone bearer service
167==================================
168TBS can be controlled locally, or by a remote device (when in a call). For
169example a remote device may initiate a call to the device with the TBS server,
170or the TBS server may initiate a call to remote device, without a TBS_CLIENT client.
171The TBS implementation is capable of fully controlling any call.
172Omitting an index for commands where a :code:`<instance_index>` can be supplied, defaults to the
173GTBS bearer.
174
175.. code-block:: console
176
177   tbs --help
178   tbs - Bluetooth TBS shell commands
179   Subcommands:
180      init                        :Initialize TBS
181      authorize                   :Authorize the current connection
182      accept                      :Accept call <call_index>
183      terminate                   :Terminate call <call_index>
184      hold                        :Hold call <call_index>
185      retrieve                    :Retrieve call <call_index>
186      originate                   :Originate call [<instance_index>] <uri>
187      join                        :Join calls <id> <id> [<id> [<id> [...]]]
188      incoming                    :Simulate incoming remote call [<{instance_index,
189                                    gtbs}>] <local_uri> <remote_uri>
190                                    <remote_friendly_name>
191      remote_answer               :Simulate remote answer outgoing call <call_index>
192      remote_retrieve             :Simulate remote retrieve <call_index>
193      remote_terminate            :Simulate remote terminate <call_index>
194      remote_hold                 :Simulate remote hold <call_index>
195      set_bearer_provider_name    :Set the bearer provider name [<{instance_index,
196                                    gtbs}>] <name>
197      set_bearer_technology       :Set the bearer technology [<{instance_index,
198                                    gtbs}>] <technology>
199      set_bearer_signal_strength  :Set the bearer signal strength [<{instance_index,
200                                    gtbs}>] <strength>
201      set_status_flags            :Set the bearer feature and status value
202                                    [<{instance_index, gtbs}>] <feature_and_status>
203      set_uri_scheme              :Set the URI prefix list <bearer_idx> <uri1 [uri2
204                                    [uri3 [...]]]>
205      print_calls                 :Output all calls in the debug log
206
207Example Usage
208=============
209
210Setup
211-----
212
213.. code-block:: console
214
215   uart:~$ bt init
216   uart:~$ bt connect xx:xx:xx:xx:xx:xx public
217
218When connected
219--------------
220
221Answering a call for a peer device originated by a client:
222
223.. code-block:: console
224
225   <dbg> bt_tbs.write_call_cp: Index 0: Processing the originate opcode
226   <dbg> bt_tbs.originate_call: New call with call index 1
227   <dbg> bt_tbs.write_call_cp: Index 0: Processed the originate opcode with status success for call index 1
228   uart:~$ tbs remote_answer 1
229   TBS succeeded for call_id: 1
230
231Incoming call from a peer device, accepted by client:
232
233.. code-block:: console
234
235   uart:~$ tbs incoming 0 tel:123 tel:456 Peter
236   TBS succeeded for call_id: 4
237   <dbg> bt_tbs.bt_tbs_remote_incoming: New call with call index 4
238   <dbg> bt_tbs.write_call_cp: Index 0: Processed the accept opcode with status success for call index 4
239