[RFC] Cycling Speed and Cadence profile (CSCP) API

[RFC] Cycling Speed and Cadence profile (CSCP) API

[Andrzej Kaczmarek]

Hi,

Here's proposal for CSCP API. This is of course for Collector role.
Not sure if 'Cycling' prefix for interface names (and probably also for plugin
name) is good enough, but couldn't think of anything better.

Comments are welcome.


Andrzej Kaczmarek (1):
  Cycling Speed and Cadence profile (CSCP) API

 doc/cycling-api.txt | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 doc/cycling-api.txt

-- 
1.7.11.3

[PATCH] Cycling Speed and Cadence profile (CSCP) API

[Andrzej Kaczmarek]

---
 doc/cycling-api.txt | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 doc/cycling-api.txt

diff --git a/doc/cycling-api.txt b/doc/cycling-api.txt
new file mode 100644
index 0000000..5988cac
--- /dev/null
+++ b/doc/cycling-api.txt
@@ -0,0 +1,112 @@
+Cycling Speed and Cadence API description
+****************************************
+
+Copyright (C) 2012	Tieto Poland
+
+Cycling Manager hierarchy
+============================
+
+Service		org.bluez
+Interface	org.bluez.CyclingManager
+Object path	[variable prefix]/{hci0,hci1,...}
+
+Methods		RegisterWatcher(object agent)
+
+			Registers a watcher to monitor cycling speed and cadence
+			measurements.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+
+		UnregisterWatcher(object agent)
+
+			Unregisters a watcher.
+
+Cycling Speed and Cadence Profile hierarchy
+============================
+
+Service		org.bluez
+Interface	org.bluez.Cycling
+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.
+
+		SetCumulativeWheelRevolutions(uint32 value)
+
+			Sets cumulative wheel revolutions value if
+			Cumulative Wheel Revolutions feature is supported.
+
+			Possible Errors: org.bluez.Error.NotSupported
+
+Signals		PropertyChanged(string name, variant value)
+
+			This signal indicates a changed value of the given
+			property.
+
+Properties	String Location (optional) [readwrite]
+
+			Current sensor location, if supported.
+			If Multiple Sensor Locations feature is supported,
+			this property can be set to one of values read from
+			SupportedLocations property.
+
+			Possible values: "Other", "Top of shoe", "In shoe",
+					"Hip", "Front Wheel", "Left Crank",
+					"Right Crank", "Left Pedal",
+					"Right Pedal", "Front Hub",
+					"Rear Dropout", "Chainstay",
+					"Rear Wheel", "Rear Hub"
+
+		array{string} SupportedLocations (optional) [readonly]
+
+			List of locations supported by sensor, only present
+			if Multiple Sensor Locations feature is supported.
+
+		boolean WheelRevolutionDataSupported [readonly]
+
+			true if sensor can read and set Cumulative Wheel
+			Revolutions value, false otherwise.
+
+		boolean MultipleSensorLocationsSupported [readonly]
+
+			true if sensor supports Multiple Sensor Locations
+			feature and can set Location, false otherwise.
+
+Cycling Speed and Cadence Watcher hierarchy
+============================
+Service		unique name
+Interface	org.bluez.CyclingWatcher
+Object path	freely definable
+
+Methods		void MeasurementReceived(object device, dict measurement)
+
+			This callback is called whenever a cycling speed and
+			cadence measurement is received from sensor.
+
+			Measurement:
+
+				uint32 WheelRevolutions (optional):
+
+					Cumulative number of wheel revolutions
+
+				uint16 LastWheelEventTime (optional):
+
+					Value of Last Wheel Event time
+
+				uint16 CrankRevolutions (optional):
+
+					Cumulative number of crank revolutions
+
+				uint16 LastCrankEventTime (optional):
+
+					Value of Last Crank Event time
-- 
1.7.11.3

Re: [PATCH] Cycling Speed and Cadence profile (CSCP) API

[Anderson Lizardo]

Hi Andrzej,

On Fri, Sep 21, 2012 at 5:09 AM, Andrzej Kaczmarek
<andrzej.kaczmarek@tieto.com> wrote:
> +Cycling Speed and Cadence API description
> +****************************************
> +
> +Copyright (C) 2012     Tieto Poland
> +
> +Cycling Manager hierarchy
> +============================
> +
> +Service                org.bluez
> +Interface      org.bluez.CyclingManager

I don't have much to comment on the API as I haven't had time to read
the CSCP spec yet, but about the name prefix, what about
"CyclingSpeed" (and "RunningSpeed" for the future RSCP) ? Too long?

The "Cycling" name is slightly uncommon, but still not that bad IMHO.

> +Properties     String Location (optional) [readwrite]

String -> string

> +                               uint16 LastWheelEventTime (optional):
> +
> +                                       Value of Last Wheel Event time

Better specify that this is in "1/1024 second units" (just checked on
developer.bluetooth.org).

> +
> +                               uint16 CrankRevolutions (optional):
> +
> +                                       Cumulative number of crank revolutions
> +
> +                               uint16 LastCrankEventTime (optional):
> +
> +                                       Value of Last Crank Event time

Same here.

Regards,
-- 
Anderson Lizardo
Instituto Nokia de Tecnologia - INdT
Manaus - Brazil

Re: [PATCH] Cycling Speed and Cadence profile (CSCP) API

[Andrzej Kaczmarek]

Hi Anderson,

On 09/21/2012 05:51 PM, Anderson Lizardo wrote:
> Hi Andrzej,
>
> On Fri, Sep 21, 2012 at 5:09 AM, Andrzej Kaczmarek
> <andrzej.kaczmarek@tieto.com> wrote:
>> +Cycling Speed and Cadence API description
>> +****************************************
>> +
>> +Copyright (C) 2012     Tieto Poland
>> +
>> +Cycling Manager hierarchy
>> +============================
>> +
>> +Service                org.bluez
>> +Interface      org.bluez.CyclingManager
>
> I don't have much to comment on the API as I haven't had time to read
> the CSCP spec yet, but about the name prefix, what about
> "CyclingSpeed" (and "RunningSpeed" for the future RSCP) ? Too long?

Ok for me. Not too long for sure, Thermometer is just 1 letter shorter.

> The "Cycling" name is slightly uncommon, but still not that bad IMHO.

In spec there's also SC used as shortcut for 'Speed and Cadence' but I 
think CyclingSC does not work well with camel-case in interface name. Or 
actually is CyclingScManager ok? But plugin name (cyclingsc) will look a 
bit weird if derived from this name, cyclingspeed sounds better.

>> +Properties     String Location (optional) [readwrite]
>
> String -> string
>
>> +                               uint16 LastWheelEventTime (optional):
>> +
>> +                                       Value of Last Wheel Event time
>
> Better specify that this is in "1/1024 second units" (just checked on
> developer.bluetooth.org).
>
>> +
>> +                               uint16 CrankRevolutions (optional):
>> +
>> +                                       Cumulative number of crank revolutions
>> +
>> +                               uint16 LastCrankEventTime (optional):
>> +
>> +                                       Value of Last Crank Event time
>
> Same here.

Sure, I'll fix above issues.

BR,
Andrzej