This page is part of archived documentation for openHAB **4.1**. Go to the current stable version

# # Units Of Measurement

To express measured values in a scientific correct unit the framework supports units of measurement. By using quantified decimal values in state updates and commands, the framework is able to automatically convert values to a desired unit which may be defined by the system locale or on a per-use-basis.

## # QuantityType

Bindings use the `QuantityType`

to post updates of sensor data with a quantifying unit.
This way the framework and/or the user is able to convert the quantified value to other matching units:

A weather binding which reads temperature values in °C would use the `QuantityType`

to indicate the unit as °C.
The framework is then able to convert the values to either °F or Kelvin according to the configuration of the system.
The default conversion the framework will use is locale-based:
The framework tries to convert a `QuantityType`

to the default unit of the configured locale.
This is the imperial system for the United States (locale US) and Liberia (language tag "en-LR").
The metric system with SI units is used for the rest of the world.
This conversion will convert the given `QuantityType`

into a default unit for the specific dimension of the type.
This is:

Dimension | default unit metric | default unit imperial |
---|---|---|

Acceleration | Meter per square second (m/s²) | Meter per square second (m/s²) |

Amount of Substance | Mole (mol) | Mole (mol) |

Angle | Degree (°) | Degree (°) |

Area | Square Meter (m²) | Square foot (ft²) |

Areal Density | Dobson unit (DU) | Dobson unit (DU) |

Catalytic Activity | Katal (kat) | Katal (kat) |

Data Amount | Byte (B) | Byte (B) |

Data Transfer Rate | Megabit per second (Mbit/s) | Megabit per second (Mbit/s) |

Density | Kilogram per cubic meter (kg/m³) | Kilogram per cubic meter (kg/m³) |

Dimensionless | Abstract unit one (one) | Abstract unit one (one) |

Electric Capacitance | Farad (F) | Farad (F) |

Electric Charge | Coulomb (C) | Coulomb (C) |

Electric Conductance | Siemens (S) | Siemens (S) |

Electric Conductivity | Siemens per meter (S/m) | Siemens per meter (S/m) |

Electric Current | Ampere (A) | Ampere (A) |

Electric Inductance | Henry (H) | Henry (H) |

Electric Potential | Volt (V) | Volt (V) |

Electric Resistance | Ohm (Ω) | Ohm (Ω) |

Energy | Kilowatt hours (kWh) | Kilowatt hours (kWh) |

Force | Newton (N) | Newton (N) |

Frequency | Hertz (Hz) | Hertz (Hz) |

Illuminance | Lux (lx) | Lux (lx) |

Intensity | Irradiance (W/m²) | Irradiance (W/m²) |

Length | Meter (m) | Inch (in) |

Luminous Flux | Lumen (lm) | Lumen (lm) |

Luminous Intensity | Candela (cd) | Candela (cd) |

Magnetic Flux | Weber (Wb) | Weber (Wb) |

Magnetic Flux Density | Tesla (T) | Tesla (T) |

Mass | Kilogram (kg) | Pound (lb) |

Power | Watt (W) | Watt (W) |

Pressure | Hectopascal (hPa) | Inch of mercury (inHg) |

Radiation Absorbed Dose | Gray (Gy) | Gray (Gy) |

Radiation Effective Dose | Sievert (Sv) | Sievert (Sv) |

Radioactivity | Becquerel (Bq) | Becquerel (Bq) |

Solid Angle | Steradian (sr) | Steradian (sr) |

Speed | Kilometers per hour (km/h) | Miles per hour (mph) |

Temperature | Celsius (°C) | Fahrenheit (°F) |

Time | Seconds (s) | Seconds (s) |

Volume | Cubic Meter (m³) | US Gallon (gal) |

Volumetric Flow Rate | Liter per minute (l/min) | US Gallon per minute (gal/min) |

In some cases the system default unit may not be the most useful unit for a given quantity.
For measuring precipitation km/h would be a quite uncommon unit, while mm/h would be the expected unit.
You can set the `unit`

metadata to a different unit to change the item's unit:

```
Number:Speed "Rainfall" { unit="mm/h" }
```

