[1/1] client: Update endpoint and trasport doc

Commit Message

Vlad Pruteanu Sept. 30, 2024, 2:58 p.m. UTC

From: nxf92481 <[e-mail]>

This updates the documentation for the use of endpoints and
transports according to the latest changes in their design.
---
 client/bluetoothctl-endpoint.rst  | 33 +++++++++++++++++++++++++++--
 client/bluetoothctl-transport.rst | 35 +++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 2 deletions(-)

Comments

[e-mail] Sept. 30, 2024, 4:41 p.m. UTC | #1

This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=894120

---Test result---

Test Summary:
CheckPatch                    PASS      0.44 seconds
GitLint                       PASS      0.32 seconds
BuildEll                      PASS      24.61 seconds
BluezMake                     PASS      1601.56 seconds
MakeCheck                     PASS      15.11 seconds
MakeDistcheck                 PASS      176.29 seconds
CheckValgrind                 PASS      249.67 seconds
CheckSmatch                   PASS      349.75 seconds
bluezmakeextell               PASS      119.79 seconds
IncrementalBuild              PASS      1414.52 seconds
ScanBuild                     PASS      1013.68 seconds



---
Regards,
Linux Bluetooth

[e-mail] Sept. 30, 2024, 7:50 p.m. UTC | #2

Hello:

This patch was applied to bluetooth/bluez.git (master)
by Luiz Augusto von Dentz <[e-mail]>:

On Mon, 30 Sep 2024 17:58:30 +0300 you wrote:
> From: nxf92481 <[e-mail]>
> 
> This updates the documentation for the use of endpoints and
> transports according to the latest changes in their design.
> ---
>  client/bluetoothctl-endpoint.rst  | 33 +++++++++++++++++++++++++++--
>  client/bluetoothctl-transport.rst | 35 +++++++++++++++++++++++++++++++
>  2 files changed, 66 insertions(+), 2 deletions(-)

Here is the summary with links:
  - [1/1] client: Update endpoint and trasport doc
    https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=f7028d6a0569

You are awesome, thank you!

Patch

diff --git a/client/bluetoothctl-endpoint.rst b/client/bluetoothctl-endpoint.rst
index d7865486e..907dbde34 100644
--- a/client/bluetoothctl-endpoint.rst
+++ b/client/bluetoothctl-endpoint.rst
@@ -41,7 +41,7 @@  register
 Register Endpoint.
 
 :Usage: **# register <UUID> <codec[:company]> [capabilities...]**
-:Example LC3 source:
+:Example LC3 BAP source:
 	 | **#endpoint.register 00002bcb-0000-1000-8000-00805f9b34fb 0x06**
 	 | **#Auto Accept (yes/no):** y
 	 | **#Max Transports (auto/value):** a
@@ -50,7 +50,7 @@  Register Endpoint.
 	 | **#Context (value):** 3
 	 | **#CIG (auto/value):** a
 	 | **#CIS (auto/value):** a
-:Example LC3 since with extra capabilities:
+:Example LC3 BAP sink with extra capabilities:
 	 | **#endpoint.register 00002bc9-0000-1000-8000-00805f9b34fb 0x06 "0x03 0xe5 0x03 0x00 0x02 0xe6 0x07"**
 	 | **#Enter Metadata (value/no):** n
 	 | **#Auto Accept (yes/no):** y
@@ -60,6 +60,25 @@  Register Endpoint.
 	 | **#Context (value):** 3
 	 | **#CIG (auto/value):** a
 	 | **#CIS (auto/value):** a
+:Example LC3 BAP Broadcast source:
+	 | **#endpoint.register 00001852-0000-1000-8000-00805f9b34fb 0x06**
+	 | **#Auto Accept (yes/no):** y
+	 | **#Max Transports (auto/value):** a
+	 | **#Locations:** 3
+	 | **#Supported Context (value):** 1
+:Example LC3 BAP Broadcast sink:
+	 | **#endpoint.register 00001851-0000-1000-8000-00805f9b34fb 0x06**
+	 | **#Auto Accept (yes/no):** y
+	 | **#Max Transports (auto/value):** a
+	 | **#Locations:** 3
+	 | **#Supported Context (value):** 1
+
+Note:
+
+If running the setup with an audio server that has LE Audio support (such as PipeWire) it will
+automatically register endpoints according to the configured roles. For more details
+about configuring a Broadcast Source with PipeWire check:
+https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/doc/dox/config/pipewire-props.7.md
 
 unregister
 ----------
@@ -68,6 +87,11 @@  Unregister Endpoint.
 
 :Usage: **# unregister <UUID/object>**
 
+Note:
+
+If the endpoint was registered by an audio server, it can't be unregistered from bluetoothctl.
+This must be done by the audio server as well.
+
 config
 ------
 
@@ -75,6 +99,11 @@  Configure Endpoint.
 
 :Usage: **# config <endpoint> <local endpoint> [preset]**
 
+Note:
+
+If the endpoint was registered by an audio server, it can't be configured from bluetoothctl.
+This must be done by the audio server as well.
+
 presets
 -------
 
diff --git a/client/bluetoothctl-transport.rst b/client/bluetoothctl-transport.rst
index 21ba2f701..4151dd436 100644
--- a/client/bluetoothctl-transport.rst
+++ b/client/bluetoothctl-transport.rst
@@ -42,6 +42,37 @@  Acquire transport.
 
 :Usage: **# acquire <transport> [transport1...]**
 
+Note:
+
+If running the setup with an audio server that has LE Audio support (such as PipeWire) it will
+automatically acquire transports according to the configured roles.
+
+select
+-------
+
+Select transport. For transports created on a Broadcast Sink device only. This moves
+the transport to the "broadcasting" state, pending acquire.
+
+:Usage: **# select <transport> [transport1...]**
+
+Note:
+If running the setup with an audio server that has LE Audio support (such as PipeWire), it will
+prompt it to automatically acquire the transport.
+
+unselect
+--------
+
+Unelect transport. For transports created on a Broadcast Sink device only. This moves
+the transport to the "idle" state, pending release by the audio server. If the transport
+was acquired by bluetoothctl it can be released straight away, without having to be
+unselected.
+
+:Usage: **# unselect <transport> [transport1...]**
+
+Note:
+If running the setup with an audio server that has LE Audio support (such as PipeWire), it will
+prompt it to automatically release the transport.
+
 release
 -------
 
@@ -49,6 +80,10 @@  Release transport.
 
 :Usage: **# release <transport> [transport1...]**
 
+Note:
+
+Transports acquired by an audio server, can only be released by said audio server.
+
 send
 ----