diff mbox series

[RFC,BlueZ] doc: Add initial MediaSetup rst

Message ID 20240619113520.7617-1-iulia.tanasescu@nxp.com (mailing list archive)
State New, archived
Headers show
Series [RFC,BlueZ] doc: Add initial MediaSetup rst | expand

Checks

Context Check Description
tedd_an/pre-ci_am success Success
tedd_an/CheckPatch success CheckPatch PASS
tedd_an/GitLint success Gitlint PASS
tedd_an/BuildEll success Build ELL PASS
tedd_an/BluezMake success Bluez Make PASS
tedd_an/MakeCheck success Bluez Make Check PASS
tedd_an/MakeDistcheck success Make Distcheck PASS
tedd_an/CheckValgrind success Check Valgrind PASS
tedd_an/CheckSmatch success CheckSparse PASS
tedd_an/bluezmakeextell success Make External ELL PASS
tedd_an/IncrementalBuild success Incremental Build PASS
tedd_an/ScanBuild success Scan Build PASS

Commit Message

Iulia Tanasescu June 19, 2024, 11:35 a.m. UTC 
This proposes a new D-Bus API to be used by the BAP Broadcast Assistant
role.

The BAP Broadcast Assistant is a Master device that can have multiple
connections with BAP Scan Delegators. The Broadcast Assistant has the UI
to start scanning, enumerate Broadacast Sources, allow the user to select
a desired Source and send the stream information to one of the peers. If
the selected stream is encrypted and the peer requires a Broadcast Code
to decrypt the stream, the user should issue a command to send the code.

A new D-Bus API is necessary to allow the BAP Broadcast Assistant
implementation in BlueZ to communicate with a top level UI process.

The Broadcast Assistant in BlueZ should register a D-Bus object for each
scanned BIS that matches the Audio capabilities of a peer. Each object
should be linked with the stream and the peer device that matches the
stream capabilities.

The top level process should detect these objects and display the
information to the user. The user can issue commands to select an object
or to provide the Broadcast Code for an object.

More information on the proposed design can be found here:
https://github.com/orgs/bluez/discussions/822
---
 Makefile.am                  |  6 ++---
 doc/org.bluez.MediaSetup.rst | 45 ++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 3 deletions(-)
 create mode 100644 doc/org.bluez.MediaSetup.rst

Comments

bluez.test.bot@gmail.com June 19, 2024, 1:49 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=863411

---Test result---

Test Summary:
CheckPatch                    PASS      0.46 seconds
GitLint                       PASS      0.34 seconds
BuildEll                      PASS      24.70 seconds
BluezMake                     PASS      1578.93 seconds
MakeCheck                     PASS      12.92 seconds
MakeDistcheck                 PASS      177.76 seconds
CheckValgrind                 PASS      250.88 seconds
CheckSmatch                   PASS      353.95 seconds
bluezmakeextell               PASS      119.94 seconds
IncrementalBuild              PASS      1404.89 seconds
ScanBuild                     PASS      998.96 seconds



---
Regards,
Linux Bluetooth
Luiz Augusto von Dentz June 19, 2024, 2:52 p.m. UTC | #2 
Hi Iulia,

