Converters

The component IO in ProtoTwin may not always exactly match your PLC tags. For example, the internal units of ProtoTwin are meters and radians, but your PLC may expect values in millimeters and degrees. Converters allow you to easily transform the values before they are transferred between ProtoTwin and the PLC. This avoids needing to modify your PLC program for the purpose of controls testing.

You can configure any binding inside the IO Browser to use a converter:

Open the Bindings tab inside the IO Browser.
Click the small gear icon to the right of the binding, which will open a dialog window.
Select the converter to use from the list and then configure its properties.

Note that only valid converters (according to the tag type, signal type and binding direction) will be listed as options. The gear icon will appear green for any bindings that have a converter configured.

Use Case

ProtoTwin uses: meters, radians, seconds, kilograms and newtons as its internal units. Values that get transferred between the PLC and the ProtoTwin Connect client may need converters. For example, the distance sensor component has a distance output, which represents the distance to a detected object in meters. Your PLC program might expect the distance to be represented by an analog voltage between 0V and 10V. The Range converter can be used to transform the measured distance to a corresponding voltage.

Directionality

The value converters in ProtoTwin have directionality. There are 3 types of converters:

Model Value converters are used to convert (ProtoTwin) model values to (PLC) server values.
Server Value converters are used to convert (PLC) server values to (ProtoTwin) model values.
Bidirectional converters can be used to convert (ProtoTwin) model values to (PLC) server values and (PLC) server values to (ProtoTwin) model values.

Built-In Converters

ProtoTwin includes a number of built-in converters:

Linear Distance

A bidirectional converter that converts a linear distance value. It has the following properties:

Server Distance: Meter, Centimeter, Millimeter, Micrometer, Yard, Foot or Inch.

Angular Distance

A bidirectional converter that converts an angular distance value. It has the following properties:

Server Angle: Radian, Milliradian, Degree, Arcminute, Arcsecond or Turn.

Linear Velocity

A bidirectional converter that converts a linear velocity value. It has the following properties:

Server Distance: Meter, Centimeter, Millimeter, Micrometer, Yard, Foot or Inch.
Server Time: Second, Millisecond, Minute or Hour.

Angular Velocity

A bidirectional converter that converts an angular velocity value. It has the following properties:

Server Angle: Radian, Milliradian, Degree, Arcminute, Arcsecond or Turn.
Server Time: Second, Millisecond, Minute or Hour.

Force

A bidirectional converter that converts a force value. It has the following properties:

Server Force: Newton or Pound Force

Torque

A bidirectional converter that converts a torque value. It has the following properties:

Server Force: Newton or Pound Force
Server Distance: Meter, Centimeter, Millimeter, Micrometer, Yard, Foot or Inch

Boolean Negation

A bidirectional converter that negates a boolean value. This can be used to convert a normally open contact, such as the state output of the push button component, to a normally closed contact.

Range

A bidirectional converter that linearly converts a value between two numeric ranges.

Model Start: The smallest model value.
Model End: The largest model value.
Server Start: The smallest server value.
Server End: The largest server value.
Clamp: Whether to clamp the converted value to the range.

One use of the range converter is to map a linear distance to/from a voltage.

In Range

A model value converter that converts a numeric model value to a boolean server value, according to whether the model value is within a defined range.

Start: The starting value for the range.
End: The ending value for the range.
Invert: Whether the server value should be inverted. The default value is false. Set to true if you want the converter to function as an out-of-range converter.

The range [Start, End] is inclusive, meaning that if the model value is exactly equal to Start or End, then the server value will be true.

Sign

A model value converter that converts a numeric model value to an integral value according to the sign of the model value.

Tolerance: The tolerance either side of zero.

The model value will be converted as follows:

if (Math.abs(modelValue) < this.tolerance) { return 0; }
return Math.sign(modelValue); // 1 if modelValue is positive, -1 if modelValue is negative.

Number to Boolean (Model Value Converter)

A model value converter that converts a numeric model value to a boolean value according to how close it is to a specified value.

True Value: The numeric value that should be converted to true.
Tolerance: The tolerance either side of the true value.

The model value will be converted to true if it is within the tolerance distance of the specified True Value.

Number to Boolean (Server Value Converter)

A server value converter that converts a numeric server value to a boolean value according to how close it is to a specified value.

True Value: The numeric value that should be converted to true.
Tolerance: The tolerance either side of the true value.

The server value will be converted to true if it is within the tolerance distance of the specified True Value.

Boolean to Number (Model Value Converter)

A model value converter that converts a boolean value to a numeric value.

True Value: The converted value when the model value is true.
False Value: The converted value when the model value is false.

Boolean to Number (Server Value Converter)

A server value converter that converts a boolean value to a numeric value.

True Value: The converted value when the server value is true.
False Value: The converted value when the server value is false.

Scripted Converters

It is possible to create your own custom scripted converters, which will be automatically listed as an option when configuring the converter for a binding. Please see the examples provided below:

import { type IModelValueConverter, Util } from "prototwin";

/**
 * Converter that converts model values (in radians) to server values (in degrees) modulo 360 degrees.
 * @remarks Converts 3π radians to 180 degrees, and -π/2 radians to 270 degrees.
 */
export class ModuloAngleConverter implements IModelValueConverter<number, number> {
    /**
     * Converts a (ProtoTwin) model angle (in radians) to a (PLC) server angle (in degrees).
     * @param modelValue The model value.
     * @returns The server value that is written to the PLC tag.
     */
    serverValue(modelValue: number): number {
        return Util.mod(Util.degrees(modelValue), 360);
    }
}

import { type IServerValueConverter, Util } from "prototwin";

/**
 * Converter that scales server values before the model input signals are written. 
 */
export class ScaleConverter implements IServerValueConverter<number, number> {
    /**
     * The scale factor to apply when converting a (PLC) server value to a (ProtoTwin) model value.
     */
    public scale: number = 10;

    /**
     * Converts a (PLC) server value to a (ProtoTwin) model value.
     * @param serverValue The server (tag) value.
     * @returns The model value that the (ProtoTwin) signal should be set to.
     */
    modelValue(serverValue: number): number {
        return serverValue * this.scale;
    }
}

import { type IValueConverter, Name } from "prototwin";

/**
 * Bidirectional value converter that negates a boolean value.
 */
@Name("Boolean Negation")
export class BooleanNegationConverter implements IValueConverter<boolean, boolean> {
    /**
     * Converts a (ProtoTwin) model value to a (PLC) server value.
     * @param modelValue The model value.
     * @returns The server value that is written to the PLC tag.
     */
    serverValue(modelValue: boolean): boolean {
        return !modelValue;
    }

    /**
     * Converts a (PLC) server value to a (ProtoTwin) model value.
     * @param serverValue The server (tag) value.
     * @returns The model value that the (ProtoTwin) signal should be set to.
     */
    modelValue(serverValue: boolean): boolean {
        return !serverValue;
    }
}