1Bluetooth: Telephone Bearer Service 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 are ignored, unless otherwise specified.
84
85Example usage
86=============
87
88Setup
89-----
90
91.. code-block:: console
92
93   uart:~$ bt init
94   uart:~$ bt advertise on
95   Advertising started
96
97When connected
98--------------
99
100Placing a call:
101
102.. code-block:: console
103
104   uart:~$ tbs_client discover
105   <dbg> bt_tbs_client.primary_discover_func: Discover complete, found 1 instances (GTBS found)
106   <dbg> bt_tbs_client.discover_func: Setup complete for 1 / 1 TBS
107   <dbg> bt_tbs_client.discover_func: Setup complete GTBS
108   uart:~$ tbs_client originate 0 tel:123
109   <dbg> bt_tbs_client.notify_handler: Index 0
110   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the dialing state with URI tel:123
111   <dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the originate opcode for call 0x00
112   <dbg> bt_tbs_client.notify_handler: Index 0
113   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the alerting state with URI tel:123
114   <call answered by peer device, and status notified by TBS server>
115   <dbg> bt_tbs_client.notify_handler: Index 0
116   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the active state with URI tel:123
117
118Placing a call on GTBS:
119
120.. code-block:: console
121
122   uart:~$ tbs_client originate 0 tel:123
123   <dbg> bt_tbs_client.notify_handler: Index 0
124   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the dialing state with URI tel:123
125   <dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the originate opcode for call 0x00
126   <dbg> bt_tbs_client.notify_handler: Index 0
127   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the alerting state with URI tel:123
128   <call answered by peer device, and status notified by TBS server>
129   <dbg> bt_tbs_client.notify_handler: Index 0
130   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x01 is in the active state with URI tel:123
131
132It is necessary to set an outgoing caller ID before placing a call.
133
134Accepting incoming call from peer device:
135
136.. code-block:: console
137
138   <dbg> bt_tbs_client.incoming_uri_notify_handler: tel:123
139   <dbg> bt_tbs_client.in_call_notify_handler: tel:456
140   <dbg> bt_tbs_client.friendly_name_notify_handler: Peter
141   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x05 is in the incoming state with URI tel:456
142   uart:~$ tbs_client accept 0 5
143   <dbg> bt_tbs_client.call_cp_callback_handler: Status: success for the accept opcode for call 0x05
144   <dbg> bt_tbs_client.current_calls_notify_handler: Call 0x05 is in the active state with URI tel
145
146
147Terminate call:
148
149.. code-block:: console
150
151   uart:~$ tbs_client terminate 0 5
152   <dbg> bt_tbs_client.termination_reason_notify_handler: ID 0x05, reason 0x06
153   <dbg> bt_tbs_client.call_cp_notify_handler: Status: success for the terminate opcode for call 0x05
154   <dbg> bt_tbs_client.current_calls_notify_handler:
155
156Telephone Bearer Service (TBS)
157******************************
158The telephone bearer service is a service that typically resides on devices that
159can make calls, including calls from apps such as Skype, e.g. (smart)phones and
160PCs.
161
162It is necessary to have :kconfig:option:`CONFIG_BT_TBS_LOG_LEVEL_DBG` enabled
163for using the TBS server interactively.
164
165Using the telephone bearer service
166==================================
167TBS can be controlled locally, or by a remote device (when in a call). For
168example a remote device may initiate a call to the device with the TBS server,
169or the TBS server may initiate a call to remote device, without a TBS_CLIENT client.
170The TBS implementation is capable of fully controlling any call.
171Omitting an index for commands where a :code:`<instance_index>` can be supplied, defaults to the
172GTBS bearer.
173
174.. code-block:: console
175
176   tbs --help
177   tbs - Bluetooth TBS shell commands
178   Subcommands:
179      init                        :Initialize TBS
180      authorize                   :Authorize the current connection
181      accept                      :Accept call <call_index>
182      terminate                   :Terminate call <call_index>
183      hold                        :Hold call <call_index>
184      retrieve                    :Retrieve call <call_index>
185      originate                   :Originate call [<instance_index>] <uri>
186      join                        :Join calls <id> <id> [<id> [<id> [...]]]
187      incoming                    :Simulate incoming remote call [<{instance_index,
188                                    gtbs}>] <local_uri> <remote_uri>
189                                    <remote_friendly_name>
190      remote_answer               :Simulate remote answer outgoing call <call_index>
191      remote_retrieve             :Simulate remote retrieve <call_index>
192      remote_terminate            :Simulate remote terminate <call_index>
193      remote_hold                 :Simulate remote hold <call_index>
194      set_bearer_provider_name    :Set the bearer provider name [<{instance_index,
195                                    gtbs}>] <name>
196      set_bearer_technology       :Set the bearer technology [<{instance_index,
197                                    gtbs}>] <technology>
198      set_bearer_signal_strength  :Set the bearer signal strength [<{instance_index,
199                                    gtbs}>] <strength>
200      set_status_flags            :Set the bearer feature and status value
201                                    [<{instance_index, gtbs}>] <feature_and_status>
202      set_uri_scheme              :Set the URI prefix list <bearer_idx> <uri1 [uri2
203                                    [uri3 [...]]]>
204      print_calls                 :Output all calls in the debug log
205
206Example Usage
207=============
208
209Setup
210-----
211
212.. code-block:: console
213
214   uart:~$ bt init
215   uart:~$ bt connect xx:xx:xx:xx:xx:xx public
216
217When connected
218--------------
219
220Answering a call for a peer device originated by a client:
221
222.. code-block:: console
223
224   <dbg> bt_tbs.write_call_cp: Index 0: Processing the originate opcode
225   <dbg> bt_tbs.originate_call: New call with call index 1
226   <dbg> bt_tbs.write_call_cp: Index 0: Processed the originate opcode with status success for call index 1
227   uart:~$ tbs remote_answer 1
228   TBS succeeded for call_id: 1
229
230Incoming call from a peer device, accepted by client:
231
232.. code-block:: console
233
234   uart:~$ tbs incoming 0 tel:123 tel:456 Peter
235   TBS succeeded for call_id: 4
236   <dbg> bt_tbs.bt_tbs_remote_incoming: New call with call index 4
237   <dbg> bt_tbs.write_call_cp: Index 0: Processed the accept opcode with status success for call index 4
238