On Wed, Jun 19, 2024 at 7:35 AM Iulia Tanasescu <iulia.tanasescu@nxp.com> wrote:
>
> This proposes a new D-Bus API to be used by the BAP Broadcast Assistant
> role.
>
> The BAP Broadcast Assistant is a Master device that can have multiple
> connections with BAP Scan Delegators. The Broadcast Assistant has the UI
> to start scanning, enumerate Broadacast Sources, allow the user to select
> a desired Source and send the stream information to one of the peers. If
> the selected stream is encrypted and the peer requires a Broadcast Code
> to decrypt the stream, the user should issue a command to send the code.
>
> A new D-Bus API is necessary to allow the BAP Broadcast Assistant
> implementation in BlueZ to communicate with a top level UI process.
>
> The Broadcast Assistant in BlueZ should register a D-Bus object for each
> scanned BIS that matches the Audio capabilities of a peer. Each object
> should be linked with the stream and the peer device that matches the
> stream capabilities.
>
> The top level process should detect these objects and display the
> information to the user. The user can issue commands to select an object
> or to provide the Broadcast Code for an object.
>
> More information on the proposed design can be found here:
> https://github.com/orgs/bluez/discussions/822
> ---
>  Makefile.am                  |  6 ++---
>  doc/org.bluez.MediaSetup.rst | 45 ++++++++++++++++++++++++++++++++++++
>  2 files changed, 48 insertions(+), 3 deletions(-)
>  create mode 100644 doc/org.bluez.MediaSetup.rst
>
> diff --git a/Makefile.am b/Makefile.am
> index 0ae721111..217e7d2e4 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -362,7 +362,7 @@ man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
>  man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
>                 doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
>                 doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
> -               doc/org.bluez.MediaTransport.5
> +               doc/org.bluez.MediaTransport.5 doc/org.bluez.MediaSetup.5
>  man_MANS += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
>                 doc/org.bluez.GattService.5 \
>                 doc/org.bluez.GattCharacteristic.5 \
> @@ -395,7 +395,7 @@ manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
>  manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
>                 doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
>                 doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
> -               doc/org.bluez.MediaTransport.5
> +               doc/org.bluez.MediaTransport.5 doc/org.bluez.MediaSetup.5
>  manual_pages += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
>                 doc/org.bluez.GattService.5 \
>                 doc/org.bluez.GattCharacteristic.5 \
> @@ -475,7 +475,7 @@ EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
>  EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
>                 doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \
>                 doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \
> -               doc/org.bluez.MediaTransport.rst
> +               doc/org.bluez.MediaTransport.rst doc/org.bluez.MediaSetup.rst
>
>  EXTRA_DIST += doc/org.bluez.GattManager.rst doc/org.bluez.GattProfile.rst\
>                 doc/org.bluez.GattService.rst \
> diff --git a/doc/org.bluez.MediaSetup.rst b/doc/org.bluez.MediaSetup.rst
> new file mode 100644
> index 000000000..7463d7cfb
> --- /dev/null
> +++ b/doc/org.bluez.MediaSetup.rst
> @@ -0,0 +1,45 @@
> +=======================
> +org.bluez.MediaSetup
> +=======================

Let's use MediaAssistant as name:
https://github.com/orgs/bluez/discussions/822#discussioncomment-9818645

> +
> +-------------------------------------------
> +BlueZ D-Bus MediaSetup API documentation
> +-------------------------------------------
> +
> +:Version: BlueZ
> +:Date: June 2024
> +:Manual section: 5
> +:Manual group: Linux System Administration
> +
> +Interface
> +=========
> +
> +:Service:      org.bluez
> +:Interface:    org.bluez.MediaSetup1
> +:Object path:  /org/bluez/{hci0,hci1,...}/src_XX_XX_XX_XX_XX_XX/dev_YY_YY_YY_YY_YY_YY/bisZ
> +
> +Methods
> +-------
> +
> +void Select()
> +````````````````````````````````````````````````````````

How about using Push as the method name here?

> +
> +       Send stream information to the remote device.
> +
> +void SetBcode(array{byte} broadcast_code)
> +`````````````````````````````````````````````````````````
> +
> +       Send Broadcast_Code to the remote device.

Hmm, I wonder if it wouldn't be better to just have a dictionary that
you can pass to the Push method.

> +Properties
> +----------
> +
> +string State [readonly]
> +```````````````````````
> +
> +       Indicates the state of the setup. Possible values are:
> +
> +       :"idle": setup created
> +       :"pending": setup selected
> +       :"requesting": remote device requires Broadcast_Code
> +       :"active": remote device started receiving stream

We might want to add a property that refers to the MediaTransport
object, that way the application can tell what is the BIS
configuration from the transport and we don't need to duplicate them
here. The lifetime of MediaAssistant shall be the same as the
MediaTransport object it refers to, so if the transport is
removed/free so is its MediaAssistant object, we may want to document
this though because the Device object could persist if they are not
temporary but the MediaTransport objects for broadcasters are normally
considered temporary as they are not paired/bonded.

> \ No newline at end of file
> --
> 2.39.2
>
Iulia Tanasescu June 21, 2024, 1:10 p.m. UTC | #3 
Hi Luiz,

