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 BT_DEBUG_TBS_CLIENT enabled for using the client
interactively.
Using the telephone bearer service client
When the Bluetooth stack has been initialized (bt init),
and a device has been connected, the telephone bearer service client can
discover TBS on the connected device calling 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
BT_TBS_CLIENT_GTBS is enabled.
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
uart:~$ bt init
uart:~$ bt advertise on
Advertising started
When connected
Placing a call:
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:
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:
<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:
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 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.
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
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:
<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:~$ 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