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_DBM,
  UNIT_BAR, UNIT_PA, UNIT_CD, UNIT_BOOL,
  UNIT_CTS, UNIT_PERCENT, UNIT_PERMILL, UNIT_PPM,
  UNIT_PPB, 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...
 
void phydat_fit (phydat_t *dat, const int32_t *values, unsigned int dim)
 Scale integer value(s) 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_DBM 

decibel-milliwatts

UNIT_BAR 

Beer?

UNIT_PA 

Pascal.

UNIT_CD 

Candela.

UNIT_BOOL 

boolean value [0|1]

UNIT_CTS 

counts

UNIT_PERCENT 

out of 100

UNIT_PERMILL 

out of 1000

UNIT_PPM 

part per million

UNIT_PPB 

part per billion

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()

void phydat_fit ( phydat_t dat,
const int32_t *  values,
unsigned int  dim 
)

Scale integer value(s) to fit into a phydat_t.

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.

int32_t values[] = { 100000, 2000000, 30000000 };
phydat_t dat = { .scale = 0 };
phydat_fit(&dat, values, 3);
Note
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.
Parameters
[in,out]datthe value will be written into this data array
[in]valuesvalue(s) to rescale
[in]dimNumber of elements in values

◆ 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