> -----Original Message-----
> From: Luiz Augusto von Dentz <luiz.dentz@gmail.com>
> Sent: Wednesday, June 19, 2024 5:53 PM
> To: Iulia Tanasescu <iulia.tanasescu@nxp.com>
> Cc: linux-bluetooth@vger.kernel.org; Claudia Cristina Draghicescu
> <claudia.rosu@nxp.com>; Mihai-Octavian Urzica <mihai-
> octavian.urzica@nxp.com>; Vlad Pruteanu <vlad.pruteanu@nxp.com>; Andrei
> Istodorescu <andrei.istodorescu@nxp.com>
> Subject: Re: [PATCH RFC,BlueZ] doc: Add initial MediaSetup rst
> 
> Hi Iulia,
> 
> On Wed, Jun 19, 2024 at 7:35 AM Iulia Tanasescu <iulia.tanasescu@nxp.com>
> wrote:
> >
> > This proposes a new D-Bus API to be used by the BAP Broadcast
> > Assistant role.
> >
> > The BAP Broadcast Assistant is a Master device that can have multiple
> > connections with BAP Scan Delegators. The Broadcast Assistant has the
> > UI to start scanning, enumerate Broadacast Sources, allow the user to
> > select a desired Source and send the stream information to one of the
> > peers. If the selected stream is encrypted and the peer requires a
> > Broadcast Code to decrypt the stream, the user should issue a command to
> send the code.
> >
> > A new D-Bus API is necessary to allow the BAP Broadcast Assistant
> > implementation in BlueZ to communicate with a top level UI process.
> >
> > The Broadcast Assistant in BlueZ should register a D-Bus object for
> > each scanned BIS that matches the Audio capabilities of a peer. Each
> > object should be linked with the stream and the peer device that
> > matches the stream capabilities.
> >
> > The top level process should detect these objects and display the
> > information to the user. The user can issue commands to select an
> > object or to provide the Broadcast Code for an object.
> >
> > More information on the proposed design can be found here:
> > https://gith/
> >
> ub.com%2Forgs%2Fbluez%2Fdiscussions%2F822&data=05%7C02%7Ciulia.tana
> ses
> >
> cu%40nxp.com%7Cc4b5189ccea94198202d08dc906f805b%7C686ea1d3bc2b
> 4c6fa92c
> >
> d99c5c301635%7C0%7C0%7C638544055766136877%7CUnknown%7CTWFp
> bGZsb3d8eyJW
> >
> IjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0
> %7C%
> >
> 7C%7C&sdata=w8yqp2HZQqouwJTFALZVB9Z32st0a3GTKm3w1TcHg10%3D&res
> erved=0
> > ---
> >  Makefile.am                  |  6 ++---
> >  doc/org.bluez.MediaSetup.rst | 45
> > ++++++++++++++++++++++++++++++++++++
> >  2 files changed, 48 insertions(+), 3 deletions(-)  create mode 100644
> > doc/org.bluez.MediaSetup.rst
> >
> > diff --git a/Makefile.am b/Makefile.am index 0ae721111..217e7d2e4
> > 100644
> > --- a/Makefile.am
> > +++ b/Makefile.am
> > @@ -362,7 +362,7 @@ man_MANS += doc/org.bluez.Adapter.5
> > doc/org.bluez.Device.5 \  man_MANS += doc/org.bluez.Media.5
> doc/org.bluez.MediaControl.5 \
> >                 doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
> >                 doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
> > -               doc/org.bluez.MediaTransport.5
> > +               doc/org.bluez.MediaTransport.5
> > + doc/org.bluez.MediaSetup.5
> >  man_MANS += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
> >                 doc/org.bluez.GattService.5 \
> >                 doc/org.bluez.GattCharacteristic.5 \ @@ -395,7 +395,7
> > @@ manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
> > manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
> >                 doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
> >                 doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
> > -               doc/org.bluez.MediaTransport.5
> > +               doc/org.bluez.MediaTransport.5
> > + doc/org.bluez.MediaSetup.5
> >  manual_pages += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
> >                 doc/org.bluez.GattService.5 \
> >                 doc/org.bluez.GattCharacteristic.5 \ @@ -475,7 +475,7
> > @@ EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
> > EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
> >                 doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \
> >                 doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \
> > -               doc/org.bluez.MediaTransport.rst
> > +               doc/org.bluez.MediaTransport.rst
> > + doc/org.bluez.MediaSetup.rst
> >
> >  EXTRA_DIST += doc/org.bluez.GattManager.rst doc/org.bluez.GattProfile.rst\
> >                 doc/org.bluez.GattService.rst \ diff --git
> > a/doc/org.bluez.MediaSetup.rst b/doc/org.bluez.MediaSetup.rst new file
> > mode 100644 index 000000000..7463d7cfb
> > --- /dev/null
> > +++ b/doc/org.bluez.MediaSetup.rst
> > @@ -0,0 +1,45 @@
> > +=======================
> > +org.bluez.MediaSetup
> > +=======================
> 
> Let's use MediaAssistant as name:
> https://github.c/
> om%2Forgs%2Fbluez%2Fdiscussions%2F822%23discussioncomment-
> 9818645&data=05%7C02%7Ciulia.tanasescu%40nxp.com%7Cc4b5189ccea941
> 98202d08dc906f805b%7C686ea1d3bc2b4c6fa92cd99c5c301635%7C0%7C0%
> 7C638544055766147461%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjA
> wMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C
> &sdata=jHOPPf1bg8SpRg4N3AP33ozX51GGUslWid9JObkRzFw%3D&reserved=
> 0
> 
> > +
> > +-------------------------------------------
> > +BlueZ D-Bus MediaSetup API documentation
> > +-------------------------------------------
> > +
> > +:Version: BlueZ
> > +:Date: June 2024
> > +:Manual section: 5
> > +:Manual group: Linux System Administration
> > +
> > +Interface
> > +=========
> > +
> > +:Service:      org.bluez
> > +:Interface:    org.bluez.MediaSetup1
> > +:Object path:
> > +/org/bluez/{hci0,hci1,...}/src_XX_XX_XX_XX_XX_XX/dev_YY_YY_YY_YY_YY_Y
> > +Y/bisZ
> > +
> > +Methods
> > +-------
> > +
> > +void Select()
> > +````````````````````````````````````````````````````````
> 
> How about using Push as the method name here?
> 
> > +
> > +       Send stream information to the remote device.
> > +
> > +void SetBcode(array{byte} broadcast_code)
> > +`````````````````````````````````````````````````````````
> > +
> > +       Send Broadcast_Code to the remote device.
> 
> Hmm, I wonder if it wouldn't be better to just have a dictionary that you can
> pass to the Push method.

So you're suggesting instead of having a separate method for setting the
Broadcast_Code, we can provide it through the Push method if the stream
is encrypted? I think this can work, but we will need another MediaAssistant
property to indicate stream information, maybe a "QoS" property like
MediaTransport is implementing.

So when calling Push from bluetoothctl, we can read the QoS property and
if the stream is encrypted, we can display a prompt for the user to enter
the Broadcast_Code.

> 
> > +Properties
> > +----------
> > +
> > +string State [readonly]
> > +```````````````````````
> > +
> > +       Indicates the state of the setup. Possible values are:
> > +
> > +       :"idle": setup created
> > +       :"pending": setup selected
> > +       :"requesting": remote device requires Broadcast_Code
> > +       :"active": remote device started receiving stream
> 
> We might want to add a property that refers to the MediaTransport object, that
> way the application can tell what is the BIS configuration from the transport and
> we don't need to duplicate them here. The lifetime of MediaAssistant shall be
> the same as the MediaTransport object it refers to, so if the transport is
> removed/free so is its MediaAssistant object, we may want to document this
> though because the Device object could persist if they are not temporary but the
> MediaTransport objects for broadcasters are normally considered temporary as
> they are not paired/bonded.

