Open tobie opened 9 years ago
I see the following three buckets:
new sensors.AmbientLight(); // lux (default)
new sensors.AmbientLight({ unit: 'lx' }); // lux
new sensors.Temperature(); // Celsius (default)
new sensors.Temperature({ unit: 'C' }); // Celsius
new sensors.Temperature({ unit: 'F' }); // Fahrenheit
new sensors.Temperature({ unit: 'K' }); // kelvin
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?
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 |
Property Name | Value |
---|---|
pressure |
kilopascals |
Event | Description |
---|---|
change |
whenever pressure changes. |
data |
all measurements |
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 |
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 |
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 |
Property Name | Value |
---|---|
position |
number, 0-? based on how many position steps the encoder has |
Event | Description |
---|---|
change |
whenever heading changes. |
data |
all measurements |
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 |
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 |
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 |
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 |
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 |
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 |
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.
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.