Type Translation
- Nina Cardillo
IAP/MQ Connections support type conversions between source and destination types to support connections between sources of one type and destinations of another. All sources and all destinations must themselves be assignment-compatible.
Connections between sources of one type and destinations of another are guided by transcoding rules. Transcoding rules are supplied with the connection data. For example, it is possible to connect an output datapoint that reports the ambient temperature in Fahrenheit, to an input datapoint that expects the ambient temperature in Celsius, but supplying a transformation rule, which computes the Celsius value from the Fahrenheit value.
Connections that require data conversion between source and destination data types may require a facilitator to implement the data conversion, even if the connection is between data points implemented using the same edge protocol within the same segment, and if that edge protocol supports true peer-to-peer connections.
Types are identified with IAP/MQ type references.
- Identical types refers to the same IAP type.
- Assignment-compatible types are types based on different IAP/MQ types, but implement the same quantities and units. For example, a standard “volt” data type and a user-defined “volt” data type could be assignment-compatible, such as if the difference is limited to the supported value range.
All sources in a connection must be at least assignment-compatible. All destinations in a connection must be at least assignment compatible. A specific implementation may require the use of identical types.
Guided transcoding of complex types is based on an optional map, which connects elements of source properties to destination properties. This map can connect source and destination fields of different names, and can provide simple explicit data transformations.
There is one map for the connection. All destinations and all sources must be of the same data type, so that one map can transcode all sources to all destinations.
Multiple distinct connections can be required to implement truly heterogenous datapoint connections.
The map is an associative array using destination property names for keys. The corresponding values are objects that describe the source property.
For example, this simple map transforms a value of standard type SNVT_switch to one of standard type SNVT_lev_percent:
| { "$": "$.value" } |
Key “$” addresses the entire value. Its value is “value”, which references a “value” property within the source datapoint value. “$” addresses the entire source or destination item. A dotted notation addresses nested properties such as “top.left.x”.
This is the identity map:
| { "$": "$" } |
Transformation objects support more complex operations such as type casts or transformation expressions. The following map produces a datapoint value of standard type SNVT_switch from a datapoint value of the standard scalar type SNVT_lev_percent:
| { value: "$", state: { transform: "$ ? 0 : 1" } } |
The first production assigns the entire source value, addressed as “$”, to the destination value property. The second production specifies a transformation with a ternary operator.
The following map converts a value of type SNVT_switch into a simple string presentation:
| { "$": { transform: "$.value + ' ' + $.state" } } |
Transformations support all non-modifying Javascript operators (see developer.mozilla.org). Pre- and post-decrement and increment operators (++, --) have no effect.
Numeric Functions
The following numeric functions are available:
| Function | Result | Description |
|---|---|---|
| abs(v) | v if v ≥ 0, else -v | Absolute of a value |
| min(v, w) | v if v ≤ w, else w | Minimum of two values |
| max(v, w) | v if v ≥ w, else w | Maximum of two values |
| sqrt(v) | Square root of v | Square root function |
| pow(v, w) | v to the power w | Power function |
String Functions
The following string functions are available:
| Function | Result | Comment |
|---|---|---|
| length(s) | Number of characters in s or 0 (zero) if none. | |
| upper(s) | The upper case version of s. | s remains unchanged |
| lower(s) | The lower case version of s. | s remains unchanged |
| substr(s, i, l) | The substring in s starting with zero-based index I and of length l characters. | s remains unchanged |
| match(s, r ) | A Boolean result indicating whether s matched ECMAScript 6 regular expression r. | Example: match(“test”, “[a-z]{4}”) |
The Constant Transformation Type
The $ object represents the source datapoint value.
This constant type map produces a SNVT_switch from a scalar SNVT_lev_percent input, where the destination “state” field is constant:
| { value: "$", state: { constant: "ST_ON" } } |
The constant value is copied into the destination verbatim. The constant transformation is more efficient than an equivalent transform.
The Enumeration Transformation Type
The enumeration type maps two different yet compatible enumerations:
| { value: "$", state: { enumeration: { source: "$", // the source enumeration value map: { 1: -1, // source 1 becomes destination -1, 0: 0, // source 0 remains 0 (the default), -1: 2 // source -1 becomes destination 2 } // map } // enum } // state } // map |
The source property of an enumeration transformation can also be evaluated as an expression. The following example maps the preset value into the preset name:
| { source: { “ON”: ”ON”, “MID”: “MID”, “OFF”: “OFF } // map } // enum } // source } |
Not all conversions, automatic or guided, are possible, perhaps due to ambiguities, or because the connection is implemented using a true peer-to-peer connection, where active conversions may not be possible. These problems are reported with an error event and a “failed” connection status. Data transformation errors, perhaps due to an incorrectly specified map, may occur after the connection has been provisioned.
Type conversion is applied at the data destination. Data sent from segment S1 to segment S2 reaches segment S2 in its original form, and destination segment S2 is responsible for applying suitable data transformation rules.