I think most use cases do not require a Broadcast Assistant to enumerate
MediaTransports, so I don't think the objects can be linked:
https://github.com/orgs/bluez/discussions/822#discussioncomment-9839217

But even if MediaTransports and MediaAssistants would coexist on a Broadcast
Assistant, they refer to different things: MediaTransports refer to streams
that the local device is trying to receive, while MediaAssistants refer to
streams that peer Scan Delegators are trying to receive.

As I see it, the "State" of a MediaAssistant allows the user to know the
stream state on the peer: For example, if the user calls the "Push" method on
a MediaAssistant, the BASS Client in BlueZ adds the stream information on the
peer, and then the BASS Client receives a notification that the peer
successfully acquired the stream, then the MediaAssistant goes to "active"
state.
> 
> > \ No newline at end of file
> > --
> > 2.39.2
> >
> 
> 
> --
> Luiz Augusto von Dentz

Regards,
Iulia
Luiz Augusto von Dentz June 21, 2024, 1:40 p.m. UTC | #4 
Hi Iulia,

On Fri, Jun 21, 2024 at 9:10 AM Iulia Tanasescu <iulia.tanasescu@nxp.com> wrote:
>
> Hi Luiz,
>
> > -----Original Message-----
> > From: Luiz Augusto von Dentz <luiz.dentz@gmail.com>
> > Sent: Wednesday, June 19, 2024 5:53 PM
> > To: Iulia Tanasescu <iulia.tanasescu@nxp.com>
> > Cc: linux-bluetooth@vger.kernel.org; Claudia Cristina Draghicescu
> > <claudia.rosu@nxp.com>; Mihai-Octavian Urzica <mihai-
> > octavian.urzica@nxp.com>; Vlad Pruteanu <vlad.pruteanu@nxp.com>; Andrei
> > Istodorescu <andrei.istodorescu@nxp.com>
> > Subject: Re: [PATCH RFC,BlueZ] doc: Add initial MediaSetup rst
> >
> > Hi Iulia,
> >
> > On Wed, Jun 19, 2024 at 7:35 AM Iulia Tanasescu <iulia.tanasescu@nxp.com>
> > wrote:
> > >
> > > This proposes a new D-Bus API to be used by the BAP Broadcast
> > > Assistant role.
> > >
> > > The BAP Broadcast Assistant is a Master device that can have multiple
> > > connections with BAP Scan Delegators. The Broadcast Assistant has the
> > > UI to start scanning, enumerate Broadacast Sources, allow the user to
> > > select a desired Source and send the stream information to one of the
> > > peers. If the selected stream is encrypted and the peer requires a
> > > Broadcast Code to decrypt the stream, the user should issue a command to
> > send the code.
> > >
> > > A new D-Bus API is necessary to allow the BAP Broadcast Assistant
> > > implementation in BlueZ to communicate with a top level UI process.
> > >
> > > The Broadcast Assistant in BlueZ should register a D-Bus object for
> > > each scanned BIS that matches the Audio capabilities of a peer. Each
> > > object should be linked with the stream and the peer device that
> > > matches the stream capabilities.
> > >
> > > The top level process should detect these objects and display the
> > > information to the user. The user can issue commands to select an
> > > object or to provide the Broadcast Code for an object.
> > >
> > > More information on the proposed design can be found here:
> > > https://gith/
> > >
> > ub.com%2Forgs%2Fbluez%2Fdiscussions%2F822&data=05%7C02%7Ciulia.tana
> > ses
> > >
> > cu%40nxp.com%7Cc4b5189ccea94198202d08dc906f805b%7C686ea1d3bc2b
> > 4c6fa92c
> > >
> > d99c5c301635%7C0%7C0%7C638544055766136877%7CUnknown%7CTWFp
> > bGZsb3d8eyJW
> > >
> > IjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0
> > %7C%
> > >
> > 7C%7C&sdata=w8yqp2HZQqouwJTFALZVB9Z32st0a3GTKm3w1TcHg10%3D&res
> > erved=0
> > > ---
> > >  Makefile.am                  |  6 ++---
> > >  doc/org.bluez.MediaSetup.rst | 45
> > > ++++++++++++++++++++++++++++++++++++
> > >  2 files changed, 48 insertions(+), 3 deletions(-)  create mode 100644
> > > doc/org.bluez.MediaSetup.rst
> > >
> > > diff --git a/Makefile.am b/Makefile.am index 0ae721111..217e7d2e4
> > > 100644
> > > --- a/Makefile.am
> > > +++ b/Makefile.am
> > > @@ -362,7 +362,7 @@ man_MANS += doc/org.bluez.Adapter.5
> > > doc/org.bluez.Device.5 \  man_MANS += doc/org.bluez.Media.5
> > doc/org.bluez.MediaControl.5 \
> > >                 doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
> > >                 doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
> > > -               doc/org.bluez.MediaTransport.5
> > > +               doc/org.bluez.MediaTransport.5
> > > + doc/org.bluez.MediaSetup.5
> > >  man_MANS += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
> > >                 doc/org.bluez.GattService.5 \
> > >                 doc/org.bluez.GattCharacteristic.5 \ @@ -395,7 +395,7
> > > @@ manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
> > > manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
> > >                 doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
> > >                 doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
> > > -               doc/org.bluez.MediaTransport.5
> > > +               doc/org.bluez.MediaTransport.5
> > > + doc/org.bluez.MediaSetup.5
> > >  manual_pages += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
> > >                 doc/org.bluez.GattService.5 \
> > >                 doc/org.bluez.GattCharacteristic.5 \ @@ -475,7 +475,7
> > > @@ EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
> > > EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
> > >                 doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \
> > >                 doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \
> > > -               doc/org.bluez.MediaTransport.rst
> > > +               doc/org.bluez.MediaTransport.rst
> > > + doc/org.bluez.MediaSetup.rst
> > >
> > >  EXTRA_DIST += doc/org.bluez.GattManager.rst doc/org.bluez.GattProfile.rst\
> > >                 doc/org.bluez.GattService.rst \ diff --git
> > > a/doc/org.bluez.MediaSetup.rst b/doc/org.bluez.MediaSetup.rst new file
> > > mode 100644 index 000000000..7463d7cfb
> > > --- /dev/null
> > > +++ b/doc/org.bluez.MediaSetup.rst
> > > @@ -0,0 +1,45 @@
> > > +=======================
> > > +org.bluez.MediaSetup
> > > +=======================
> >
> > Let's use MediaAssistant as name:
> > https://github.c/
> > om%2Forgs%2Fbluez%2Fdiscussions%2F822%23discussioncomment-
> > 9818645&data=05%7C02%7Ciulia.tanasescu%40nxp.com%7Cc4b5189ccea941
> > 98202d08dc906f805b%7C686ea1d3bc2b4c6fa92cd99c5c301635%7C0%7C0%
> > 7C638544055766147461%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjA
> > wMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C
> > &sdata=jHOPPf1bg8SpRg4N3AP33ozX51GGUslWid9JObkRzFw%3D&reserved=
> > 0
> >
> > > +
> > > +-------------------------------------------
> > > +BlueZ D-Bus MediaSetup API documentation
> > > +-------------------------------------------
> > > +
> > > +:Version: BlueZ
> > > +:Date: June 2024
> > > +:Manual section: 5
> > > +:Manual group: Linux System Administration
> > > +
> > > +Interface
> > > +=========
> > > +
> > > +:Service:      org.bluez
> > > +:Interface:    org.bluez.MediaSetup1
> > > +:Object path:
> > > +/org/bluez/{hci0,hci1,...}/src_XX_XX_XX_XX_XX_XX/dev_YY_YY_YY_YY_YY_Y
> > > +Y/bisZ
> > > +
> > > +Methods
> > > +-------
> > > +
> > > +void Select()
> > > +````````````````````````````````````````````````````````
> >
> > How about using Push as the method name here?
> >
> > > +
> > > +       Send stream information to the remote device.
> > > +
> > > +void SetBcode(array{byte} broadcast_code)
> > > +`````````````````````````````````````````````````````````
> > > +
> > > +       Send Broadcast_Code to the remote device.
> >
> > Hmm, I wonder if it wouldn't be better to just have a dictionary that you can
> > pass to the Push method.
>
> So you're suggesting instead of having a separate method for setting the
> Broadcast_Code, we can provide it through the Push method if the stream
> is encrypted? I think this can work, but we will need another MediaAssistant
> property to indicate stream information, maybe a "QoS" property like
> MediaTransport is implementing.
>
> So when calling Push from bluetoothctl, we can read the QoS property and
> if the stream is encrypted, we can display a prompt for the user to enter
> the Broadcast_Code.

Yep, I think we will need QoS properties anyway if we don't have a
transport to refer to, otherwise bluetoothctl would not be able to
list the stream configuration.

> >
> > > +Properties
> > > +----------
> > > +
> > > +string State [readonly]
> > > +```````````````````````
> > > +
> > > +       Indicates the state of the setup. Possible values are:
> > > +
> > > +       :"idle": setup created
> > > +       :"pending": setup selected
> > > +       :"requesting": remote device requires Broadcast_Code
> > > +       :"active": remote device started receiving stream
> >
> > We might want to add a property that refers to the MediaTransport object, that
> > way the application can tell what is the BIS configuration from the transport and
> > we don't need to duplicate them here. The lifetime of MediaAssistant shall be
> > the same as the MediaTransport object it refers to, so if the transport is
> > removed/free so is its MediaAssistant object, we may want to document this
> > though because the Device object could persist if they are not temporary but the
> > MediaTransport objects for broadcasters are normally considered temporary as
> > they are not paired/bonded.
>
> I think most use cases do not require a Broadcast Assistant to enumerate
> MediaTransports, so I don't think the objects can be linked:
> https://github.com/orgs/bluez/discussions/822#discussioncomment-9839217

