[RFC,3/9] doc: Add set-api

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

This adds set-api.rst which documents DeviceSet interface.
---
 doc/set-api.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 doc/set-api.rst

Hi Luiz,

to, 2023-03-02 kello 17:27 -0800, Luiz Augusto von Dentz kirjoitti:
> > From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
> > 
> > This adds set-api.rst which documents DeviceSet interface.
> > ---
> >  doc/set-api.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 53 insertions(+)
> >  create mode 100644 doc/set-api.rst
> > 
> > diff --git a/doc/set-api.rst b/doc/set-api.rst
> > new file mode 100644
> > index 000000000000..17c5f93b6b86
> > --- /dev/null
> > +++ b/doc/set-api.rst
> > @@ -0,0 +1,53 @@
> > +=====================================
> > +BlueZ D-Bus DeviceSet API description
> > +=====================================
> > +
> > +
> > +DeviceSet interface
> > +===================
> > +
> > +Service		org.bluez
> > +Interface	org.bluez.DeviceSet1
> > +Object path	[variable prefix]/{hci0,hci1,...}/set_{sirk}
> > +
> > +Methods
> > +=======
> > +
> > +**void Connect() [experimental]**
> > +
> > +	Connects all **devices** members of the set, each member is
> > +	connected in sequence as they were added/loaded following the
> > +	same proceedure as described in **Device1.Connect**.
> > +
> > +	Possible errors: org.bluez.Error.NotReady
> > +			 org.bluez.Error.Failed
> > +			 org.bluez.Error.InProgress
> > +			 org.bluez.Error.AlreadyConnected
> > +
> > +**void Disconnect() [experimental]**
> > +
> > +	Disconnects all **devices** members of the set, each member is
> > +	disconnected in sequence as they were connected following the
> > +	same proceedure as described in **Device1.Disconnect**.
> > +
> > +	Possible errors: org.bluez.Error.NotConnected
> > +
> > +Properties
> > +==========
> > +
> > +**bool AutoConnect [read-write, experimental]**
> > +
> > +	Indicates if the **devices** members of the set shall be automatically
> > +	connected once any of its members is connected.
> > +
> > +**array(object) Devices [ready-only, experimental]**
> > +
> > +	List of devices objects that are members of the set.
> > +
> > +**byte Size [read-only, experimental]**
> > +
> > +	Set members size.
> > +
> > +**byte Rank [read-only, experimental]**
> > +
> > +	Set members rank.

It looks like rank is supposed to be a property of each set member
device, not a constant property of the set like size.

See CSIS 5.4: "The value of the Set Member Rank characteristic exposed
by servers that are part of the same Coordinated Set shall be
contiguous integers starting from 0x01 to the size of the Coordinated
Set."

So maybe should be something like

**array(byte) Ranks [read-only, experimental]**

	Set member ranks.

Hi Pauli,

On Sat, Mar 4, 2023 at 2:19 PM Pauli Virtanen <pav@iki.fi> wrote:
>
> Hi Luiz,
>
> to, 2023-03-02 kello 17:27 -0800, Luiz Augusto von Dentz kirjoitti:
> > > From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
> > >
> > > This adds set-api.rst which documents DeviceSet interface.
> > > ---
> > >  doc/set-api.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 53 insertions(+)
> > >  create mode 100644 doc/set-api.rst
> > >
> > > diff --git a/doc/set-api.rst b/doc/set-api.rst
> > > new file mode 100644
> > > index 000000000000..17c5f93b6b86
> > > --- /dev/null
> > > +++ b/doc/set-api.rst
> > > @@ -0,0 +1,53 @@
> > > +=====================================
> > > +BlueZ D-Bus DeviceSet API description
> > > +=====================================
> > > +
> > > +
> > > +DeviceSet interface
> > > +===================
> > > +
> > > +Service            org.bluez
> > > +Interface  org.bluez.DeviceSet1
> > > +Object path        [variable prefix]/{hci0,hci1,...}/set_{sirk}
> > > +
> > > +Methods
> > > +=======
> > > +
> > > +**void Connect() [experimental]**
> > > +
> > > +   Connects all **devices** members of the set, each member is
> > > +   connected in sequence as they were added/loaded following the
> > > +   same proceedure as described in **Device1.Connect**.
> > > +
> > > +   Possible errors: org.bluez.Error.NotReady
> > > +                    org.bluez.Error.Failed
> > > +                    org.bluez.Error.InProgress
> > > +                    org.bluez.Error.AlreadyConnected
> > > +
> > > +**void Disconnect() [experimental]**
> > > +
> > > +   Disconnects all **devices** members of the set, each member is
> > > +   disconnected in sequence as they were connected following the
> > > +   same proceedure as described in **Device1.Disconnect**.
> > > +
> > > +   Possible errors: org.bluez.Error.NotConnected
> > > +
> > > +Properties
> > > +==========
> > > +
> > > +**bool AutoConnect [read-write, experimental]**
> > > +
> > > +   Indicates if the **devices** members of the set shall be automatically
> > > +   connected once any of its members is connected.
> > > +
> > > +**array(object) Devices [ready-only, experimental]**
> > > +
> > > +   List of devices objects that are members of the set.
> > > +
> > > +**byte Size [read-only, experimental]**
> > > +
> > > +   Set members size.
> > > +
> > > +**byte Rank [read-only, experimental]**
> > > +
> > > +   Set members rank.
>
> It looks like rank is supposed to be a property of each set member
> device, not a constant property of the set like size.

Yep, Ive been debating putting a property called SetRank into the
Device interface.

> See CSIS 5.4: "The value of the Set Member Rank characteristic exposed
> by servers that are part of the same Coordinated Set shall be
> contiguous integers starting from 0x01 to the size of the Coordinated
> Set."
>
> So maybe should be something like
>
> **array(byte) Ranks [read-only, experimental]**

Or we actually sort the Devices list based on the rank, anyway Ive
been doing some modification like adding the Adapter object to
DeviceSet and a Set property to Device interface to make it easier to
locate its members, Im also planning to add support to the likes of
bluetoothctl.

>         Set member ranks.
>
> --
> Pauli Virtanen