Units of Measurement

Introduction

What is a Unit?

A unit defines the measurement used to express the value of a property or telemetry field. In Enapter Blueprints, the unit property determines how values are displayed in dashboards and the user interface, and it must be UCUM-compliant.

What is UCUM?

UCUM (Unified Code for Units of Measure) is a standardized system for representing measurement units in a precise, machine-readable, and unambiguous way. It covers a wide range of scientific, engineering, and industrial units and is designed specifically for use in software systems.

UCUM solves the most critical problem in unit handling — unambiguous representation. Unlike informal or inconsistent abbreviations, UCUM defines exactly what each unit means.

This makes UCUM ideal for powering reliable, standardized data display and processing in Enapter systems.

Units Typography

Units can be written in two forms: symbols or full codes. Symbols are short names for units: kg, m, s. The full codes are kilogram, meter, second.

It's not possible to mix different forms: You cannot write kilometer/h or kg.meter.

Manifest Features

Autoscale

For example, a device may send data in kilowatts. If the value is smaller or larger (e.g., 0.8 kW or 1000 kW), it is usually preferable to convert it to 800 W and 1 MW, respectively, for display in the UI.

You can define custom conversion rules for any property or telemetry attribute via the ui.auto_scale option:

telemetry:
  power:
    display_name: Power
    type: float
    unit: kW
    ui:
      auto_scale: [W, kW, MW]

That means the UI will use only W, kW, and MW for autoscale.

This feature also means you can completely disable autoscaling by setting one value into the auto_scale array.

The rules for unit values in auto_scale:

• The original unit is not automatically added to auto_scale. You should add it manually if needed.
• Units in auto_scale can differ from the original unit only by prefix (kilo/k, mega/M). So you cannot autoscale inches into meters. The only exception is for duration units (second, minute, hour, etc.).
• For complex units like km/h, only the first unit can be autoscaled. It means m/h or cm/h is available for autoscaling, but km/s or meter/day is not.

Custom Units

If the available UCUM units don’t fit your specific use case, you can define custom units. This allows you to display values using your own unit names or symbols, exactly how you want them to appear in the UI.

units:
  apple:
    display_name: Apple
    symbol: apl.

Please note that custom units cannot be autoscaled. Feel free to reach out to us via Discord to let us know that you need an extra unit with the autoscaling feature.

Allow Ambiguous Units

In the UCUM system:

• C represents Coulomb
• F represents Farad

While temperature units are:

• Cel for Degrees Celsius
• [degF] for Fahrenheit

To prevent misinterpretation (e.g., mistakenly using C for Celsius), the system raises an error if C or F are used without clarification.

If you really want to include Coulomb and Farad in your manifest:

1. Use coulomb or farad to avoid ambiguity.
2. Set allow_unit_c or allow_unit_f to true.

A valid example:

properties:
  battery_charge:
    display_name: Battery Charge
    unit: C  # Coulombs
    type: float
    allow_unit_c: true

  capacitor_value:
    display_name: Capacitance
    unit: F  # Farads
    type: float
    allow_unit_f: true

telemetry:
  total_charge:
    display_name: Total Charge
    unit: coulomb  # Using full name, no flag needed
    type: float

  capacitor_rating:
    display_name: Capacitor Rating
    unit: farad  # Using full name, no flag needed
    type: float