---
doc/thermometer-api.txt | 126 +++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 126 insertions(+), 0 deletions(-)
create mode 100644 doc/thermometer-api.txt
diff --git a/doc/thermometer-api.txt b/doc/thermometer-api.txt
new file mode 100644
index 0000000..6392d39
--- /dev/null
+++ b/doc/thermometer-api.txt
@@ -0,0 +1,126 @@
+BlueZ D-Bus Thermometer API description
+****************************************
+
+ Santiago Carot-Nemesio <[email protected]>
+
+Health Thermometer Profile hierarchy
+=====================================
+
+Service org.bluez
+Interface org.bluez.Thermometer
+Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+
+Methods void SetProperty(string name, variant value)
+
+ Changes the value of the specified property. Only
+ read-write properties can be changed. On success
+ this will emit a PropertyChanged signal.
+
+ Possible Errors: org.bluez.Error.InvalidArguments
+
+ dict GetProperties()
+
+ Returns all properties for the interface. See the
+ Properties section for the available properties.
+
+ RegisterWatcher(object agent)
+
+ Registers a watcher to monitor scanned measurements.
+ This agent will be notified about final temperature
+ measurements.
+
+ Possible Errors: org.bluez.Error.InvalidArguments
+
+ UnregisterWatcher(object agent)
+
+ Unregisters a watcher.
+
+ Final and intermediate temperatures won't be notified to
+ this agent any more.
+
+ Possible Errors: org.bluez.Error.InvalidArguments
+ org.bluez.Error.NotFound
+
+ EnableIntermediateMeasurement(object agent)
+
+ Enables intermediate measurement notifications for this
+ agent if the thermometer supports it.
+
+ Possible Errors: org.bluez.Error.InvalidArguments
+ org.bluez.Error.NotSupported
+
+ DisableIntermediateMeasurement(object agent)
+
+ Disables intermediate measurement notifications for this
+ agent. It will disable notifications in the thermometer
+ when the last agent removes the watcher for intermediate
+ measurements.
+
+ Possible Errors: org.bluez.Error.InvalidArguments
+ org.bluez.Error.NotFound
+
+Signals PropertyChanged(string name, variant value)
+
+ This signal indicates a changed value of the given
+ property.
+
+Properties boolean Intermediate [readonly]
+
+ True if the thermometer supports intermediate measurement
+ notifications.
+
+ uint16 Interval (optional) [readwrite]
+
+ The Measurement Interval defines the time (in seconds)
+ between measurements. This interval is not related to
+ the intermediate measurements and must be defined into
+ a valid range. Setting it to zero means that no periodic
+ measurements will be taken.
+
+ uint16 Maximum (optional) [readonly]
+
+ Defines the maximum value allowed for the interval
+ between periodic measurements.
+
+ uint16 Minimum (optional) [readonly]
+
+ Defines the minimum value allowed for the interval
+ between periodic measurements.
+
+
+Health Thermometer Watcher hierarchy
+====================================
+Service unique name
+Interface org.bluez.ThermometerWatcher
+Object path freely definable
+
+Methods void MeasurementReceived(dict measure)
+
+ This callback gets called when a measure has been
+ scanned in the thermometer. The Time entry in the dict
+ will be only present if the device supports storing of
+ data. The time value is expressed in seconds since epoch.
+ The value represented is (mantissa) x (10**exponent)
+ See foot note for special values when treating with
+ health devices.
+
+ Dict is defined as below:
+ {
+ "Exponent" : int8,
+ "Mantissa" : int32,
+ "Unit" : ("Celsius" or "Fahrenheit"),
+ "Time" : uint64,
+ "Type" : ("Armpit", "Body", "Ear", "Finger",
+ "Intestines", "Mouth", "Rectum", "Toe",
+ "Tympanum"),
+ "Measurement" : ("Final" or "Intermediate"),
+ }
+
+ For special cases, the exponent shall always be zero and
+ the mantissa should be one of following values:
+
+ NRes = -(2**23)
+ NaN = +(2**23-1)
+ INFINITY = (2**23-2)
+ -INFINITY = -(2**23-2)
--
1.7.6
Hi,
On Mon, Jul 04, 2011, Santiago Carot-Nemesio wrote:
> ---
> doc/thermometer-api.txt | 126 +++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 126 insertions(+), 0 deletions(-)
> create mode 100644 doc/thermometer-api.txt
I've pushed this upstream. It doesn't mean that it'd the final API, but
at least we have a starting point for the implementation.
Johan
Hi Claudio,
2011/7/6 Claudio Takahasi <[email protected]>:
> Hi Santiago,
>
> <snip>
>
>> + ? ? ? ? ? ? ? RegisterWatcher(object agent)
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Registers a watcher to monitor scanned measurements.
>> + ? ? ? ? ? ? ? ? ? ? ? This agent will be notified about final temperature
>> + ? ? ? ? ? ? ? ? ? ? ? measurements.
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Possible Errors: org.bluez.Error.InvalidArguments
>> +
>> + ? ? ? ? ? ? ? UnregisterWatcher(object agent)
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Unregisters a watcher.
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Final and intermediate temperatures won't be notified to
>> + ? ? ? ? ? ? ? ? ? ? ? this agent any more.
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Possible Errors: org.bluez.Error.InvalidArguments
>> + ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? org.bluez.Error.NotFound
>> +
>> + ? ? ? ? ? ? ? EnableIntermediateMeasurement(object agent)
>
> It'd be good to try hide from the apps notifications and indications.
> My opinion is: watchers doesn't need to know if the characteristic
> value is a notification or indication.
The Notification word in the API refers to way that the plugin will
report to applications about measures received. Nothing related with
the property of the characteristic. The idea is that applications does
not worried about that. Always a measurement (notification or
indication) is received the callback in the watcher gets called.
> The thermometer implementation could enable automatically
> notifications if there is at least one watcher registered.
>
> Is it important to know if the characteristic value is intermediate or not?
Yes, for example there may be watchers that want to feed a display
with intermediate values until the final measurement arrives, in
opposite, EEE11073-20601 watchers dont need get intermediate ones to
work so we dont need to bother them with intermediate measurements.
>
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Enables intermediate measurement notifications for this
>> + ? ? ? ? ? ? ? ? ? ? ? agent if the thermometer supports it.
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Possible Errors: org.bluez.Error.InvalidArguments
>> + ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? org.bluez.Error.NotSupported
>> +
>> + ? ? ? ? ? ? ? DisableIntermediateMeasurement(object agent)
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Disables intermediate measurement notifications for this
>> + ? ? ? ? ? ? ? ? ? ? ? agent. It will disable notifications in the thermometer
>> + ? ? ? ? ? ? ? ? ? ? ? when the last agent removes the watcher for intermediate
>> + ? ? ? ? ? ? ? ? ? ? ? measurements.
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Possible Errors: org.bluez.Error.InvalidArguments
>> + ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? org.bluez.Error.NotFound
>> +
>> +Signals ? ? ? ? ? ? ? ?PropertyChanged(string name, variant value)
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? This signal indicates a changed value of the given
>> + ? ? ? ? ? ? ? ? ? ? ? property.
>> +
>> +Properties ? ? boolean Intermediate [readonly]
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? True if the thermometer supports intermediate measurement
>> + ? ? ? ? ? ? ? ? ? ? ? notifications.
>> +
>> + ? ? ? ? ? ? ? uint16 Interval (optional) [readwrite]
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? The Measurement Interval defines the time (in seconds)
>> + ? ? ? ? ? ? ? ? ? ? ? between measurements. This interval is not related to
>> + ? ? ? ? ? ? ? ? ? ? ? the intermediate measurements and must be defined into
>> + ? ? ? ? ? ? ? ? ? ? ? a valid range. Setting it to zero means that no periodic
>> + ? ? ? ? ? ? ? ? ? ? ? measurements will be taken.
>> +
>> + ? ? ? ? ? ? ? uint16 Maximum (optional) [readonly]
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Defines the maximum value allowed for the interval
>> + ? ? ? ? ? ? ? ? ? ? ? between periodic measurements.
>> +
>> + ? ? ? ? ? ? ? uint16 Minimum (optional) [readonly]
>> +
>> + ? ? ? ? ? ? ? ? ? ? ? Defines the minimum value allowed for the interval
>> + ? ? ? ? ? ? ? ? ? ? ? between periodic measurements.
>> +
>
> Intervals could be a config option. It can be extended later if
> necessary, move the config option to the API(Property) is easier than
> remove a property.
>
Do you mean to move it to the bluetoothd configuration file?
I think that it's not a good a idea because this value should be in a
determinated range imposed by the device. Each device can have it own
range and it may differ among all those kind of devices.
Regards.
On Jul 6, 2011, at 10:02 AM, Claudio Takahasi wrote:
> Hi Santiago,
>
> <snip>
>
>> + RegisterWatcher(object agent)
>> +
>> + Registers a watcher to monitor scanned measurements.
>> + This agent will be notified about final temperature
>> + measurements.
>> +
>> + Possible Errors: org.bluez.Error.InvalidArguments
>> +
>> + UnregisterWatcher(object agent)
>> +
>> + Unregisters a watcher.
>> +
>> + Final and intermediate temperatures won't be notified to
>> + this agent any more.
>> +
>> + Possible Errors: org.bluez.Error.InvalidArguments
>> + org.bluez.Error.NotFound
>> +
>> + EnableIntermediateMeasurement(object agent)
>
> It'd be good to try hide from the apps notifications and indications.
> My opinion is: watchers doesn't need to know if the characteristic
> value is a notification or indication.
> The thermometer implementation could enable automatically
> notifications if there is at least one watcher registered.
The API does that for final measurements. This only enables/disables
the intermediate ones.
>
> Is it important to know if the characteristic value is intermediate or not?
Yes. Intermediate is a "rough" measurement that is sent for display purposes
only, to keep the user happy, and not necessary when there is nobody watching.
The final measurement is the "trusted" one.
SGkgU2FudGlhZ28sCgo8c25pcD4KCj4gKyDCoCDCoCDCoCDCoCDCoCDCoCDCoCBSZWdpc3Rlcldh
dGNoZXIob2JqZWN0IGFnZW50KQo+ICsKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKg
IMKgIFJlZ2lzdGVycyBhIHdhdGNoZXIgdG8gbW9uaXRvciBzY2FubmVkIG1lYXN1cmVtZW50cy4K
PiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIFRoaXMgYWdlbnQgd2lsbCBiZSBu
b3RpZmllZCBhYm91dCBmaW5hbCB0ZW1wZXJhdHVyZQo+ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAg
wqAgwqAgwqAgwqAgbWVhc3VyZW1lbnRzLgo+ICsKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKg
IMKgIMKgIMKgIFBvc3NpYmxlIEVycm9yczogb3JnLmJsdWV6LkVycm9yLkludmFsaWRBcmd1bWVu
dHMKPiArCj4gKyDCoCDCoCDCoCDCoCDCoCDCoCDCoCBVbnJlZ2lzdGVyV2F0Y2hlcihvYmplY3Qg
YWdlbnQpCj4gKwo+ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgVW5yZWdpc3Rl
cnMgYSB3YXRjaGVyLgo+ICsKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIEZp
bmFsIGFuZCBpbnRlcm1lZGlhdGUgdGVtcGVyYXR1cmVzIHdvbid0IGJlIG5vdGlmaWVkIHRvCj4g
KyDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCB0aGlzIGFnZW50IGFueSBtb3JlLgo+
ICsKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIFBvc3NpYmxlIEVycm9yczog
b3JnLmJsdWV6LkVycm9yLkludmFsaWRBcmd1bWVudHMKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKg
IMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIG9yZy5ibHVlei5FcnJvci5Ob3RG
b3VuZAo+ICsKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIEVuYWJsZUludGVybWVkaWF0ZU1lYXN1
cmVtZW50KG9iamVjdCBhZ2VudCkKCkl0J2QgYmUgZ29vZCB0byB0cnkgaGlkZSBmcm9tIHRoZSBh
cHBzIG5vdGlmaWNhdGlvbnMgYW5kIGluZGljYXRpb25zLgpNeSBvcGluaW9uIGlzOiB3YXRjaGVy
cyBkb2Vzbid0IG5lZWQgdG8ga25vdyBpZiB0aGUgY2hhcmFjdGVyaXN0aWMKdmFsdWUgaXMgYSBu
b3RpZmljYXRpb24gb3IgaW5kaWNhdGlvbi4KVGhlIHRoZXJtb21ldGVyIGltcGxlbWVudGF0aW9u
IGNvdWxkIGVuYWJsZSBhdXRvbWF0aWNhbGx5Cm5vdGlmaWNhdGlvbnMgaWYgdGhlcmUgaXMgYXQg
bGVhc3Qgb25lIHdhdGNoZXIgcmVnaXN0ZXJlZC4KCklzIGl0IGltcG9ydGFudCB0byBrbm93IGlm
IHRoZSBjaGFyYWN0ZXJpc3RpYyB2YWx1ZSBpcyBpbnRlcm1lZGlhdGUgb3Igbm90PwoKPiArCj4g
KyDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCBFbmFibGVzIGludGVybWVkaWF0ZSBt
ZWFzdXJlbWVudCBub3RpZmljYXRpb25zIGZvciB0aGlzCj4gKyDCoCDCoCDCoCDCoCDCoCDCoCDC
oCDCoCDCoCDCoCDCoCBhZ2VudCBpZiB0aGUgdGhlcm1vbWV0ZXIgc3VwcG9ydHMgaXQuCj4gKwo+
ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgUG9zc2libGUgRXJyb3JzOiBvcmcu
Ymx1ZXouRXJyb3IuSW52YWxpZEFyZ3VtZW50cwo+ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAg
wqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgb3JnLmJsdWV6LkVycm9yLk5vdFN1cHBv
cnRlZAo+ICsKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIERpc2FibGVJbnRlcm1lZGlhdGVNZWFz
dXJlbWVudChvYmplY3QgYWdlbnQpCj4gKwo+ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAg
wqAgwqAgRGlzYWJsZXMgaW50ZXJtZWRpYXRlIG1lYXN1cmVtZW50IG5vdGlmaWNhdGlvbnMgZm9y
IHRoaXMKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIGFnZW50LiBJdCB3aWxs
IGRpc2FibGUgbm90aWZpY2F0aW9ucyBpbiB0aGUgdGhlcm1vbWV0ZXIKPiArIMKgIMKgIMKgIMKg
IMKgIMKgIMKgIMKgIMKgIMKgIMKgIHdoZW4gdGhlIGxhc3QgYWdlbnQgcmVtb3ZlcyB0aGUgd2F0
Y2hlciBmb3IgaW50ZXJtZWRpYXRlCj4gKyDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDC
oCBtZWFzdXJlbWVudHMuCj4gKwo+ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAg
UG9zc2libGUgRXJyb3JzOiBvcmcuYmx1ZXouRXJyb3IuSW52YWxpZEFyZ3VtZW50cwo+ICsgwqAg
wqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgb3Jn
LmJsdWV6LkVycm9yLk5vdEZvdW5kCj4gKwo+ICtTaWduYWxzIMKgIMKgIMKgIMKgIMKgIMKgIMKg
IMKgUHJvcGVydHlDaGFuZ2VkKHN0cmluZyBuYW1lLCB2YXJpYW50IHZhbHVlKQo+ICsKPiArIMKg
IMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIFRoaXMgc2lnbmFsIGluZGljYXRlcyBhIGNo
YW5nZWQgdmFsdWUgb2YgdGhlIGdpdmVuCj4gKyDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDC
oCDCoCBwcm9wZXJ0eS4KPiArCj4gK1Byb3BlcnRpZXMgwqAgwqAgYm9vbGVhbiBJbnRlcm1lZGlh
dGUgW3JlYWRvbmx5XQo+ICsKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIFRy
dWUgaWYgdGhlIHRoZXJtb21ldGVyIHN1cHBvcnRzIGludGVybWVkaWF0ZSBtZWFzdXJlbWVudAo+
ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgbm90aWZpY2F0aW9ucy4KPiArCj4g
KyDCoCDCoCDCoCDCoCDCoCDCoCDCoCB1aW50MTYgSW50ZXJ2YWwgKG9wdGlvbmFsKSBbcmVhZHdy
aXRlXQo+ICsKPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIFRoZSBNZWFzdXJl
bWVudCBJbnRlcnZhbCBkZWZpbmVzIHRoZSB0aW1lIChpbiBzZWNvbmRzKQo+ICsgwqAgwqAgwqAg
wqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgYmV0d2VlbiBtZWFzdXJlbWVudHMuIFRoaXMgaW50ZXJ2
YWwgaXMgbm90IHJlbGF0ZWQgdG8KPiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKg
IHRoZSBpbnRlcm1lZGlhdGUgbWVhc3VyZW1lbnRzIGFuZCBtdXN0IGJlIGRlZmluZWQgaW50bwo+
ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAgYSB2YWxpZCByYW5nZS4gU2V0dGlu
ZyBpdCB0byB6ZXJvIG1lYW5zIHRoYXQgbm8gcGVyaW9kaWMKPiArIMKgIMKgIMKgIMKgIMKgIMKg
IMKgIMKgIMKgIMKgIMKgIG1lYXN1cmVtZW50cyB3aWxsIGJlIHRha2VuLgo+ICsKPiArIMKgIMKg
IMKgIMKgIMKgIMKgIMKgIHVpbnQxNiBNYXhpbXVtIChvcHRpb25hbCkgW3JlYWRvbmx5XQo+ICsK
PiArIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIMKgIERlZmluZXMgdGhlIG1heGltdW0g
dmFsdWUgYWxsb3dlZCBmb3IgdGhlIGludGVydmFsCj4gKyDCoCDCoCDCoCDCoCDCoCDCoCDCoCDC
oCDCoCDCoCDCoCBiZXR3ZWVuIHBlcmlvZGljIG1lYXN1cmVtZW50cy4KPiArCj4gKyDCoCDCoCDC
oCDCoCDCoCDCoCDCoCB1aW50MTYgTWluaW11bSAob3B0aW9uYWwpIFtyZWFkb25seV0KPiArCj4g
KyDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCDCoCBEZWZpbmVzIHRoZSBtaW5pbXVtIHZh
bHVlIGFsbG93ZWQgZm9yIHRoZSBpbnRlcnZhbAo+ICsgwqAgwqAgwqAgwqAgwqAgwqAgwqAgwqAg
wqAgwqAgwqAgYmV0d2VlbiBwZXJpb2RpYyBtZWFzdXJlbWVudHMuCj4gKwoKSW50ZXJ2YWxzIGNv
dWxkIGJlIGEgY29uZmlnIG9wdGlvbi4gSXQgY2FuIGJlIGV4dGVuZGVkIGxhdGVyIGlmCm5lY2Vz
c2FyeSwgbW92ZSB0aGUgY29uZmlnIG9wdGlvbiB0byB0aGUgQVBJKFByb3BlcnR5KSBpcyBlYXNp
ZXIgdGhhbgpyZW1vdmUgYSBwcm9wZXJ0eS4KClJlZ2FyZHMsCkNsYXVkaW8K