This unit is then also used for persistence.
Setting the `unit`

metadata to `kW`

would persist 5.0 for a value of 5.0 kW (while 5000 would be persisted without because the system default is W).
Attention: Changing the unit of an item may corrupt your already persisted data, no automatic conversion takes place.

The unit of the item is independent of the state description. The state description is used for display purposes only, it can contain any compatible unit and will not affect what is persisted or used in events.

## # Number item with dimension and DecimalType

A `DecimalType`

state update or command to a `Number`

item that contains a dimension is considered to have the item's unit.
So updating a `Number:Length`

item with `5.0`

will set the item's state to 5 m or 5 in. (depending on your locale).
In case you set a different unit (see above, e.g. `km`

) that is taken and the item will set it's state to 5 km.

## # Number item without dimension and QuantityType

A `QuantityType`

state update or command to a non-dimensional `Number`

item will result in a state update that consists of the numeric part only.
So updating a `Number`

item with `5.0 kW`

will set the item's state to 5.0, updating the same item with `5.0 W`

will also set the item's state to 5.0.
Linking dimension channels to non-dimensional items is therefore discouraged and will not be permitted in future versions of openHAB.

### # Defining ChannelTypes

In order to match `NumberItems`

and Channels and define a default state description with unit placeholder the Channel also has to provide an Item type which includes the dimension information:

```
<channel-type id="temperature">
<item-type>Number:Temperature</item-type>
<label>Temperature</label>
<description>Current temperature</description>
<state readOnly="true" pattern="%.1f %unit%" />
</channel-type>
```

The state description pattern "%.1f %unit%" describes the value format as floating point with one decimal place and also the special placeholder for the unit.

## # Implementing UoM

When creating QuantityType states the framework offers some useful packages and classes:
The `org.openhab.core.library.unit`

package contains the classes `SIUnits`

, `ImperialUnits`

and `Units`

which provide units unique to either of the measurement systems and common units used in both systems.

The `MetricPrefix`

class provides prefixes like MILLI, CENTI, HECTO, etc. and the `BinaryPrefix`

class provides prefixes like KIBI, MEBI, etc. both of which are wrappers to create derived units.

The `org.openhab.core.library.dimension`

and `javax.measure.quantity`

packages provide interfaces which are used to type the generic QuantityType and units.

## # List of Units

All units which are currently supported by default are listed in the tables below.

Imperial (base unit symbols):

Type | Unit | Symbol |
---|---|---|

Length | Inch | in |

Length | Foot | ft |

Length | Yard | yd |

Length | Chain | ch |

Length | Furlong | fur |

Length | Mile | mi |

Length | League | lea |

Pressure | Inch of Mercury | inHg |

Pressure | Pound per square inch | psi |

Speed | Miles per Hour | mph |

Temperature | Fahrenheit | °F |

Volume | Gallon (US) | gal |

VolumetricFlowRate | Gallon (US) per minute | gal/min |

SI (base unit symbols):

Type | Unit | Symbol |
---|---|---|

Acceleration | Metre per Second squared | m/s² |

Acceleration | Standard Gravity | ɡₙ |

AmountOfSubstance | Mole | mol |

AmountOfSubstance | Deutscher Härtegrad | °dH |

Angle | Radian | rad |

Angle | Degree | ° |

Angle | Minute Angle | ' |

Angle | Second Angle | '' |

Area | Square Metre | m² |

ArealDensity | Dobson Unit | DU |

CatalyticActivity | Katal | kat |

DataAmount | Bit | bit |

DataAmount | Byte | B |

DataAmount | Octet | o |

DataTransferRate | Bit per Second | bit/s |

Density | Gram per cubic Metre | g/m³ |

Dimensionless | Percent | % |

Dimensionless | Parts per Million | ppm |

Dimensionless | Decibel | dB |

ElectricPotential | Volt | V |

ElectricCapacitance | Farad | F |

ElectricCharge | Coulomb | C |

ElectricCharge | Ampere Hour | Ah |

ElectricConductance | Siemens | S |

