value.proto

syntax = "proto3";

package hiber.value;

import "google/protobuf/duration.proto";
import "base.proto";

option java_multiple_files = true;
option java_package = "global.hiber.api.grpc.value";
option go_package = ".;hiber";

message Value {
    /* The type of value that is represented. */
    enum Type {
        OTHER = 0;

        /* This field contains numeric values, with an optional unit of measurement defined below. */
        NUMERIC = 1;

        /* This field contains text to be displayed. */
        TEXT = 2;

        /* This field switches between several predefined values. Typically used for status fields. */
        ENUM = 3;
    }

    Type type = 1;
    oneof value {
        Numeric numeric = 2;
        string text = 3;
        Enum enum = 4;
    }

    /* If the value is numeric, this specifies the unit, value, etc. */
    message Numeric {
        /* The type of numeric value that is represented.
         * Supported types will automatically convert to the preferred unit (based on the user settings).
         */
        enum Type {
            TYPE_UNKNOWN = 0;

            /* Battery level, as a percentage. */
            BATTERY_LEVEL = 11;

            /* Distance in metric or imperial units. */
            DISTANCE = 3;

            /* Time period. */
            DURATION = 8;

            /* Volume per time period. */
            FLOW = 12;

            /* Fuel efficiency, e.g. mpg or l/100km. */
            FUEL_EFFICIENCY = 9;

            /* Mass. */
            MASS = 10;

            /* Known unit that is not (yet) supported.
             * This could be a very specific value, like a counter,
             * or something like energy in joules that is not available.
             */
            OTHER = 15;

            /* A percentage, typically 0-100%. */
            PERCENTAGE = 1;

            /* Pressure. */
            PRESSURE = 4;

            /* Count per time period, e.g. the amount of items counted in a 24 hour window. */
            RATE = 14;

            /* Speed that something rotates per time period, typically in revolutions per minute. */
            ROTATION_SPEED = 13;

            /* Temperature. */
            TEMPERATURE = 2;

            /* Speed, e.g. km/h. */
            SPEED = 6;

            /* Voltage, e.g. mV. */
            VOLTAGE = 5;

            /* Volume, e.g. m³. */
            VOLUME = 7;
        }

        /* Special case for battery level, since it can be provided in many units.
         * Not included in the UnitPreferences, since it cannot be converted.
         */
        message BatteryLevel {
            /* Convenience type for battery level. Other units may be added here later, like voltage. */
            enum BatteryLevelUnit {
                /* Battery level as a percentage (technically not a unit). */
                PERCENT = 0;
            }

            BatteryLevelUnit unit = 2;
            reserved 1,3,4;
        }

        /* The value is a distance value, converted to your preferred distance unit. */
        message Distance {
            /* Unit of distance */
            enum DistanceUnit {
                METER = 0; // m
                MILLIMETER = 1; // mm
                CENTIMETER = 2; // cm
                KILOMETER = 3; // km
                YARD = 5; // yd
                MILE = 4; // mi
                FOOT = 6; // '
                INCH = 7; // ″

                /* NM. This is a special case unit and may not be auto-converted to your UnitPreference. */
                NAUTICAL_MILE = 8;
            }
            DistanceUnit unit = 2;
            reserved 1,3,4;
        }

        message Duration {
            /* Unit of duration. */
            enum DurationUnit {
                MILLISECONDS = 0; // ms
                SECONDS = 1; // s
                MINUTES = 2; // min
                HOURS = 3; // h
                DAYS = 4; // d
                WEEKS = 5; // w
            }
            DurationUnit unit = 4;
            google.protobuf.Duration duration = 1;
            reserved 2,3,5;
        }

        message Flow {
            /* Unit of volume per time. */
            enum FlowUnit {
                CUBIC_METER_PER_HOUR = 0; // m³/h
                BARRELS_PER_DAY = 1; // bbl/d
                CUBIC_METER_PER_SECOND = 2; // m³/s
                CUBIC_FEET_PER_HOUR = 3; // ft³/h
                CUBIC_FEET_PER_SECOND = 4; // ft³/s
                LITER_PER_HOUR = 5; // l/h
                LITER_PER_SECOND = 6; // l/s
            }
            FlowUnit unit = 2;
            reserved 1,3,4;
        }

        /* The value is a fuel efficiency value, converted to your preferred fuel efficiency unit. */
        message FuelEfficiency {
            /* Unit of fuel efficiency */
            enum FuelEfficiencyUnit {
                LITER_PER_100_KILOMETER = 0; // l/100km
                KILOMETER_PER_LITER = 1; // km/l
                KILOMETER_PER_GALLON = 2; // km/gal (US)
                KILOMETER_PER_IMPERIAL_GALLON = 3; // km/gal (imp)
                MILES_PER_GALLON = 4; // mpg (US)
                MILES_PER_IMPERIAL_GALLON = 5; // mpg (imp)
                MILES_PER_LITER = 6; // mpl
            }
            FuelEfficiencyUnit unit = 2;
            reserved 1,3,4;
        }

        /* The value is a mass value, converted to your preferred mass unit. */
        message Mass {
            /* Unit of mass. */
            enum MassUnit {
                KILOGRAMS = 0; // kg
                POUNDS = 1; // lb
            }
            MassUnit unit = 2;
            reserved 1,3,4;
        }

        /* Known unit that is not (yet) supported.
         * This could be a very specific value, like a counter,
         * or something like energy in joules that is not available.
         */
        message Other {
        }

        /* The value is a percentage. */
        message Percentage {
            /* Convenience type for percentage. Technically not a unit, but for consistency, we've added it here. */
            enum PercentageUnit {
                /* % */
                PERCENT = 0;
            }
            PercentageUnit unit = 3;
            reserved 1,2,4;
        }

        /* The value is a pressure value, converted to your preferred pressure unit. */
        message Pressure {
            /* Unit of pressure. */
            enum PressureUnit {
                BAR = 0; // bar
                PSI = 1; // psi
                K_PA = 2; // kPa
                KILOGRAM_PER_CENTIMETER_SQUARED = 3; // kg/cm²
            }
            PressureUnit unit = 2;
            reserved 1,3,4;
        }

        message Rate {
            enum RateUnit {
                /* The amount of items counted in a 24 hour window. */
                ITEMS_PER_24_HOURS = 0;
            }
            RateUnit unit = 2;
            uint32 value = 1;
            reserved 3,4;
        }

        /* The value for rotation speed. The only value is revolutions per minute (RPM), therefore it is not included in
         * unit preferences.
         */
        message RotationSpeed {
            enum RotationSpeedUnit {
                REVOLUTIONS_PER_MINUTE = 0; // rpm
            }
            RotationSpeedUnit unit = 2;
            reserved 1,3,4;
        }

        /* The value is a speed value, converted to your preferred speed unit. */
        message Speed {
            /* Unit of speed. */
            enum SpeedUnit {
                KILOMETERS_PER_HOUR = 0; // km/h
                /* kn. This is a special case unit and may not be auto-converted to your UnitPreference. */
                KNOTS = 1;
                METERS_PER_SECOND = 2; // m/s
                MILES_PER_HOUR = 3; // mph
                FEET_PER_SECOND = 4; // ft/s
            }
            SpeedUnit unit = 2;
            reserved 1,3,4;
        }

        /* The value is a temperature, converted to your preferred temperature unit. */
        message Temperature {
            /* Unit of temperature. */
            enum TemperatureUnit {
                KELVIN = 0; // K
                DEGREES_CELSIUS = 1; // °C
                DEGREES_FAHRENHEIT = 2; // °F
            }
            TemperatureUnit unit = 2;
            reserved 1,3,4;
        }

        /* The value is a voltage, converted to your preferred voltage unit. */
        message Voltage {
            /* Unit of voltage. */
            enum VoltageUnit {
                MILLIVOLT = 0; // mV
            }
            VoltageUnit unit = 2;
            reserved 1,3,4;
        }

        /* The value is a volume value, converted to your preferred volume unit. */
        message Volume {
            /* Unit of volume. */
            enum VolumeUnit {
                LITER = 0; // l
                GALLON_US = 1; // gal (US)
                GALLON_IMPERIAL = 2; // gal (imp)
                CUBIC_METER = 3; // m³
                CUBIC_FEET = 4; // ft³
            }
            VolumeUnit unit = 2;
            reserved 1,3,4;
        }

        Type type = 1;
        oneof typed_value {
            BatteryLevel battery_level = 11;
            Distance distance = 3;
            Duration duration = 4;
            FuelEfficiency fuel_efficiency = 14;
            Percentage percentage = 5;
            Pressure pressure = 6;
            Speed speed = 7;
            Temperature temperature = 8;
            Voltage voltage = 9;
            Volume volume = 10;
            Mass mass = 12;
            Flow flow = 13;
            RotationSpeed rotation_speed = 16;
            Rate rate = 17;
            Other other = 22;

            double unknown = 15;
        }

        double value = 2;

        /* Textual representation including unit symbol, rounded based on the user preferences and field config. */
        string textual = 18;

        /* Unit of the value, based on the user preferences. */
        UnitOfMeasurement unit = 19;

        /* Display string of the unit symbol, based on the unit of the value (which is based on user preferences). */
        string unit_symbol = 21;

        /* The original unit, iff this value was converted from another unit because of user preferences. */
        optional UnitOfMeasurement converted_from = 20;
    }

    /* If this value is an enum, this specifies the value, display name and color for this enum value. */
    message Enum {
        /* The enum value. This might be a cryptic value, see the display_name and description for more information. */
        string value = 1;

        /* User-facing name for this value. */
        string display_name = 2;

        /* More details for this enum value. */
        string description = 3;

        /* (Optional) color for this enum value. */
        string color = 4;

        /* Priority of the value, typically used for ordering. */
        int32 priority = 5;
    }
}

