Units Guide

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-complied.

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.

Why UCUM?

We chose UCUM because it solves two critical problems in unit handling:

1. Automatic conversion — UCUM enables consistent conversion between units (e.g. from bar to Pa, or L/min to m³/h).
2. Unambiguous representation — Unlike informal or inconsistent abbreviations, UCUM defines exactly what each unit means. For example:

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

Manifest Features

Autoscale

With autoscaling, you can define custom conversion rules for any property or telemetry attribute. 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.

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

auto_scale

Defines preferred units for automatically converting and displaying values based on their magnitude.

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.
    type: custom
  kg:
    display_name: kilogram
    symbol: kg 
    type: ucum

display_namerequired

A unit name which will be shown in the UI.

symbolrequired

A unit label which will be shown in the UI.

typerequired

Can have one of the following values:

• custom - it won't be validated as a UCUM unit or autoscaled.
• ucum - it will be validated as a UCUM unit and can be autoscaled.

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

allow_unit_c

Allows to use C as Coulomb unit label.

allow_unit_f

Allows to use F as Farad unit label.