ElectricConductivity | Siemens per Metre | S/m |

ElectricCurrent | Ampere | A |

ElectricInductance | Henry | H |

ElectricResistance | Ohm | Ω |

Energy | Joule | J |

Energy | Watt Second | Ws |

Energy | Watt Hour | Wh |

Energy | Volt-Ampere Hour | VAh |

Energy | Volt-Ampere Reactive Hour | varh |

Energy | Calorie | cal |

Force | Newton | N |

Frequency | Hertz | Hz |

Frequency | Revolutions per minute | rpm |

Illuminance | Lux | lx |

Intensity | Irradiance | W/m² |

Intensity | Microwatt per square Centimeter | µW/cm² |

Length | Metre | m |

LuminousFlux | Lumen | lm |

LuminousIntensity | Candela | cd |

MagneticFlux | Weber | Wb |

MagneticFluxDensity | Tesla | T |

Mass | Gram | g |

Power | Watt | W |

Power | Volt-Ampere | VA |

Power | Volt-Ampere Reactive | var |

Power | Decibel-Milliwatts | dBm |

Pressure | Pascal | Pa |

Pressure | Hectopascal | hPa |

Pressure | Millimetre of Mercury | mmHg |

Pressure | Bar | bar |

Radioactivity | Becquerel | Bq |

RadiationDoseAbsorbed | Gray | Gy |

RadiationDoseEffective | Sievert | Sv |

RadiationSpecificActivity | Curie | Ci |

SolidAngle | Steradian | sr |

Speed | Metre per Second | m/s |

Speed | Knot | kn |

Temperature | Kelvin | K |

Temperature | Celsius | °C |

Temperature^ | Mired | mired |

Time | Second | s |

Time | Minute | min |

Time | Hour | h |

Time | Day | d |

Time | Week | week |

Time | Year | y |

Volume | Litre | l |

Volume | Cubic Metre | m³ |

VolumetricFlowRate | Litre per Minute | l/min |

VolumetricFlowRate | Cubic Metre per Second | m³/s |

VolumetricFlowRate | Cubic Metre per Minute | m³/min |

VolumetricFlowRate | Cubic Metre per Hour | m³/h |

VolumetricFlowRate | Cubic Metre per Day | m³/d |

^: Technically, mireds are the reciprocal of Temperature, but QuantityType and NumberItem will transparently convert between mireds and Kelvin.
This technicality might be a problem if you are using mireds in rules.
Be sure to use the `toInvertibleUnit`

method on QuantityType, rather than `toUnit`

.

Metric Prefixes:

Name | Symbol | Factor |
---|---|---|

Yotta | Y | 10²⁴ |

Zetta | Z | 10²¹ |

Exa | E | 10¹⁸ |

Peta | P | 10¹⁵ |

Tera | T | 10¹² |

Giga | G | 10⁹ |

Mega | M | 10⁶ |

Kilo | k | 10³ |

Hecto | h | 10² |

Deca | da | 10 |

Deci | d | 10⁻¹ |

Centi | c | 10⁻² |

Milli | m | 10⁻³ |

Micro | µ | 10⁻⁶ |

Nano | n | 10⁻⁹ |

Pico | p | 10⁻¹² |

Femto | f | 10⁻¹⁵ |

Atto | a | 10⁻¹⁸ |

Zepto | z | 10⁻²¹ |

Yocto | y | 10⁻²⁴ |

Binary Prefixes:

Name | Symbol | Factor |
---|---|---|

Kibi | ki | 2¹⁰ |

Mebi | Mi | 2²⁰ |

Gibi | Gi | 2³⁰ |

Tebi | Ti | 2⁴⁰ |

Pebi | Pi | 2⁵⁰ |

Exbi | Ei | 2⁶⁰ |

Zebi | Zi | 2⁷⁰ |

Yobi | Yi | 2⁸⁰ |

To use the prefixes simply add the prefix to the unit symbol - for example:

- milliAmpere -
`mA`

- centiMetre -
`cm`

- kiloWatt -
`kW`

- KibiByte -
`kiB`

*Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)*

← Audio & Voice Rules →