From: "Frédéric Danis" <frederic.danis@linux.intel.com>
To: linux-bluetooth@vger.kernel.org
Subject: [PATCH v18 01/16] doc: Add telephony interface design document
Date: Thu, 23 Aug 2012 16:38:50 +0200 [thread overview]
Message-ID: <1345732745-28706-2-git-send-email-frederic.danis@linux.intel.com> (raw)
In-Reply-To: <1345732745-28706-1-git-send-email-frederic.danis@linux.intel.com>
---
Makefile.am | 2 +-
doc/audio-telephony-design.txt | 318 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 319 insertions(+), 1 deletion(-)
create mode 100644 doc/audio-telephony-design.txt
diff --git a/Makefile.am b/Makefile.am
index 4977a05..aae19f9 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -385,7 +385,7 @@ EXTRA_DIST += doc/manager-api.txt \
doc/network-api.txt doc/input-api.txt doc/audio-api.txt \
doc/control-api.txt doc/hfp-api.txt doc/health-api.txt \
doc/sap-api.txt doc/media-api.txt doc/assigned-numbers.txt \
- doc/supported-features.txt
+ doc/supported-features.txt doc/audio-telephony-design.txt
AM_YFLAGS = -d
diff --git a/doc/audio-telephony-design.txt b/doc/audio-telephony-design.txt
new file mode 100644
index 0000000..45e79ca
--- /dev/null
+++ b/doc/audio-telephony-design.txt
@@ -0,0 +1,318 @@
+Telephony Interface Design
+**************************
+
+Introduction
+============
+
+The aim of this document is to briefly describe the telephony interface which
+will allow external application to implement telephony related profiles
+(headset, handsfree, dial-up networking and sim access).
+
+
+The goal
+========
+
+Previous version of headset code in BlueZ needs the implementation of an AT
+parser for each modem target or external telephony application (Maemo, oFono)
+which is not the aim of Bluez.
+
+The telephony interface allows BlueZ to focus on Bluetooth communication part
+(connection, disconnection, authentication, authorization) and let external
+application (i.e. oFono) take charge of the Telephony tasks (AT parsing and
+modem specific code).
+This will allow code to be simpler, easier to maintain and debug in both BlueZ
+and telephony application.
+
+
+Design
+======
+
+External applications, which should implement AT parsing and telephony part
+will have to register an org.bluez.TelephonyAgent using this new interface.
+This will setup a SDP record for the profile and a RFCOMM server listening for
+incoming connection.
+
+When a new device is connected, NewConnection method of TelephonyAgent is
+called. The telephony agent must reply with a TelephonyConnection object after
+proper communication establishment (after SLC setup completes for HFP, or
+directly for other profiles).
+
+For Headset and Handsfree profiles, the interaction with the audio component
+(i.e. PulseAudio) will be done by listening to TelephonyConnection properties
+changes.
+
+
+Flow charts
+===========
+
+Here is some flowcharts of interactions between BlueZ, telephony agent (oFono)
+and audio component (PulseAudio):
+
+ .....> Bluetooth communication between headset and phone
+ -----> Dbus messages and signals
+
+Outgoing SCO connection - HFP <= 1.5
+------------------------------------
+
+When PulseAudio needs to setup the audio connection it will call media
+transport acquire method. This will perform a SCO connection and return the SCO
+socket file descriptor to PulseAUdio.
+
+ PulseAudio BlueZ HF/AG
+ | | |
+ | transport acquire | |
+ |------------------------>| |
+ | | connect SCO |
+ | |..............>|
+ | return SCO fd | |
+ |<------------------------| |
+ | | |
+
+Incoming SCO connection - HFP <= 1.5
+------------------------------------
+
+On an incoming SCO connection the profile will change to playing state.
+On reception of this state change, PulseAudio will call media transport acquire
+method to retrieve the SCO socket file descriptor.
+
+ PulseAudio BlueZ HF/AG
+ | | |
+ | | connect SCO |
+ | |<..............|
+ | state changed signal | |
+ |<------------------------| |
+ | | |
+ | transport acquire | |
+ |------------------------>| |
+ | | |
+ | return SCO fd | |
+ |<------------------------| |
+ | | |
+
+Codec negotiation - HFP AG - HFP v1.6
+-------------------------------------------
+
+On reception of HF available codecs command (AT+BAC), the gateway may start a
+codec selection procedure which will end up by codec property update and setup
+of the correct media transport.
+When a media transport already exists and it uses a different codec, it should
+be closed before correct one is setup.
+
+ PulseAudio BlueZ oFono HF
+ | | | |
+ | | | AT+BAC=u1,u2 |
+ | | |<.............|
+ | | | |
+ | | | OK |
+ | | |.............>|
+ | | | |
+ | | | +BCS:id |
+ | | |.............>|
+ | | | |
+ | | | AT+BCS=id |
+ | | |<.............|
+ | | | |
+ | | | OK |
+ | | |.............>|
+ | | codec property | |
+ | | changed signal | |
+ | |<---------------| |
+ | configure Transport | | |
+ |<--------------------| | |
+ | | | |
+
+It may also be possible to force a codec selection procedure by calling "get
+audio codec" method of TelephonyConnection.
+
+ PulseAudio BlueZ oFono HF
+ | | | |
+ | | get codec | |
+ | |---------------->| |
+ | | | +BCS:id |
+ | | |............>|
+ | | | |
+ | | | AT+BCS=id |
+ | | |<............|
+ | | | |
+ | | | OK |
+ | | |............>|
+ | | codec property | |
+ | | changed signal | |
+ | |<----------------| |
+ | configure Transport | | |
+ |<--------------------| | |
+ | | | |
+
+Outgoing SCO connection - HFP AG - HFP v1.6
+-------------------------------------------
+
+Idem than for HFP v1.5
+
+Incoming SCO connection - HFP AG - HFP v1.6
+-------------------------------------------
+
+It is pretty the same here as for outgoing SCO connection, except that it is
+started upon reception of AT+BCC from the headset.
+
+ PulseAudio BlueZ oFono HF
+ | | | |
+ | | | AT+BCC |
+ | | |<...........|
+ | | | |
+ | | | OK |
+ | | |...........>|
+ | | connection | |
+ | | requested signal | |
+ | |<-----------------| |
+ | | | |
+ | | connect SCO |
+ | |..............................>|
+ | state changed signal | | |
+ |<---------------------| | |
+ | | | |
+ | transport acquire | | |
+ |--------------------->| | |
+ | | | |
+ | return SCO fd | | |
+ |<---------------------| | |
+
+
+Codec negotiation - HFP HF - HFP v1.6
+-------------------------------------------
+
+Codec selection procedure started by gateway will end up by codec property
+update and setup of the correct media transport.
+When a media transport already exists and it uses a different codec, it should
+be closed before correct one is setup.
+
+ PulseAudio BlueZ oFono HF
+ | | | |
+ | | | +BCS:id |
+ | | |<.............|
+ | | | |
+ | | | AT+BCS=id |
+ | | |.............>|
+ | | | |
+ | | | OK |
+ | | |<.............|
+ | | codec property | |
+ | | changed signal | |
+ | |<---------------| |
+ | configure Transport | | |
+ |<--------------------| | |
+ | | | |
+
+Outgoing SCO connection - HFP HF - HFP v1.6
+-------------------------------------------
+
+On media transport acquire, the TelephonyConnection interface is called to
+request connection from the gateway.
+Then incoming SCO socket file descriptor will be returned to PulseAudio.
+
+ PulseAudio BlueZ oFono AG
+ | | | |
+ | transport acquire | | |
+ |----------------------->| | |
+ | | request | |
+ | | connection | |
+ | |---------------->| |
+ | | | AT+BCC |
+ | | |..........>|
+ | | | |
+ | | | OK |
+ | | |<..........|
+ | | | |
+ | | connect SCO |
+ | |<............................|
+ | return SCO fd | | |
+ |<-----------------------| | |
+ | | | |
+
+Incoming SCO connection - HFP HF - HFP v1.6
+-------------------------------------------
+
+Idem than for HFP v1.5
+
+AT+NREC - HFP AG
+----------------
+
+Reception of AT+NREC will be signaled to Bluez by TelephonyConnection.
+This will update the NREC property of media transport interface (listened by
+PulseAudio).
+
+ HF oFono BlueZ PulseAudio
+ | AT+NREC | | |
+ |............>| | |
+ | | property | |
+ | | changed signal | |
+ | |--------------->| |
+ | OK | | property |
+ |<............| | changed signal |
+ | | |--------------->|
+ | | | |
+
++BSIR - HFP AG
+--------------
+
+PulseAudio can change in-band ring tone by calling SetProperty method of media
+transport interface.
+This will call SetProperty of TelephonyConnection interface, which will send the
+proper +BSIR unsolicited event.
+
+ HF oFono BlueZ PulseAudio app
+ | | | | |
+ | | | |<------------|
+ | | | SetProperty | |
+ | | |<---------------| |
+ | | SetProperty | | |
+ | |<---------------| | |
+ | +BSIR:x | | | |
+ |<............| | | |
+ | | property | | |
+ | | changed signal | | |
+ | |--------------->| | |
+ | | | | |
+
+AT+VGS,AT+VGM - HFP AG
+----------------------
+
+Reception of volume management command will be signaled to Bluez by
+TelephonyConnection.
+This will update the corresponding volume property of media transport interface
+(listened by PulseAudio).
+
+ HF oFono BlueZ PulseAudio app
+ | | | | |
+ | AT+VGS=xx | | | |
+ |............>| | | |
+ | | property | | |
+ | | changed signal | | |
+ | |--------------->| | |
+ | OK | | | |
+ |<............| | property | |
+ | | | changed signal | |
+ | | |--------------->| |
+ | | | |------------>|
+ | | | | |
+
++VGS,+VGM - HFP AG
+------------------
+
+PulseAudio can change volume by calling SetProperty method of media transport
+interface.
+This will call SetProperty of TelephonyConnection interface, which will send the
+proper +VGx unsolicited event.
+
+ HF oFono BlueZ PulseAudio app
+ | | | | |
+ | | | |<------------|
+ | | | SetProperty | |
+ | | |<---------------| |
+ | | SetProperty | | |
+ | |<---------------| | |
+ | +VGS:xx | | | |
+ |<............| property | | |
+ | | changed signal | property | |
+ | |--------------->| changed signal | |
+ | | |--------------->| |
+ | | | |------------>|
--
1.7.9.5
next prev parent reply other threads:[~2012-08-23 14:38 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-08-23 14:38 [PATCH v18 00/16] Add org.bluez.Telephony interface Frédéric Danis
2012-08-23 14:38 ` Frédéric Danis [this message]
2012-08-23 14:38 ` [PATCH v18 02/16] doc: Add telephony interface to audio-api.txt Frédéric Danis
2012-08-23 14:38 ` [PATCH v18 03/16] doc: Add HSP HS channel to assigned numbers Frédéric Danis
2012-08-23 14:38 ` [PATCH v18 04/16] audio: Remove telephony driver from headset.c Frédéric Danis
2012-08-23 14:38 ` [PATCH v18 05/16] audio: Remove dummy telephony driver Frédéric Danis
2012-08-23 14:38 ` [PATCH v18 06/16] audio: Remove maemo5 " Frédéric Danis
2012-08-23 14:38 ` [PATCH v18 07/16] audio: Remove maemo6 " Frédéric Danis
2012-08-23 14:38 ` [PATCH v18 08/16] audio: Remove oFono " Frédéric Danis
2012-08-23 14:38 ` [PATCH v18 09/16] audio: Add org.bluez.Telephony interface Frédéric Danis
2012-08-23 14:38 ` [PATCH v18 10/16] audio: Add headset audio properties to MediaTransport Frédéric Danis
2012-08-23 14:39 ` [PATCH v18 11/16] audio: Move HFP/HSP AG servers to telephony.c Frédéric Danis
2012-08-23 14:39 ` [PATCH v18 12/16] audio: Move HFP HF server " Frédéric Danis
2012-08-23 14:39 ` [PATCH v18 13/16] audio: Add DUN GW to org.bluez.Telephony Frédéric Danis
2012-08-23 14:39 ` [PATCH v18 14/16] audio: Add SAP " Frédéric Danis
2012-08-23 14:39 ` [PATCH v18 15/16] adapter: Add API to get fast connectable mode Frédéric Danis
2012-08-23 14:39 ` [PATCH v18 16/16] audio: Add fast connectable to telephony interface Frédéric Danis
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1345732745-28706-2-git-send-email-frederic.danis@linux.intel.com \
--to=frederic.danis@linux.intel.com \
--cc=linux-bluetooth@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).