Converted Values

Table of Contents

• Proportional Scaling
• Linear Conversion
• Multi-Point Linear Interpolation
• Accessing Converted Values

Converted values are skill data points that convert the value of another skill data point using a set of value mappings. The source data point is referred to as the raw value, and must be either a numeric data point, or a Boolean data point. For Boolean data points, the value false is interpreted as 0, and the value true as 1. Converted values support both integers and floating point values as raw values, but the converted value is always a double precision floating point value.

The converted value data point supports the same I/O directions as the raw value data point. If the raw value data point supports the input direction, then its value is automatically converted to a converted value. If the raw data points supports the output direction, any value written to the converted value data point is converted back into a raw value and written to the raw value data point. Both conversions are done automatically and do not require a task to be scheduled.

The conversion is performed using one or more value mappings, each of which specifies the desired converted value for a specific raw value. There are three types of conversions, depending on the number of value mappings you specify. The conversion types are described below.

Proportional Scaling

The simplest type of conversion is a proportional scaling, that simply multiplies the raw value with a fixed factor. A scaling requires only one single value mapping, that specifies the desired value for an arbitrary raw value. Since the scaling is a simple multiplication, a raw value of 0 will have a converted value of 0.

The conversion between raw and converted values for a proportional mapping looks like this:

proportional scaling

The raw value and the converted value can be positive or negative, and the raw value need not lie within the range of the raw value data point. Neither the raw value not the converted value must be 0, however.

Proportional scalings are generally used in three situations:

1. Range mapping: Some devices map a real-world value to the range of values supported by the communication protocol. A device that measures electricat current may scale the supported current value to a 16-bit unsigned integer, for example, to take full advantage of the value range of a Modbus register. So the Modbus register values between 0 and 65535 might represent currents between 0 and 24 A. The converted value data point would, in this case, have a single value mapping, mapping a raw value of 65535 to a converted value of 20.
2. Decoding scaled values: Instead of mapping the real-world value to the entire range of the raw value, some devices will use a fixed scaling factor. The above current measuring device might return the current measurement as a multiple in multiples of 0.1 mA, so that a value of 1 mA is represented by a register value of 10. The converted value data point would, in this case, have a single value mapping, mapping a raw value of 10 to a converted value of 1. (The raw value chosen for the mapping is arbitrary, a mapping of raw value 10 to converted value 1 has the exact same effect as a mapping of raw value 20 to converted value 2, raw value 100 to converted value 10, etc. Only the factor is relevant.)
3. Unit conversion: Some devices might supply values in units other than the ones desired. If the current measuring device reports its value in mA, bit the value shoudl be stored in A in Xentara, a mapping of raw value 1000 to converted value 1 can be used, to convert 1000 mA into 1 A.

Linear Conversion

A linear conversion uses two value mappings to define a linear function that is used to convert the values. A linear conversion is similar to proportional scaling, but a raw value of 0 does not necessarily represent a converted value of 0.

The conversion between raw and converted values for a linear conversion looks like this:

linear conversion

The raw values and converted values can be positive or negative, and the raw values need not lie within the range of the raw value data point. Because the conversion must work in the output as well as the input direction, the mapping must be invertible, however, meaning that neither the two raw values nor the two converted values can be the same.

Linear conversions are generally used in two situations:

1. Range mapping: Some devices map a range of real-world value to the range of values supported by the communication protocol. Often, these mappings map the measurement range of the sensor to the communication range. A barometric pressure sensor may have an operating range of 300 hPa to 1200 hPa, and map that range to the range of a single Modbus register. In this case, the converted value data point would need to mappings, one mapping the lower point of the range, and one mapping the upper range. In this case, the two mappings would map a raw value of 0 to a converted value of 300, and a raw value of 65535 to a converted value of 1200.
2. Complex unit conversion: Some unit conversion cannot be acheived by simple multiplication. A conversion from °F to °C cannot be accomplished by a simple multiplication. To convert from °F to °C, a converted value data point would need two value mappings for two known conversion points, e.g. the freezing and boiling points of water. The two value mappings would thus map a raw value of 32 to a converted value of 0 (freezing), and a raw value of 212 to a converted value of 100 (boiling).

Strictly speaking, linear conversion is a special case of linear interpolation with only two interpolation points.

Multi-Point Linear Interpolation

Multi-point linear interpolation uses a set of value mappings and perfrom a linear interpolation to convert the value. Values that lie between to interpolation points are interpolated, and values that lie outside the range are extrapolated.

The conversion between raw and converted values for a multi-point linear interpolation with five value mappings looks like this:

multi-point linear interpolation

The raw values and converted values can be positive or negative, and the raw values need not lie within the range of the raw value data point. Because the conversion must work in the output as well as the input direction, the mapping must be invertible, however, meaning that the conversion graph must be strictly ascending or strictly descending.

Multi-point linear interpolation is generally used to calibrate a sensor attached to an analog input in the case where the sensor response is non-linear. A set of measurements must be taken, and the obtained raw values mapped to the correct real-world values, resulting in a set of calibration points. These calibration points must then be attached to the converted value data point as value mappings.

Accessing Converted Values

Converted values have the following members:

Attributes

key	The converted value’s primary key.
name	The converted value’s name. The name is the last component of the primary key.
UUID	The unique UUID of the converted value.
type	The converted value’s element type. For converted values, this is always “converted value”.
category	The converted value’s category. For converted values, this is always “data point”.
value	The converted value’s value. This attribute has the same readability and writability as the raw value’s value attribute, meaning that this attribute is readable if the raw value’s value attribute is readable, and writable if the raw value’s value attribute is writable.
updateTime	The last time the value was updated. This attribute is only available for converted values whose raw value supports the input direction.
changeTime	The last time the value changed. This attribute is only available for converted values whose raw value supports the input direction.
quality	The quality of the current value. This attribute is only available for converted values whose raw value supports the input direction.
error	If the quality attribute is anything but “good”, this attribute contains the error that caused the quality to degrade. This attribute is only available for converted values whose raw value supports the input direction.

Events

changed

This event is raised when the value, the quality, or the error changes. This event is only available for converted values whose raw value supports the input direction.

Additionally, the converted value will inherit all attributes and events related to the input and/or output data from its raw value, as applicable. At least the following attributes are inherited from the raw value data point, if is provides them:

• sourceTime
• writeTime
• writeError

Each individual type of skill data point can have additional attributes and events that are inherited by converted values. Please refer to the documentation of the specific skill data point for details. Converted values inherit the same attributes and events as data points.