[RFC v2] DeviceLE1 and DeviceBR1 interface

[RFC v2] DeviceLE1 and DeviceBR1 interface

[Szymon Janc]

Hi,

New proposal with new names: DeviceLE1 and DeviceBR1.
I've also updated interfaces to cover ServicesResolved property.

>From original cover letter:

Current Device1 interface doesn't handle dualmode devices very well and
doesn't provide information if remote supports LE, BR/EDR or both.
There is a problem with bond information, connected transport, supported
technologies etc.

Instead of duplicating properties which would require LE, BR/EDR and
(as currently) mixed variants I propose having two separates interfaces
DeviceSmart1 and DeviceClassic1 which would represent supported transports.

Thanks to this applications can easily track if remote device is LE or not
which is important eg with discovery where different apps can do different
type of discovery or when it want to use profile only over specific
transport.

Eventually those new interfaces would deprecate Device1 interface.

Comments are welcome.

Szymon Janc (1):
  doc: Add DeviceBR1 and DeviceLE1 interfaces

 doc/device-br-api.txt | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/device-le-api.txt | 161 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 361 insertions(+)
 create mode 100644 doc/device-br-api.txt
 create mode 100644 doc/device-le-api.txt

-- 
2.6.2

[RFC v2] doc: Add DeviceBR1 and DeviceLE1 interfaces

[Szymon Janc]

This interfaces will provide per tranport capabilities of remote
devices. Eventually leading to deprecation of Device1 interface.
---
 doc/device-br-api.txt | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/device-le-api.txt | 161 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 361 insertions(+)
 create mode 100644 doc/device-br-api.txt
 create mode 100644 doc/device-le-api.txt

