Should unit option's behavior be defined in the Generic Sensor API?

[tobie]

Typical example is of course Fahrenheit vs. Celsius degrees, but it becomes more interesting with more complex examples such as quarterions, rotational matrices or Tait-Bryan angles for device orientation.

If we were to specify a behavior in the the generic spec, I'd imagine each implementation of the spec would need to define a default unit. Constructing the sensor object would raise an error if the required unit was not available.

[anssiko]

I see the following three buckets:

• Only one sensible default unit. Never raises an error. For example:

new sensors.AmbientLight(); // lux (default)
new sensors.AmbientLight({ unit: 'lx' }); // lux

• Multiple possible default units. Conversion between the units always possible, thus every implementation supports all units. Never raises an error either. For example:

new sensors.Temperature(); // Celsius (default)
new sensors.Temperature({ unit: 'C' }); // Celsius
new sensors.Temperature({ unit: 'F' }); // Fahrenheit
new sensors.Temperature({ unit: 'K' }); // kelvin

• Multiple possible default units. Conversion between the units is not always possible. Raises an error if an implementation is not able to support the required unit. For example:

new sensors.Orientation(); // Tait–Bryan angles (default, for Device Orientation compat)
new sensors.Orientation({ unit: 'tait-bryan' }); // Tait–Bryan angles
new sensors.Orientation({ unit: 'rotation-matrix' }); // Rotation matrix, may raise an error
new sensors.Orientation({ unit: 'quaternion' }); // Quaternion, may raise an error

Specifically related to device orientation, based on what I see in the awesome Device Orientation API article by @richtr a conversion is possible between various representations assuming the platform provides an extra bit of information that the window.orientation API provides (do all relevant platform APIs expose corresponding data?).

So I guess my conclusion is we should define a default unit for each concrete sensor and also raise an error if the unit required is not supported. The latter behaviour should be defined in the Generic Sensor API spec.

Can we learn something from Johnny-Five or other platforms -- how they're handling the third case where the platform may not support all the unit options?

[rwaldron]

Accelerometer

Property Name	Value
x	g-force
y	g-force
z	g-force (if available)
pitch	angle in degrees
roll	angle in degrees
acceleration	magnitude of g-force
orientation	-3, -2, -1, 1, 2, 3

Event	Description
change	whenever x, y or z g-force changes.
data	all measurements

Barometer

Property Name	Value
pressure	kilopascals

Event	Description
change	whenever pressure changes.
data	all measurements

Button

Property Name	Value
isDown	boolean

Event	Description
down	when button is down, based on "down value"
up	when button is up, based on "up value"
hold	when button is held down, based on "hold time"
change	whenever pressure change surpasses threshold.
data	all measurements

Color (WIP)

Property Name	Value
rgb	visible color in RGB as an array of 8-bit values [red, green, blue]

Event	Description
change	whenever visible color changes.
data	all measurements

Compass

Property Name	Value
heading	degrees 0°-359°
bearing	an object, see below

{
  point: "NorthEast by East",
  abbr: "NEbE",
  low: 50.63,
  mid: 56.25,
  high: 61.87, 
  heading: ...same as present heading
}

Event	Description
change	whenever heading changes.
data	all measurements

Encoder (WIP)

Property Name	Value
position	number, 0-? based on how many position steps the encoder has

Event	Description
change	whenever heading changes.
data	all measurements

Gyroscope

Property Name	Value
pitch	y rotation rate in degrees per second
roll	x rotation rate in degrees per second
yaw	z rotation rate in degrees per second
rate	an object containing x, y, z rotation rate *

Event	Description
change	whenever rotation rate changes.
data	all measurements

Joystick

This only represents a single "stick", not to be confused with a gamepad.

Property Name	Value
x	-1 to 1 (left to right), where 0 is the center point **
y	-1 to 1 (top to bottom), where 0 is the center point **

Event	Description
change	whenever rotation rate changes.
data	all measurements

Light (WIP)

Property Name	Value
intensity	0-100, based on component lux range capability.
illuminance	amount of visible light in lux

Event	Description
change	whenever visible amount of light changes.
data	all measurements

Motion

This is not for detecting the device's own motion, it detects external environment
motion.

Property Name	Value
detectedMotion	true if the sensor detects motion of any kind, false if the environment appears "still"

Event	Description
change	whenever detection (motion or stillness) changes.
data	all measurements

Proximity

Property Name	Value
cm, centimeters	distance to obstruction in centimeters ***
in, inches	distance to obstruction in inches ***

Event	Description
change	whenever distance to obstruction changes.
data	all measurements

Sensor

Generic, works with any analog or digital sensor.

Property Name	Value
value (analog)	input voltage as a 10-bit value
value (digital)	input voltage high or low (1 or 0)

Event	Description
change	whenever value changes.
data	all measurements

Temperature

Property Name	Value
C, celsius	temperature in celsius ***
F, fahrenheit	temperature in fahrenheit ***
K, kelvin	temperature in kelvin ***

Event	Description
change	whenever value changes.
data	all measurements

---

* Gyroscope had an unfortunate early design mistake, that forced us to put the x, y, z rates in their own property. This will be fixed for eventual 1.0 release (by replacing the present this.x, this.y, this.z with x, y, z in rotation rate).

** Joystick directions can be inverted at initialization with a constructor option object property: invertX: true|false, invertY: true|false or invert: true|false | which inverts both |)

*** Both the full name and abbreviation are exposed to (hopefully) cater to intuition.

---

@anssiko

how they're handling the third case where the platform may not support all the unit options?

No such problem exists. All sensors of a "kind" (accelerometer, barometer, compass, etc) produce at least the minimum required data. Using that data, we compute the rest, eg. an accelerometer is only going to produce x, y, z (if available) measurements in g-force values, so we compute the other property's values from that value. Similarly, most temperature sensors only produce a value in celsius, so the F and K are always computed from C.

Back to platforms... A platform can either interface with a sensor, or it cannot; specifically, if a sensor interface is I2C, then it works with platforms that have I2C support—otherwise it simply does not. Ideally, Johnny-Five supports enough commercially available models of a "kind" to make it easy to swap between them based on the platform's capabilities.