[RFC v2] doc: Add DeviceBR1 and DeviceLE1 interfaces

[Szymon Janc <szymon.janc@codecoup.pl>]

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