diff --git a/doc/device-br-api.txt b/doc/device-br-api.txt
new file mode 100644
index 0000000..78b2a6d
--- /dev/null
+++ b/doc/device-br-api.txt
@@ -0,0 +1,200 @@
+BlueZ D-Bus Classic Device API description
+*****************************************
+
+
+Device hierarchy
+================
+
+Service		org.bluez
+Interface	org.bluez.DeviceBR1 [Experimental]
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Methods		void Connect()
+
+			This is a generic method to connect any profiles
+			the remote device supports that can be connected
+			to and have been flagged as auto-connectable on
+			our side. If only subset of profiles is already
+			connected it will try to connect currently disconnected
+			ones.
+
+			If at least one profile was connected successfully this
+			method will indicate success.
+
+			Possible errors: org.bluez.Error.NotReady
+					 org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.AlreadyConnected
+
+		void Disconnect()
+
+			This method gracefully disconnects all connected
+			profiles and then terminates low-level BR/EDR ACL
+			connection.
+
+			ACL connection will be terminated even if some profiles
+			were not disconnected properly e.g. due to misbehaving
+			device.
+
+			This method can be also used to cancel a preceding
+			Connect call before a reply to it has been received.
+
+			Possible errors: org.bluez.Error.NotConnected
+
+		void ConnectProfile(string uuid)
+
+			This method connects a specific profile of this
+			device. The UUID provided is the remote service
+			UUID for the profile.
+
+			Possible errors: org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.InvalidArguments
+					 org.bluez.Error.NotAvailable
+					 org.bluez.Error.NotReady
+
+		void DisconnectProfile(string uuid)
+
+			This method disconnects a specific profile of
+			this device. The profile needs to be registered
+			client profile.
+
+			There is no connection tracking for a profile, so
+			as long as the profile is registered this will always
+			succeed.
+
+			Possible errors: org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.InvalidArguments
+					 org.bluez.Error.NotSupported
+
+		void Pair()
+
+			This method will connect to the remote device,
+			initiate pairing and then retrieve all SDP records.
+
+			If the application has registered its own agent,
+			then that specific agent will be used. Otherwise
+			it will use the default agent.
+
+			Only for applications like a pairing wizard it
+			would make sense to have its own agent. In almost
+			all other cases the default agent will handle
+			this just fine.
+
+			In case there is no application agent and also
+			no default agent present, this method will fail.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.Failed
+					 org.bluez.Error.AlreadyExists
+					 org.bluez.Error.AuthenticationCanceled
+					 org.bluez.Error.AuthenticationFailed
+					 org.bluez.Error.AuthenticationRejected
+					 org.bluez.Error.AuthenticationTimeout
+					 org.bluez.Error.ConnectionAttemptFailed
+
+		void CancelPairing()
+
+			This method can be used to cancel a pairing
+			operation initiated by the Pair method.
+
+			Possible errors: org.bluez.Error.DoesNotExist
+					 org.bluez.Error.Failed
+
+Properties	string Address [readonly]
+
+			The Bluetooth device address of the remote device.
+
+		string Name [readonly, optional]
+
+			The Bluetooth remote name. This value can not be
+			changed. Use the Alias property instead.
+
+			This value is only present for completeness. It is
+			better to always use the Alias property when
+			displaying the devices name.
+
+			If the Alias property is unset, it will reflect
+			this value which makes it more convenient.
+
+		string Icon [readonly, optional]
+
+			Proposed icon name according to the freedesktop.org
+			icon naming specification.
+
+		uint32 Class [readonly, optional]
+
+			The Bluetooth class of device of the remote device.
+
+		array{string} UUIDs [readonly, optional]
+
+			List of 128-bit UUIDs that represents the available
+			remote services.
+
+		boolean Paired [readonly]
+
+			Indicates if the remote device is paired.
+
+		boolean Connected [readonly]
+
+			Indicates if the remote device is currently connected.
+
+		boolean Trusted [readwrite]
+
+			Indicates if the remote is seen as trusted. This
+			setting can be changed by the application.
+
+		boolean Blocked [readwrite]
+
+			If set to true any incoming connections from the
+			device will be immediately rejected. Any device
+			drivers will also be removed and no new ones will
+			be probed as long as the device is blocked.
+
+		string Alias [readwrite]
+
+			The name alias for the remote device. The alias can
+			be used to have a different friendly name for the
+			remote device.
+
+			In case no alias is set, it will return the remote
+			device name. Setting an empty string as alias will
+			convert it back to the remote device name.
+
+			When resetting the alias with an empty string, the
+			property will default back to the remote name.
+
+		object Adapter [readonly]
+
+			The object path of the adapter the device belongs to.
+
+		boolean LegacyPairing [readonly]
+
+			Set to true if the device only supports the pre-2.1
+			pairing mechanism. This property is useful during
+			device discovery to anticipate whether legacy or
+			simple pairing will occur if pairing is initiated.
+
+			Note that this property can exhibit false-positives
+			in the case of Bluetooth 2.1 (or newer) devices that
+			have disabled Extended Inquiry Response support.
+
+		string Modalias [readonly, optional]
+
+			Remote Device ID information in modalias format
+			used by the kernel and udev.
+
+		int16 RSSI [readonly, optional]
+
+			Received Signal Strength Indicator of the remote
+			device (inquiry).
+
+		int16 TxPower [readonly, optional, experimental]
+
+			Advertised transmitted power level (inquiry).
+
+		bool ServicesResolved [readonly, experimental]
+
+			Indicate whether or not service discovery has been
+			resolved.
diff --git a/doc/device-le-api.txt b/doc/device-le-api.txt
new file mode 100644
index 0000000..c74e387
--- /dev/null
+++ b/doc/device-le-api.txt
@@ -0,0 +1,161 @@
+BlueZ D-Bus Smart Device API description
+****************************************
+
+
+Device hierarchy
+================
+
+Service		org.bluez
+Interface	org.bluez.DeviceLE1 [Experimental]
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Methods		void Connect()
+
+			This is a generic method to connect low-level LE ACL
+			and then (if needed) retrieve all GATT primary services.
+
+			Possible errors: org.bluez.Error.NotReady
+					 org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.AlreadyConnected
+
+		void Disconnect()
+
+			This method terminates low-level LE ACL connection.
+
+			This method can be also used to cancel a preceding
+			Connect call before a reply to it has been received.
+
+			Possible errors: org.bluez.Error.NotConnected
+
+		void Pair()
+
+			This method will connect to the remote device,
+			initiate pairing and then retrieve all GATT primary
+			services.
+
+			If the application has registered its own agent,
+			then that specific agent will be used. Otherwise
+			it will use the default agent.
+
+			Only for applications like a pairing wizard it
+			would make sense to have its own agent. In almost
+			all other cases the default agent will handle
+			this just fine.
+
+			In case there is no application agent and also
+			no default agent present, this method will fail.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.Failed
+					 org.bluez.Error.AlreadyExists
+					 org.bluez.Error.AuthenticationCanceled
+					 org.bluez.Error.AuthenticationFailed
+					 org.bluez.Error.AuthenticationRejected
+					 org.bluez.Error.AuthenticationTimeout
+					 org.bluez.Error.ConnectionAttemptFailed
+
+		void CancelPairing()
+
+			This method can be used to cancel a pairing
+			operation initiated by the Pair method.
+
+			Possible errors: org.bluez.Error.DoesNotExist
+					 org.bluez.Error.Failed
+
+Properties	string Address [readonly]
+
+			The Bluetooth device address of the remote device.
+
+		string Name [readonly, optional]
+
+			The Bluetooth remote name. This value can not be
+			changed. Use the Alias property instead.
+
+			This value is only present for completeness. It is
+			better to always use the Alias property when
+			displaying the devices name.
+
+			If the Alias property is unset, it will reflect
+			this value which makes it more convenient.
+
+		string Icon [readonly, optional]
+
+			Proposed icon name according to the freedesktop.org
+			icon naming specification.
+
+		uint16 Appearance [readonly, optional]
+
+			External appearance of device, as found on GAP service.
+
+		array{string} UUIDs [readonly, optional]
+
+			List of 128-bit UUIDs that represents the available
+			remote services.
+
+		boolean Paired [readonly]
+
+			Indicates if the remote device is paired.
+
+		boolean Connected [readonly]
+
+			Indicates if the remote device is currently connected.
+
+		boolean Trusted [readwrite]
+
+			Indicates if the remote is seen as trusted. This
+			setting can be changed by the application.
+
+		boolean Blocked [readwrite]
+
+			If set to true any incoming connections from the
+			device will be immediately rejected. Any device
+			drivers will also be removed and no new ones will
+			be probed as long as the device is blocked.
+
+		string Alias [readwrite]
+
+			The name alias for the remote device. The alias can
+			be used to have a different friendly name for the
+			remote device.
+
+			In case no alias is set, it will return the remote
+			device name. Setting an empty string as alias will
+			convert it back to the remote device name.
+
+			When resetting the alias with an empty string, the
+			property will default back to the remote name.
+
+		object Adapter [readonly]
+
+			The object path of the adapter the device belongs to.
+
+		string Modalias [readonly, optional]
+
+			Remote Device Information information in modalias format
+			used by the kernel and udev.
+
+		int16 RSSI [readonly, optional]
+
+			Received Signal Strength Indicator of the remote
+			device (advertising).
+
+		int16 TxPower [readonly, optional, experimental]
+
+			Advertised transmitted power level (advertising).
+
+		dict ManufacturerData [readonly, optional]
+
+			Manufacturer specific advertisement data. Keys are
+			16 bits Manufacturer ID followed by its byte array
+			value.
+
+		dict ServiceData [readonly, optional]
+
+			Service advertisement data. Keys are the UUIDs in
+			string format followed by its byte array value.
+
+		bool ServicesResolved [readonly, experimental]
+
+			Indicate whether or not service discovery has been
+			resolved.
-- 
2.6.2

Re: [RFC v2] doc: Add DeviceBR1 and DeviceLE1 interfaces

[Johnny Robeson]

Can you expose the LE address type here too as a readonly method?


This is currently available in the management api here as seen here: ht
tp://git.kernel.org/cgit/bluetooth/bluez.git/tree/doc/mgmt-
api.txt?id=60d28644cab85f2b75cd760f916049387ce8a248#n2159

Also, can you clarify how included and/or secondary services are
handled?