Detailed Description

The purpose of this module is to introduce a common view on physical data throughout RIOT. This data is typically the output from sensor readings, data aggregation, and also the input for actuators.

The idea is to enable different sensor/actuator drivers and other RIOT modules to exchange and have the same view on this kind of data. Labeling data with a unit type it's scaling makes it possible to pipe data between modules in an automated fashion without the need of specialized software wrappers and/or data normalization modules.

Macro Definition Documentation

We use a fixed number of 3 dimensions, as many physical values we encounter can be expressed this way. In practice we have e.g. readings from accelerometers, gyros, color sensors, or set data for RGB LEDs.

When expressing 1-dimensional data we just ignore the 2 higher dimension. This leads to a slight overhead of some byte of memory - but we benefit from a unified data structure for passing around physical data.

Enumeration Type Documentation

This list should contain all needed physical units (e.g. SI units), but also non-physical units that can be used to define the type of data passed around. This can be for example BOOL or aggregate values. As rule of thumb, the unit list can contain anything that helps two modules automatically negotiate, if they can understand each other.

Note

Extent this list as needed.

Enumerator

UNIT_UNDEF

unit undefined

UNIT_NONE

data has no physical unit

UNIT_TEMP_C

degree Celsius

UNIT_TEMP_F

degree Fahrenheit

UNIT_TEMP_K

Kelvin.

UNIT_LUX

Lux (lx)

UNIT_M

meters

UNIT_M2

square meters

UNIT_M3

cubic meters

UNIT_G

gravitational force

UNIT_DPS

degree per second

UNIT_GR

grams - not using the SI unit (kg) here to make scale handling simpler

Inserts the values in the given dat so that all dim values in values fit inside the limits of the data type, [PHYDAT_MIN, PHYDAT_MAX], and updates the stored scale factor. The value is rounded to the nearest integer if possible, otherwise away from zero. E.g. 0.5 and 0.6 are rounded to 1, 0.4 and -0.4 are rounded to 0, -0.5 and -0.6 are rounded to -1.

Unless compiled with -DPHYDAT_FIT_TRADE_PRECISION_FOR_ROM=0, this function will scale the value -32768, even though it would fit into a phydat_t. Statistically, this precision loss happens in 0.00153% of the calls. This optimization saves a bit more than 20 bytes.

Precondition

The phydat_t::scale member in dat was initialized by the caller prior to calling this function.