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.
 

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_scale_to_str (int8_t scale)
 Convert the given scale factor to a NULL terminated string. 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 56 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 74 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_scale_to_str()

char phydat_scale_to_str ( int8_t  scale)

Convert the given scale factor to a NULL terminated string.

The given scaling factor will be given as SI unit (e.g. M for Mega, u for micro, etc) for obvious cases or in scientific notation (e.g. 2E11, 1E-22, etc) otherwise.

Parameters
[in]scalescale factor to convert

◆ 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