Phydat

Generic data container for physical data and utility functions. More...

Detailed Description

Generic data container for physical data and utility functions.

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.

Todo:
It might make sense to introduce additional data types for increased precision, i.e. something like phydat_float_t...

Files

file  phydat.h
 Generic data container for physical data interface.
 

Data Structures

struct  phydat_t
 Generic data structure for expressing physical values. More...
 

Macros

#define PHYDAT_DIM   (3U)
 The fixed number of dimensions we work with. More...
 
#define PHYDAT_SCALE_STR_MAXLEN   (sizeof("*E-128\0"))
 The maximum length of a scaling string.
 
#define PHYDAT_MIN   (INT16_MIN)
 Minimum value for phydat_t::val.
 
#define PHYDAT_MAX   (INT16_MAX)
 Maximum value for phydat_t::val.
 

Enumerations

enum  {
  UNIT_UNDEF, UNIT_NONE, UNIT_TEMP_C, UNIT_TEMP_F,
  UNIT_TEMP_K, UNIT_LUX, UNIT_M, UNIT_M2,
  UNIT_M3, UNIT_G, UNIT_DPS, UNIT_GR,
  UNIT_A, UNIT_V, UNIT_GS, UNIT_BAR,
  UNIT_PA, UNIT_CD, UNIT_BOOL, UNIT_PERCENT,
  UNIT_PERMILL, UNIT_PPM, UNIT_TIME, UNIT_DATE
}
 Definition of physical units and comparable data types. More...
 

Functions

void phydat_dump (phydat_t *data, uint8_t dim)
 Dump the given data container to STDIO. More...
 
const char * phydat_unit_to_str (uint8_t unit)
 Convert the given unit to a string. More...
 
char phydat_prefix_from_scale (int8_t scale)
 Convert the given scale factor to an SI prefix. More...
 
uint8_t phydat_fit (phydat_t *dat, long value, unsigned int index, uint8_t prescale)
 Scale an integer value to fit into a phydat_t. More...
 

Macro Definition Documentation

◆ PHYDAT_DIM

#define PHYDAT_DIM   (3U)

The fixed number of dimensions we work with.

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.

Definition at line 55 of file phydat.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Definition of physical units and comparable data types.

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

UNIT_A 

Ampere.

UNIT_V 

Volts.

UNIT_GS 

gauss

UNIT_BAR 

Beer?

UNIT_PA 

Pascal.

UNIT_CD 

Candela.

UNIT_BOOL 

boolean value [0|1]

UNIT_PERCENT 

out of 100

UNIT_PERMILL 

out of 1000

UNIT_PPM 

part per million

UNIT_TIME 

the three dimensions contain sec, min, and hours

UNIT_DATE 

the 3 dimensions contain days, months and years

Definition at line 73 of file phydat.h.

Function Documentation

◆ phydat_dump()

void phydat_dump ( phydat_t data,
uint8_t  dim 
)

Dump the given data container to STDIO.

Parameters
[in]datadata container to dump
[in]dimnumber of dimension of data to dump

◆ phydat_fit()

uint8_t phydat_fit ( phydat_t dat,
long  value,
unsigned int  index,
uint8_t  prescale 
)

Scale an integer value to fit into a phydat_t.

Insert value at position index in the given dat while rescaling all numbers in dat->val so that value fits inside the limits of the data type, [PHYDAT_MIN, PHYDAT_MAX], and update the stored scale factor. The result will be rounded towards zero (the standard C99 integer division behaviour). The final parameter prescale can be used to chain multiple calls to this function in order to fit multidimensional values into the same phydat_t.

The code example below shows how to chain multiple calls via the prescale parameter

long val0 = 100000;
long val1 = 2000000;
long val2 = 30000000;
dat.scale = 0;
phydat_fit(&dat, val0, 0, phydat_fit(&dat, val1, 1, phydat_fit(&dat, val2, 2, 0)));

The prescale scaling is only applied to value, the existing values in dat are only scaled if the prescaled value does not fit in phydat_t::val

Parameters
[in,out]datthe value will be written into this data array
[in]valuevalue to rescale
[in]indexplace the value at this position in the phydat_t::val array
[in]prescalestart by scaling the value by this exponent
Returns
scaling offset that was applied

◆ phydat_prefix_from_scale()

char phydat_prefix_from_scale ( int8_t  scale)

Convert the given scale factor to an SI prefix.

The given scaling factor is returned as a SI unit prefix (e.g. M for Mega, u for micro, etc), or \0 otherwise.

Parameters
[in]scalescale factor to convert
Returns
SI prefix if applicable
\0 if no SI prefix was found

◆ phydat_unit_to_str()

const char* phydat_unit_to_str ( uint8_t  unit)

Convert the given unit to a string.

Parameters
[in]unitunit to convert
Returns
string representation of given unit (e.g. V or m)
NULL if unit was not recognized