Fair point.

> But even if MediaTransports and MediaAssistants would coexist on a Broadcast
> Assistant, they refer to different things: MediaTransports refer to streams
> that the local device is trying to receive, while MediaAssistants refer to
> streams that peer Scan Delegators are trying to receive.
>
> As I see it, the "State" of a MediaAssistant allows the user to know the
> stream state on the peer: For example, if the user calls the "Push" method on
> a MediaAssistant, the BASS Client in BlueZ adds the stream information on the
> peer, and then the BASS Client receives a notification that the peer
> successfully acquired the stream, then the MediaAssistant goes to "active"
> state.

Fair enough, we just need to make sure the clients have enough
information to decide on what to Push thus it is probably a good idea
to have QoS property as well.

> >
> > > \ No newline at end of file
> > > --
> > > 2.39.2
> > >
> >
> >
> > --
> > Luiz Augusto von Dentz
>
> Regards,
> Iulia
diff mbox series

Patch

diff --git a/Makefile.am b/Makefile.am
index 0ae721111..217e7d2e4 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -362,7 +362,7 @@  man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
 		doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
 		doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
-		doc/org.bluez.MediaTransport.5
+		doc/org.bluez.MediaTransport.5 doc/org.bluez.MediaSetup.5
 man_MANS += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
 		doc/org.bluez.GattService.5 \
 		doc/org.bluez.GattCharacteristic.5 \
