W3C home > Mailing lists > Public > public-device-apis@w3.org > September 2015

Re: [sensors] Should unit option's behavior be defined in the Generic Sensor API?

From: Rick Waldron via GitHub <sysbot+gh@w3.org>
Date: Thu, 03 Sep 2015 18:18:29 +0000
To: public-device-apis@w3.org
Message-ID: <issue_comment.created-137533195-1441304308-sysbot+gh@w3.org>
### 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 |

```js
{
  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. 

-- 
GitHub Notif of comment by rwaldron
See https://github.com/w3c/sensors/issues/62#issuecomment-137533195
Received on Thursday, 3 September 2015 18:18:31 UTC

This archive was generated by hypermail 2.3.1 : Monday, 23 October 2017 14:54:06 UTC