public inbox for linux-bluetooth@vger.kernel.org
 help / color / mirror / Atom feed
* [RFC BlueZ 00/10] New Telephony interface for HSP, HFP and CCP
@ 2025-05-28  8:59 Frédéric Danis
  2025-05-28  8:59 ` [RFC BlueZ 01/10] doc: Add new telephony related profiles interfaces Frédéric Danis
                   ` (9 more replies)
  0 siblings, 10 replies; 13+ messages in thread
From: Frédéric Danis @ 2025-05-28  8:59 UTC (permalink / raw)
  To: linux-bluetooth

This will introduce a new Telephony interface wich is intended to be
shared by the profiles able to control telephony calls.

The idea is to split the call control interface from the audio streaming,
as it is done for AVRCP and A2DP.
As for A2DP, the audio part will be delegated to the audio daemon (like
PipeWire) by the creation of new endpoints for CVSD and mSBC, LC3 endpoint
already exists.

The interface is mostly based on the one done for PipeWire's native
backend.

This will simplify the qualification of the telephony related profiles as
the qualification will no more depend on external projects, and calls can
be controlled from bluetoothctl.

A first implementation allows to dial or hangup a call using HFP.

Frédéric Danis (10):
  doc: Add new telephony related profiles interfaces
  audio/telephony: Add shared interfaces implementation
  audio/telephony: Add skeleton for HFP profile
  audio/hfp-hf: Add HFP SLC connection and event support
  audio/hfp-hf: Add dial support
  audio/hfp-hf: Add hangup all calls support
  audio/hfp-hf: Add answer a specific call support
  client/telephony: Add new submenu
  audio/hfp-hf: Remove call interface during profile disconnection
  audio/hfp-hf: Create existing call during SLC phase

 Makefile.am                       |    4 +
 Makefile.plugins                  |    5 +
 Makefile.tools                    |    9 +-
 client/bluetoothctl-telephony.rst |   95 +++
 client/main.c                     |    3 +
 client/telephony.c                |  524 ++++++++++++
 client/telephony.h                |   12 +
 configure.ac                      |    7 +
 doc/org.bluez.TelephonyAg.rst     |  200 +++++
 doc/org.bluez.TelephonyCall.rst   |  144 ++++
 profiles/audio/hfp-hf.c           | 1299 +++++++++++++++++++++++++++++
 profiles/audio/telephony.c        |  713 ++++++++++++++++
 profiles/audio/telephony.h        |  110 +++
 13 files changed, 3122 insertions(+), 3 deletions(-)
 create mode 100644 client/bluetoothctl-telephony.rst
 create mode 100644 client/telephony.c
 create mode 100644 client/telephony.h
 create mode 100644 doc/org.bluez.TelephonyAg.rst
 create mode 100644 doc/org.bluez.TelephonyCall.rst
 create mode 100644 profiles/audio/hfp-hf.c
 create mode 100644 profiles/audio/telephony.c
 create mode 100644 profiles/audio/telephony.h

-- 
2.43.0


