* [RFC v2] doc: Add DeviceBR1 and DeviceLE1 interfaces
2016-04-04 1:22 [RFC v2] DeviceLE1 and DeviceBR1 interface Szymon Janc
@ 2016-04-04 1:22 ` Szymon Janc
2016-04-05 5:30 ` Johnny Robeson
0 siblings, 1 reply; 3+ messages in thread
From: Szymon Janc @ 2016-04-04 1:22 UTC (permalink / raw)
To: linux-bluetooth; +Cc: 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
^ permalink raw reply related [flat|nested] 3+ messages in thread