Hi Arman, In this weekend, I think about this API again , and there is one question for you: In your new proposal , bluez offer two ways for application to read characteristic value, one is to get property array of value, the other is to use ReadValue method. For applications, in which condition they use property array of value and in which condition they use ReadValue ? will it cause a confusion for user when offer two ways for user at the same time? > I have to disagree here. I think making the DBus.Properties interface work for this particular case doesn't make the API particularly simpler, in fact I think it adds unnecessary complexity and ambiguity to the semantics involved. It's not clear, for instance, if Get should always return the cached value or if it should issue a > Read request to the remote end. You suggest making an initial read request and storing that value and updating it on notifications. What if the characteristic doesn't support notifications but it's value can change? What if the client is implementing a profile that warrants a read request to the remote end to get the > freshest value on demand? You said "What if the characteristic doesn't support notifications but it's value can change?" It means cached array of value cannot be trusted in the condition you said exist if this value changes happen not result from writing to the remote end device. So in my understanding, there is no worth to read characteristic value by property array of value, the property's role is just to emit propertychanged signal when write/read/notification operation changes its value. If so, we just define a signal such as ValueUpdated to tell user value has been changed is ok. "What if the characteristic doesn't support notifications but it's value can change?", if this value change just happen only one condition that client write the value to remote, not in which remote change its value itself spontaneously and not send notification. In fact, Set/Get property also can achieve the same result as your new proposal. Because the cache value can be trusted in this condition. And the cache value is the freshest value because client write value to the remote would let cache value send propertychanged signal to refresh itself to newest value. So there are two API design can be used: 1. array of value property Get/Set (This design just happen only one condition that client write the value to remote, not in which remote change its value itself spontaneously and not send notification.) 2. ReadValue /WriteValue method and signal ValueUpdated However, in the conclusion, array of value property and ReadValue/WriteValue can not be coexist, otherwise that design will result in ambiguity and not make sense. Thanks Chaojie -----Original Message----- From: linux-bluetooth-owner@xxxxxxxxxxxxxxx [mailto:linux-bluetooth-owner@xxxxxxxxxxxxxxx] On Behalf Of Arman Uguray Sent: Tuesday, July 22, 2014 7:41 AM To: linux-bluetooth@xxxxxxxxxxxxxxx Cc: Arman Uguray Subject: [RFC v1 1/1] doc/gatt-api: New API properties and methods for the GATT D-Bus API. This patch proposes changes to the currently unimplemented GATT D-Bus API for desktop bluetoothd. This is the first step in implementing a GATT client layer for bluetoothd that will change the way remote attributes are accessed via bluetoothd plugins and external applications. --- doc/gatt-api.txt | 118 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 106 insertions(+), 12 deletions(-) diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt index 8c7975c..741bd18 100644 --- a/doc/gatt-api.txt +++ b/doc/gatt-api.txt @@ -32,6 +32,25 @@ Properties string UUID [read-only] 128-bit service UUID. + boolean Primary [read-only] + + Indicates whether or not this GATT service is a + primary service. If false, the service is secondary. + + object Device [read-only, optional] + + Object path of the Bluetooth device the service + belongs to. Only present on services from remote + devices. + + array{object} Characteristics [read-only] + + Array of object paths representing the characteristics + of this service. This property is set only when the + characteristic discovery has been completed, however the + characteristic objects will become available via + ObjectManager as soon as they get discovered. + array{object} Includes [read-only]: Not implemented Array of object paths representing the included @@ -48,6 +67,47 @@ Service org.bluez Interface org.bluez.GattCharacteristic1 [Experimental] Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY +Methods array{byte} ReadValue() + + Issues a request to read the value of the + characteristic and returns the value if the + operation was successful. + + Possible Errors: org.bluez.Error.Failed + org.bluez.Error.InProgress + org.bluez.Error.ReadNotPermitted + org.bluez.Error.NotPaired + org.bluez.Error.NotSupported + + void WriteValue(array{byte} value) + + Issues a request to write the value of the + characteristic. + + Possible Errors: org.bluez.Error.Failed + org.bluez.Error.InProgress + org.bluez.Error.WriteNotPermitted + org.bluez.Error.NotPaired + org.bluez.Error.NotSupported + + void StartNotify() + + Starts a notification session from this characteristic + if it supports value notifications or indications. + + Possible Errors: org.bluez.Error.Failed + org.bluez.Error.InProgress + org.bluez.Error.NotSupported + + void StopNotify() + + This method will cancel any previous StartNotify + transaction. Note that notifications from a + characteristic are shared between sessions thus + calling StopNotify will release a single session. + + Possible Errors: org.bluez.Error.Failed + Properties string UUID [read-only] 128-bit characteristic UUID. @@ -57,12 +117,19 @@ Properties string UUID [read-only] Object path of the GATT service the characteristc belongs to. - array{byte} Value [read-write] + array{byte} Value [read-only, optional] + + The cached value of the characteristic. This property + gets updated only after a successful read request and + when a notification or indication is received, upon + which a PropertiesChanged signal will be emitted. - Value read from the remote Bluetooth device or from - the external application implementing GATT services. + boolean Notifying [read-only] - array{string} Flags [read-only, optional] + True, if notifications or indications on this + characteristic are currently enabled. + + array{string} Flags [read-only] Defines how the characteristic value can be used. See Core spec "Table 3.5: Characteristic Properties bit @@ -79,6 +146,14 @@ Properties string UUID [read-only] "reliable-write" "writable-auxiliaries" + array{object} Descriptors [read-only] + + Array of object paths representing the descriptors + of this service. This property is set only when the + descriptor discovery has been completed, however the + descriptor objects will become available via + ObjectManager as soon as they get discovered. + Characteristic Descriptors hierarchy ==================================== @@ -89,6 +164,29 @@ Service org.bluez Interface org.bluez.GattDescriptor1 [Experimental] Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ +Methods array{byte} ReadValue() + + Issues a request to read the value of the + characteristic and returns the value if the + operation was successful. + + Possible Errors: org.bluez.Error.Failed + org.bluez.Error.InProgress + org.bluez.Error.ReadNotPermitted + org.bluez.Error.NotPaired + org.bluez.Error.NotSupported + + void WriteValue(array{byte} value) + + Issues a request to write the value of the + characteristic. + + Possible Errors: org.bluez.Error.Failed + org.bluez.Error.InProgress + org.bluez.Error.WriteNotPermitted + org.bluez.Error.NotPaired + org.bluez.Error.NotSupported + Properties string UUID [read-only] 128-bit descriptor UUID. @@ -98,16 +196,12 @@ Properties string UUID [read-only] Object path of the GATT characteristc the descriptor belongs to. - array{byte} Value [read-write] - - Raw characteristic descriptor value read from the - remote Bluetooth device or from the external - application implementing GATT services. + array{byte} Value [read-only, optional] - string Permissions [read-only]: To be defined + The cached value of the descriptor. This property + gets updated only after a successful read request, upon + which a PropertiesChanged signal will be emitted. - Defines read/write authentication and authorization - requirements. Service Manager hierarchy ============================= -- 2.0.0.526.g5318336 -- To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
