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: Depended on the configured locale the framework tries to convert a QuantityType to the default unit of the matching measurement system. 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:

Dimensiondefault unit metricdefault unit imperial
LengthMeter (m)Inch (in)
TemperatureCelsius (°C)Fahrenheit (°F)
PressureHectopascal (hPa)Inch of mercury (inHg)
SpeedKilometers per hour (km/h)Miles per hour (mph)
IntensityIrradiance (W/m2)Irradiance (W/m2)
DimensionlessAbstract unit one (one)Abstract unit one (one)
AngleDegree (°)Degree (°)

NumberItem linked to QuantityType Channel

In addition to the automated conversion the NumberItem linked to a Channel delivering QuantityTypes can be configured to always have state updates converted to a specific unit. The unit given in the state description is parsed and then used for conversion (if necessary). The framework assumes that the unit to parse is always the last token in the state description. If the parsing failed the locale based default conversion takes place.

Number:Temperature temperature "Outside [%.2f °F]" { channel="...:current#temperature" }

In the example the NumberItem is specified to bind to Channels which offer values from the dimension Temperature. Without the dimension information the NumberItem only will receive updates of type DecimalType without a unit and any conversion. The state description defines two decimal places for the value and the fix unit °F. In case the state description should display the unit the binding delivers or the framework calculates through locale based conversion the pattern will look like this:

"Outside [%.2f %unit%]"

The special placeholder %unit% will then be replaced by the actual unit symbol. In addition the placeholder %unit% can be placed anywhere in the state description.

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.eclipse.smarthome.core.library.unit package contains the classes SIUnits, ImperialUnits and SmartHomeUnits 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. which are wrappers to create derived units. The org.eclipse.smarthome.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:

TypeUnitSymbol
PressureInch of MercuryinHg
TemperatureFahrenheit°F
SpeedMiles per Hourmph
LengthInchin
LengthFootft
LengthYardyd
LengthChainch
LengthFurlongfur
LengthMilemi
LengthLeaguelea

SI:

TypeUnitSymbol
AccelerationMetre per square Secondm/s2
AmountOfSubstanceMolemol
AngleRadianrad
AngleDegree°
AngleMinute Angle'
AngleSecond Angle''
AreaSquare Metrem2
ArealDensityDobson UnitDU
CatalyticActivityKatalkat
DimensionlessPercent%
DimensionlessParts per Millionppm
DimensionlessDecibeldB
ElectricPotentialVoltV
ElectricCapacitanceFaradF
ElectricChargeCoulombC
ElectricConductanceSiemensS
ElectricCurrentAmpereA
ElectricInductanceHenryH
ElectricResistanceOhmΩ
EnergyJouleJ
EnergyWatt SecondWs
EnergyWatt HourWh
EnergyKiloWatt HourkWh
ForceNewtonN
FrequencyHertzHz
IlluminanceLuxlx
IntensityIrradianceW/m²
LengthMetrem
LengthKilometrekm
LuminousFluxLumenlm
LuminousIntensityCandelacd
MagneticFluxWeberWb
MagneticFluxDensityTeslaT
MassKilogramkg
MassGramg
PowerWattW
PressurePascalPa
PressurehectoPascalhPa
PressureMillimetre of MercurymmHg
PressureBarbar
RadioactivityBecquerelBq
RadiationDoseAbsorbedGrayGy
RadiationDoseEffectiveSievertSv
SolidAngleSteradiansr
SpeedMetre per Secondm/s
SpeedKilometre per Hourkm/h
SpeedKnotkn
TemperatureKelvinK
TemperatureCelsius°C
TimeSeconds
TimeMinutemin
TimeHourh
TimeDayd
TimeWeekweek
TimeYeary
VolumeCubic Metrem3

Prefixes:

NameSymbolValue
YottaY10²⁴
ZettaZ10²¹
ExaE10¹⁸
PetaP10¹⁵
TeraT10¹²
GigaG10⁹
MegaM10⁶
Kilok10³
Hectoh10²
Decada10
Decid10⁻¹
Centic10⁻²
Millim10⁻³
Microµ10⁻⁶
Nanon10⁻⁹
Picop10⁻¹²
Femtof10⁻¹⁵
Attoa10⁻¹⁸
Zeptoz10⁻²¹
Yoctoy10⁻²⁴

To use the prefixes simply add the prefix to the unit symbol e.g.

Examples: -milliAmpere - mA -centiMetre - cm -kiloWatt - kW