^ permalink raw reply	[flat|nested] 13+ messages in thread
* [RFC BlueZ v2 01/27] doc: Add new telephony related profiles interfaces
@ 2025-06-27 14:51 Frédéric Danis
  2025-06-27 16:15 ` New Telephony interface for HSP, HFP and CCP bluez.test.bot
  0 siblings, 1 reply; 13+ messages in thread
From: Frédéric Danis @ 2025-06-27 14:51 UTC (permalink / raw)
  To: linux-bluetooth

These are interfaces are meant to be generic to the telephony related
"headset" profiles like HSP HS, HFP HF, and CCP.
---
v1->v2:
  - Rename org.bluez.TelephonyCall1 to org.bluez.Call1
  - Remove reference to profiles in org.bluez.TelephonyAg1 object path
  - Add profile UUID property to org.bluez.TelephonyAg1
  - Add OperatorName property to org.bluez.TelephonyAg1

 Makefile.am                   |   4 +
 doc/org.bluez.Call.rst        | 136 ++++++++++++++++++++++
 doc/org.bluez.TelephonyAg.rst | 207 ++++++++++++++++++++++++++++++++++
 3 files changed, 347 insertions(+)
 create mode 100644 doc/org.bluez.Call.rst
 create mode 100644 doc/org.bluez.TelephonyAg.rst

diff --git a/Makefile.am b/Makefile.am
index 02ad23cf2..12714ecf8 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -388,6 +388,7 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
 		doc/org.bluez.obex.Message.5 \
 		doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
 		doc/org.bluez.obex.Image.5
+man_MANS += doc/org.bluez.TelephonyAg.5 doc/org.bluez.Call.5
 endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
@@ -422,6 +423,7 @@ manual_pages += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
 		doc/org.bluez.obex.Message.5 \
 		doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
 		doc/org.bluez.obex.Image.5
+manual_pages += doc/org.bluez.TelephonyAg.5 doc/org.bluez.Call.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
 			src/main.conf profiles/network/network.conf \
@@ -505,6 +507,8 @@ EXTRA_DIST += doc/org.bluez.obex.Client.rst doc/org.bluez.obex.Session.rst \
 		doc/org.bluez.obex.AgentManager.rst doc/org.bluez.obex.Agent.rst \
 		doc/org.bluez.obex.Image.rst
 
+EXTRA_DIST += doc/org.bluez.TelephonyAg.rst doc/org.bluez.Call.rst
+
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
 		doc/pts-opp.txt
 
diff --git a/doc/org.bluez.Call.rst b/doc/org.bluez.Call.rst
new file mode 100644
index 000000000..3fcd6f6ea
--- /dev/null
+++ b/doc/org.bluez.Call.rst
@@ -0,0 +1,136 @@
+===============
+org.bluez.Call1
+===============
+
+--------------------------------------------
+BlueZ D-Bus Telephony Call API documentation
+--------------------------------------------
+
+:Version: BlueZ
+:Date: May 2025
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.Call1 [experimental]
+:Object path:	[variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/telephony_ag#/call#
+
+Methods
+-------
+
+void Answer()
+`````````````
+
+Answers an incoming call. Only valid if the state of the call is "incoming".
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+void Hangup()
+`````````````
+
+Hangs up the call.
+
+For an incoming call, the call is hung up using ATH or equivalent. For a
+waiting call, the remote party is notified by using the User Determined User
+Busy (UDUB) condition. This is generally implemented using CHLD=0.
+
+Please note that the GSM specification does not allow the release of a held
+call when a waiting call exists. This is because 27.007 allows CHLD=1X to
+operate only on active calls. Hence a held call cannot be hung up without
+affecting the state of the incoming call (e.g. using other CHLD alternatives).
+Most manufacturers provide vendor extensions that do allow the state of the
+held call to be modified using CHLD=1X or equivalent. It should be noted that
+Bluetooth HFP specifies the classic 27.007 behavior and does not allow CHLD=1X
+to modify the state of held calls.
+
+Based on the discussion above, it should also be noted that releasing a
+particular party of a held multiparty call might not be possible on some
+implementations. It is recommended for the applications to structure their UI
+accordingly.
+
+NOTE: Releasing active calls does not produce side-effects. That is the state
+of held or waiting calls is not affected. As an exception, in the case where a
+single active call and a waiting call are present, releasing the active call
+will result in the waiting call transitioning to the 'incoming' state.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+Properties
+----------
+
+string LineIdentification [readonly]
+````````````````````````````````````
+
+Contains the Line Identification information returned by the network, if
+present. For incoming calls this is effectively the CLIP. For outgoing calls
+this attribute will hold the dialed number, or the COLP if received by the
+audio gateway.
+
+Please note that COLP may be different from the dialed number. A special
+"withheld" value means the remote party refused to provide caller ID and the
+"override category" option was not provisioned for the current subscriber.
+
+string IncomingLine [readonly, optional]
+````````````````````````````````````````
+
+Contains the Called Line Identification information returned by the network.
+This is only available for incoming calls and indicates the local subscriber
+number which was dialed by the remote party. This is useful for subscribers
+which have a multiple line service with their network provider and would like
+to know what line the call is coming in on.
+
+string Name [readonly]
+``````````````````````
+
+Contains the Name Identification information returned by the network, if
+present.
+
+boolean Multiparty [readonly]
+`````````````````````````````
+
+Contains the indication if the call is part of a multiparty call or not.
+
+Notifications if a call becomes part or leaves a multiparty call are sent.
+
+string State [readonly]
+```````````````````````
+
+Contains the state of the current call.
+
+Possible values:
+
+:"active":
+
+	The call is active
+
+:"held":
+
+	The call is on hold
+
+:"dialing":
+
+	The call is being dialed
+
+:"alerting":
+
+	The remote party is being alerted
+
+:"incoming":
+
+	Incoming call in progress
+
+:"waiting":
+
+	Call is waiting
+
+:"disconnected":
+
+	No further use of this object is allowed, it will be
+	destroyed shortly
diff --git a/doc/org.bluez.TelephonyAg.rst b/doc/org.bluez.TelephonyAg.rst
new file mode 100644
index 000000000..ddb5eec0f
--- /dev/null
+++ b/doc/org.bluez.TelephonyAg.rst
@@ -0,0 +1,207 @@
+======================
+org.bluez.TelephonyAg1
+======================
+
+-----------------------------------------------------
+BlueZ D-Bus Telephony Audio Gateway API documentation
+-----------------------------------------------------
+
+:Version: BlueZ
+:Date: May 2025
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.TelephonyAg1 [experimental]
+:Object path:	[variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/telephony_ag#
+
+Methods
+-------
+
+object Dial(string number)
+``````````````````````````
+
+Call number, if number is void try to call last dialed number.
+Initiates a new outgoing call. Returns the object path to the newly created
+call.
+
+The number must be a string containing the following characters:
+`[0-9+*#,ABCD]{1,80}` The character set can contain numbers, `+`, `*`, `#`,
+`,` and the letters `A` to `D`. Besides this sanity checking no further number
+validation is performed. It is assumed that the gateway and/or the network
+will perform further validation.
+
+If number is an empty string, it will try to call last dialed number.
+
+NOTE: If an active call (single or multiparty) exists, then it is
+automatically put on hold if the dial procedure is successful.
+
+Possible Errors:
+
+:org.bluez.Error.InvalidState:
+:org.bluez.Error.InvalidArguments:
+:org.bluez.Error.NotSupported:
+:org.bluez.Error.Failed:
+
+void SwapCalls()
+````````````````
+
+Swaps Active and Held calls. The effect of this is that all calls (0 or more
+including calls in a multi-party conversation) that were Active are now Held,
+and all calls (0 or more) that were Held are now Active.
+
+GSM specification does not allow calls to be swapped in the case where Held,
+Active and Waiting calls exist. Some modems implement this anyway, thus it is
+manufacturer specific whether this method will succeed in the case of Held,
+Active and Waiting calls.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+void ReleaseAndAnswer()
+```````````````````````
+
+Releases currently active call (0 or more) and answers the currently waiting
+call. Please note that if the current call is a multiparty call, then all
+parties in the multi-party call will be released.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+void ReleaseAndSwap()
+`````````````````````
+
+Releases currently active call (0 or more) and activates any currently held
+calls. Please note that if the current call is a multiparty call, then all
+parties in the multi-party call will be released.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+void HoldAndAnswer()
+````````````````````
+
+Puts the current call (including multi-party calls) on hold and answers the
+currently waiting call. Calling this function when a user already has a both
+Active and Held calls is invalid, since in GSM a user can have only a single
+Held call at a time.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+void HangupAll()
+````````````````
+
+Releases all calls except waiting calls. This includes multiparty calls.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+void HangupActive()
+```````````````````
+
+Releases active calls. This includes multiparty active calls.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+void HangupHeld()
+`````````````````
+
+Releases held calls except waiting calls. This includes multiparty held calls.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+array{object} CreateMultiparty()
+````````````````````````````````
+
+Joins active and held calls together into a multi-party call. If one of the
+calls is already a multi-party call, then the other call is added to the
+multiparty conversation. Returns the new list of calls participating in the
+multiparty call.
+
+There can only be one subscriber controlled multi-party call according to the
+GSM specification.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.Failed
+
+void SendTones(string tones)
+````````````````````````````
+
+Sends the DTMF tones to the network. The tones have a fixed duration.
+Tones can be one of: '0' - '9', '*', '#', 'A', 'B', 'C', 'D'. The last four
+are typically not used in normal circumstances.
+
+Possible Errors:
+:org.bluez.Error.InvalidState
+:org.bluez.Error.InvalidArgs
+:org.bluez.Error.Failed
+
+Properties
+----------
+
+string UUID [readonly]
+``````````````````````
+
+UUID of the profile which the Telephony Audio Gateway is for.
+
+string State [readonly]
+```````````````````````
+
+Contains the state of the current connection.
+
+Possible values:
+
+:"connecting":
+
+	RFComm connection in progress
+
+:"slc_connecting":
+
+	Service Level Connection in progress
+
+:"connected":
+
+	RFComm and Service Level Connection are connected
+
+:"disconnecting":
+
+	No further use of this object is allowed, it will be destroyed shortly
+
+boolean Service [readonly]
+``````````````````````````
+
+Network service availability.
+
+byte Signal [readonly]
+``````````````````````
+
+Network level signal from 0 to 5.
+
+boolean Roaming [readonly]
+``````````````````````````
+
+Network roaming usage.
+
+byte BattChg [readonly]
+```````````````````````
+
+Battery level from 0 to 5.
+
+string OperatorName [readonly, optional]
+````````````````````````````````````````
+
+Operator name
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 13+ messages in thread
end of thread, other threads:[~2025-06-27 16:15 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-05-28  8:59 [RFC BlueZ 00/10] New Telephony interface for HSP, HFP and CCP Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 01/10] doc: Add new telephony related profiles interfaces Frédéric Danis
2025-05-28 10:33   ` New Telephony interface for HSP, HFP and CCP bluez.test.bot
2025-05-28  8:59 ` [RFC BlueZ 02/10] audio/telephony: Add shared interfaces implementation Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 03/10] audio/telephony: Add skeleton for HFP profile Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 04/10] audio/hfp-hf: Add HFP SLC connection and event support Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 05/10] audio/hfp-hf: Add dial support Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 06/10] audio/hfp-hf: Add hangup all calls support Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 07/10] audio/hfp-hf: Add answer a specific call support Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 08/10] client/telephony: Add new submenu Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 09/10] audio/hfp-hf: Remove call interface during profile disconnection Frédéric Danis
2025-05-28  8:59 ` [RFC BlueZ 10/10] audio/hfp-hf: Create existing call during SLC phase Frédéric Danis
  -- strict thread matches above, loose matches on Subject: below --
2025-06-27 14:51 [RFC BlueZ v2 01/27] doc: Add new telephony related profiles interfaces Frédéric Danis
2025-06-27 16:15 ` New Telephony interface for HSP, HFP and CCP bluez.test.bot

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox