org.eclipse.mdm.nucleus/org.eclipse.mdm.businessobjects/src/main/proto/mdm.proto

/********************************************************************************
 * Copyright (c) 2015-2018 Contributors to the Eclipse Foundation
 *
 * See the NOTICE file(s) distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 ********************************************************************************/
syntax = "proto3";

package org.eclipse.mdm.protobuf;

import "google/protobuf/timestamp.proto";

/**
 * Specifies if the MeasuredValues contain the final values or the generation parameters.
 */
enum ValuesMode {
		/**
		 * MeasuredValues will contain the final values, calculated for non-explicit
		 * sequence representations using generation parameters and, if applicable, the
		 * raw values. No generation parameters are returned in the resulting
		 * MeasuredValues, SequenceRepresentation will be EXPLICIT.
		 */
		CALCULATED = 0;
		/**
		 * MeasuredValues will contain the (raw) values and generation parameters as
		 * present in the storage.
		 */
		STORAGE = 1;
}

/**
 * Scalar type enumeration represents the datatype of MeasuredValues.
 */
enum ScalarType {
	STRING = 0;          // MeasuredValues are provided as StringArray
	DATE = 1;            // MeasuredValues are provided as DateArray
	BOOLEAN = 2;         // MeasuredValues are provided as BooleanArray
	BYTE = 3;            // MeasuredValues are provided as ByteArray
	SHORT = 4;           // MeasuredValues are provided as ShortArray
	INTEGER = 5;         // MeasuredValues are provided as IntegerArray
	LONG = 6;            // MeasuredValues are provided as LongArray
	FLOAT = 7;           // MeasuredValues are provided as FloatArray
	DOUBLE = 8;          // MeasuredValues are provided as DoubleArray
	BYTE_STREAM = 9;     // MeasuredValues are provided as ByteStreamArray
	FLOAT_COMPLEX = 10;  // MeasuredValues are provided as FloatComplexArray
	DOUBLE_COMPLEX = 11; // MeasuredValues are provided as DoubleComplexArray
	ENUMERATION = 12;    // not used for MeasuredValues
	FILE_LINK = 13;      // not used for MeasuredValues
	BLOB = 14;           // not used for MeasuredValues
	UNKNOWN = 15;        // not used for MeasuredValues
}

/**
 * This is the axis type enumeration as defined in the ASAM ODS NVH model.
 */
enum AxisType {
	X_AXIS = 0;  // A Channel of this type may be displayed as the x-axis.
	Y_AXIS = 1;  // A Channel of this type may be displayed as the y-axis.
	XY_AXIS = 2; // A Channel of this type may be displayed as the x- or y-axis.
}

/**
 * The sequence representation to describe the storage type of measured values.
 */
enum SequenceRepresentation {
  /**
	 * Measured values are stored as is and values are therefore immediately
	 * available.
	 */
	EXPLICIT = 0;
	/**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> = p for i
	 * &isin; [1, n], n is the total number of values and generation parameter p
	 * (offset).
	 */
	IMPLICIT_CONSTANT = 1;
	  /**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> =
	 * p<sub>1</sub>+(i-1)*p<sub>2</sub> for i &isin; [1, n], n is the total number
	 * of values and generation parameters p<sub>1</sub> (start value) and
	 * p<sub>2</sub> (increment).
	 */
	IMPLICIT_LINEAR = 2;
	/**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> =
	 * p<sub>1</sub>+((i-1)mod(p<sub>3</sub>-p<sub>1</sub>)/p<sub>2</sub>)*
	 * p<sub>2</sub> for i &isin; [1, n], n is the total number of values and
	 * generation parameters p<sub>1</sub> (start value), p<sub>2</sub> (increment)
	 * and p<sub>3</sub> (number of values per saw). The expression
	 * (p<sub>3</sub>-p<sub>1</sub>)/p<sub>2</sub> must be truncated to integer to
	 * start each saw curve cycle at p<sub>1</sub>.
	 */
	IMPLICIT_SAW = 3;
	/**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> =
	 * p<sub>1</sub>+p<sub>2</sub>*r<sub>i</sub> for i &isin; [1, n], n is the total
	 * number of values and generation parameters p<sub>1</sub> (offset),
	 * p<sub>2</sub> (factor) and the raw value r at position i.
	 */
	RAW_LINEAR = 4;
	/**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> = &sum;
	 * p<sub>j</sub>*r<sub>i</sub><sup>j-1</sup> = p<sub>2</sub>+p<sub>3
	 * </sub>*r<sub>i</sub>+p<sub>4</sub>*r<sub>i</sub><sup>2</sup>+... for i &isin;
	 * [1, n], n is the total number of values and generation parameters
	 * p<sub>j</sub> for j &isin; [1, p<sub>1</sub>] and the raw value r at position
	 * i.
	 */
	RAW_POLYNOMIAL = 5;
	/*
	 * Not used. But keep here to show ordinal sequence.
	 */
	FORMULA = 6;
	/**
	 * Measured values are stored as is in an external file and values are therefore
	 * immediately available.
	 */
	EXPLICIT_EXTERNAL = 7;
	/**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> =
	 * p<sub>1</sub>+p<sub>2</sub>*r<sub>i</sub> for i &isin; [1, n], n is the total
	 * number of values and generation parameters p<sub>1</sub> (offset),
	 * p<sub>2</sub> (factor) and the raw value r at position i read from an
	 * external file.
	 */
	RAW_LINEAR_EXTERNAL = 8;
	/**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> = &sum;
	 * p<sub>j</sub>*r<sub>i</sub><sup>j-1</sup> = p<sub>2</sub>+p<sub>3
	 * </sub>*r<sub>i</sub>+p<sub>4</sub>*r<sub>i</sub><sup>2</sup>+... for i &isin;
	 * [1, n], n is the total number of values and generation parameters
	 * p<sub>j</sub> for j &isin; [1, p<sub>1</sub>] and the raw value r at position
	 * i read from an external file.
	 */
	RAW_POLYNOMIAL_EXTERNAL = 9;
	/**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> =
	 * (p<sub>1</sub>+p<sub>2</sub>*r<sub>i</sub>)*p<sub>3</sub> for i &isin; [1,
	 * n], n is the total number of values and generation parameters p<sub>1</sub>
	 * (offset), p<sub>2</sub> (factor), p<sub>2</sub> (calibration) and the raw
	 * value r at position i.
	 */
	RAW_LINEAR_CALIBRATED = 10;
	/**
	 * Each value x<sub>i</sub> is generated as follows: x<sub>i</sub> =
	 * (p<sub>1</sub>+p<sub>2</sub>*r<sub>i</sub>)*p<sub>3</sub> for i &isin; [1,
	 * n], n is the total number of values and generation parameters p<sub>1</sub>
	 * (offset), p<sub>2</sub> (factor), p<sub>2</sub> (calibration) and the raw
	 * value r at position i read from an external file.
	 */
	RAW_LINEAR_CALIBRATED_EXTERNAL = 11;
}

/**
 * This class provides all required informations to load measured values.
 */
 message ReadRequest {
	string channel_group_id = 1;     // ID of the ChannelGroup which Channel values are requested.

	repeated string channel_ids = 2; // IDs of the channels to load. If empty, all channels are loaded.
	/**
	 * IDSs of the units in which the corresponding channel values (i.e. the channels at the same index as in channel_ids)
	 * are loaded. A missing or empty string is interpreted as the default unit of the channel.
	 * Superfluous unit IDs are ignored.
	 */
	repeated string unit_ids = 3;

	int32 request_size = 4;          // Number of requested values
	int32 start_index = 5;           // Start index of the requested values

	ValuesMode values_mode = 6;      // Mode in which the values are returned. See description of ValueMode enum.
}

/**
 * This message represents a complex value with real and imaginary parts of type float.
 */
message FloatComplex {
	float re = 1; // The real part.
	float im = 2; // The imaginary part.
}

/**
 * This message represents a complex value with real and imaginary parts of type double.
 */
message DoubleComplex {
	double re = 1; // The real part.
	double im = 2; // The imaginary part.
}

message StringArray        { repeated string values = 1; }
message DateArray          { repeated google.protobuf.Timestamp values = 1; }
message BooleanArray       { repeated bool   values = 1 [packed=true]; }
message ByteArray          {          bytes  values = 1; }
message ShortArray         { repeated int32  values = 1 [packed=true]; }
message IntegerArray       { repeated int32  values = 1 [packed=true]; }
message LongArray          { repeated int64  values = 1 [packed=true]; }
message FloatArray         { repeated float  values = 1 [packed=true]; }
message DoubleArray        { repeated double values = 1 [packed=true]; }
message ByteStreamArray    { repeated bytes  values = 1; }
message FloatComplexArray  { repeated FloatComplex  values = 1; }
message DoubleComplexArray { repeated DoubleComplex values = 1; }

/**
 * This message represents a sequence of measured values for one Channel.
 */
message MeasuredValues {
	string name = 1;                                         // Name of the channel
	string unit = 2;                                         // Unit of the values
	int32 length = 3;                                        // Length of the channel

	SequenceRepresentation sequence_representation = 4;      // The SequenceRepresentation of the measured values.
	repeated double generation_parameters = 5 [packed=true]; // The generation parameters of the channel
	bool independent = 6;                                    // The independent flag of the channel
	AxisType axis_type = 7;                                  // The axis type of the channel
	ScalarType scalar_type = 8;                              // Scalar type of the channel's values
	oneof values {
		StringArray         string_array = 9;                // STRING
		DateArray           date_array = 10;                 // DATE
		BooleanArray        boolean_array = 11;              // BOOLEAN
		ByteArray           byte_array = 12;                 // BYTE
		ShortArray          short_array = 13;                // SHORT
		IntegerArray        integer_array = 14;              // INTEGER
		LongArray           long_array = 15;                 // LONG
		FloatArray          float_array = 16;                // FLOAT
		DoubleArray         double_array = 17;               // DOUBLE,
		ByteStreamArray     byte_stream_array = 18;          // BYTE_STREAM
		FloatComplexArray   float_complex_array = 19;        // FLOAT_COMPLEX
		DoubleComplexArray  double_complex_array = 20;       // DOUBLE_COMPLEX
		// The following datatypes are not supported in ODS for measuredvalues: ENUMERATION, FILE_LINK, BLOB, UNKNOWN
	}                                                        // the actual measured values
	repeated bool flags = 21 [packed=true];                  // The flags of the measured values
}

/**
 * Container for a list of MeasuredValues
 */
message MeasuredValuesList {
	repeated MeasuredValues values = 1; // List of MeasuredValues
}

/**
 * Container for a list of WriteRequests
 */
message WriteRequestList {
	/**
	 * Holds required data to write mass data.
	 */
	message WriteRequest {
		message ExplicitData {
			oneof values {
				StringArray         string_array = 1;          // STRING
				DateArray           date_array = 2;            // DATE
				BooleanArray        boolean_array = 3;         // BOOLEAN
				ByteArray           byte_array = 4;            // BYTE
				ShortArray          short_array = 5;           // SHORT
				IntegerArray        integer_array = 6;         // INTEGER
				LongArray           long_array = 7;            // LONG
				FloatArray          float_array = 8;           // FLOAT
				DoubleArray         double_array = 9;          // DOUBLE,
				ByteStreamArray     byte_stream_array = 10;    // BYTE_STREAM
				FloatComplexArray   float_complex_array = 11;  // FLOAT_COMPLEX
				DoubleComplexArray  double_complex_array = 12; // DOUBLE_COMPLEX
				// The following datatypes are not supported in ODS for measuredvalues: ENUMERATION, FILE_LINK, BLOB, UNKNOWN
			} // the actual values

			repeated bool flags = 13 [packed=true];            // The flags of the measured values
		}

		/**
		 * Configures a WriteRequest to create an implicit linear sequence
		 * of measured values. See org.eclipse.mdm.api.base.massdata.WriteRequestBuilder.implicitLinear(ScalarType, double, double)
		 */
		message ImplicitLinear {
			ScalarType scalar_type = 1; // Scalar type of the channel's values
			double start = 2;           // The start value of the line.
			double increment = 3;       // The gradient of the line.
		}

		/**
		 * Configures a WriteRequest to create an implicit saw sequence
		 * of measured values. See org.eclipse.mdm.api.base.massdata.WriteRequestBuilder.implicitSaw(ScalarType, double, double, double).
		 */
		message ImplicitSaw {
			ScalarType scalar_type = 1; // Scalar type of the channel's values
			double start = 2;           // The start value of each saw cycle.
			double increment = 3;       // The increment.
			double stop = 4;            // The stop value of each saw cycle. The stop value is exclusive.
		}

		/**
		 * Configures a WriteRequest to create an implicit constant sequence
		 * of measured values. See org.eclipse.mdm.api.base.massdata.WriteRequestBuilder.implicitConstant(ScalarType, double).
		 */
		message ImplicitConstant {
			ScalarType scalar_type = 1; // Scalar type of the channel's values
			double offset = 2;          // The constant value.
		}

		/**
		 * Configures the WriteRequest to create a raw linear sequence of
		 * measured values. See org.eclipse.mdm.api.base.massdata.WriteRequestBuilder.rawLinear(double, double)
		 */
		message RawLinear {
			ScalarType scalar_type = 1; // Scalar type of the channel's values
			double offset = 2;          // The offset for each value.
			double factor = 3;          // The factor for each value.
			ExplicitData values = 4;    // The raw values.
		}

		/**
		 * Configures the WriteRequest to create a raw polynomial sequence of
		 * measured values. See org.eclipse.mdm.api.base.massdata.WriteRequestBuilder.rawPolynomial(double...)
		 */
		message RawPolynomial {
			ScalarType scalar_type = 1;       // Scalar type of the channel's values
			repeated double coefficients = 2; // At least 2 coefficients must be provided.
			ExplicitData values = 3;          // The raw values.
		}

		/**
		 * Configures the WriteRequest to create a raw linear calibrated sequence of
		 * measured values. See org.eclipse.mdm.api.base.massdata.WriteRequestBuilder.rawLinearCalibrated(double, double, double)
		 */
		message RawLinearCalibrated {
			ScalarType scalar_type = 1; // Scalar type of the channel's values
			double offset = 2;          // The offset for each value.
			double factor = 3;          // The factor for each value.
			double calibration = 4;     // The calibration factor.
			ExplicitData values = 5;    // The raw values.
		}

		string channel_group_id = 1;    // The ChannelGroup for this request.
		string channel_id = 2;          // The Channel specified mass data will be dedicated to.
		AxisType axis_type = 3;         // The AxisType of the written mass data.
		bool independent = 4;           // The independent flag for the Channel
		oneof data {
			ExplicitData explicit = 5;
			ImplicitConstant implicit_constant = 6;
			ImplicitLinear implicit_linear = 7;
			ImplicitSaw implicit_saw = 8;
			RawLinear raw_linear = 9;
			RawPolynomial raw_polynomial = 10;
			RawLinearCalibrated raw_linear_calibrated = 11;
		}                               // The mass data for this Channel
		string source_unit_id = 12;     // The source Unit ID for the data. (Hint this not implemented as of version 5.1.0M6)
	}
	repeated WriteRequest values = 1;   // The List of WriteRequests
}

/**
 * Message to request preview values.
 * Preview values are only provided for numerical Datatypes.
 * If channels with other Datatypes are requested, an empty MeasuredValues message is returned.
 */
message PreviewRequest {
	ReadRequest read_request = 1; // Read request, which specifies which data should be read.
	int32 number_of_chunks = 2;   // Number of chunks, e.g. number of values returned by the preview request.
}

/**
 * Message containing preview data requested by a PreviewRequest
 */
message PreviewValuesList {
	repeated MeasuredValues min = 1; // minimum values for each chunk
	repeated MeasuredValues avg = 2; // average values for each chunk
	repeated MeasuredValues max = 3; // maximum values for each chunk
}