/* Get an aggregated value for the selected data (e.g. average).
 * Text fields can only use the LAST aggregation.
 * Enum fields support a subset of aggregations:
 *   - DEFAULT and LAST return the last value;
 *   - MINIMUM and MAXIMUM return the lowest or highest value (respectively) based on the enum value order;
 *   - AVERAGE and SUM are not supported.
 */
enum ValueAggregation {
    DEFAULT = 0;

    /* Return the average value.
     * Not supported for textual and enum fields. When used with these fields, LAST is used instead.
     */
    AVERAGE = 1;

    /* Return the sum all values.
     * Not supported for textual and enum fields. When used with these fields, LAST is used instead.
     */
    SUM = 2;

    /* Just take the last value. */
    LAST = 3;

    /* Return the lowest value.
     * For enum fields, the order of values is used to determine the MINIMUM.
     * Not supported for textual fields. When used with these fields, LAST is used instead.
     */
    MINIMUM = 4;

    /* Return the highest value.
     * For enum fields, the order of values is used to determine the MAXIMUM.
     * Not supported for textual fields. When used with these fields, LAST is used instead.
     */
    MAXIMUM = 5;
}

/* Transform the values into a derived value. */
enum ValueTransformation {
    /* Instead of returning the value, return the amount of time a value was active.
     * Aggregation (if applicable) is applied afterwards on the duration value.
     */
    DURATION = 0;

    /* Instead of returning the value, return the difference between the value and the previous value.
     * Aggregation (if applicable) is applied before the delta is calculated.
     */
    DELTA = 1;
}