@@ -395,7 +395,7 @@  manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
 		doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
 		doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
-		doc/org.bluez.MediaTransport.5
+		doc/org.bluez.MediaTransport.5 doc/org.bluez.MediaSetup.5
 manual_pages += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
 		doc/org.bluez.GattService.5 \
 		doc/org.bluez.GattCharacteristic.5 \
@@ -475,7 +475,7 @@  EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
 EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
 		doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \
 		doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \
-		doc/org.bluez.MediaTransport.rst
+		doc/org.bluez.MediaTransport.rst doc/org.bluez.MediaSetup.rst
 
 EXTRA_DIST += doc/org.bluez.GattManager.rst doc/org.bluez.GattProfile.rst\
 		doc/org.bluez.GattService.rst \
diff --git a/doc/org.bluez.MediaSetup.rst b/doc/org.bluez.MediaSetup.rst
new file mode 100644
index 000000000..7463d7cfb
--- /dev/null
+++ b/doc/org.bluez.MediaSetup.rst
@@ -0,0 +1,45 @@ 
+=======================
+org.bluez.MediaSetup
+=======================
+
+-------------------------------------------
+BlueZ D-Bus MediaSetup API documentation
+-------------------------------------------
+
+:Version: BlueZ
+:Date: June 2024
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.MediaSetup1
+:Object path:	/org/bluez/{hci0,hci1,...}/src_XX_XX_XX_XX_XX_XX/dev_YY_YY_YY_YY_YY_YY/bisZ
+
+Methods
+-------
+
+void Select()
+````````````````````````````````````````````````````````
+
+	Send stream information to the remote device.
+
+void SetBcode(array{byte} broadcast_code)
+`````````````````````````````````````````````````````````
+
+	Send Broadcast_Code to the remote device.
+
+Properties
+----------
+
+string State [readonly]
+```````````````````````
+
+	Indicates the state of the setup. Possible values are:
+
+	:"idle": setup created
+	:"pending": setup selected
+	:"requesting": remote device requires Broadcast_Code
+	:"active": remote device started receiving stream
\ No newline at end of file