Engineering Units

Engineering units are exposed through the EngineeringUnits property (EUInformation) on analog variables (or any variable where this property was added).

When working with Engineering Units in FactoryTalk Optix, you can define custom units in an EngineeringUnitDictionary variable and reference them from the EUInformation of your variables. Alternatively, you can directly assign standard OPC UA engineering units by setting the appropriate UnitId.

AnalogVariables are not required to have engineering units, but when they do, it allows clients to understand the physical meaning of the variable's value and display it accordingly.

EngineeringUnitDictionary

Create an EngineeringUnitDictionary

The following example shows how to create (or overwrite) an EngineeringUnitDictionary variable in Model and add custom engineering units (including a Percent unit with UnitId = 0)

using FTOptix.Core;
using FTOptix.NetLogic;
using UAManagedCore;

public class DesignTimeNetLogic1 : BaseNetLogic
{
    [ExportMethod]
    public void CreateCustomEngineeringUnitDictionary()
    {
        var model = Project.Current.Get("Model");
        if (model == null)
        {
            Log.Warning("DesignTimeNetLogic1", "Model folder not found");
            return;
        }

        const string dictionaryName = "EngineeringUnitDictionary1";

        // Recreate the dictionary to keep this example deterministic.
        var existingDictionary = model.GetVariable(dictionaryName);
        existingDictionary?.Delete();

        var dictionary = InformationModel.MakeVariable(
            dictionaryName,
            FTOptix.Core.DataTypes.EngineeringUnitDictionaryItem,
            FTOptix.Core.VariableTypes.EngineeringUnitDictionary,
            new uint[] { 0 });

        // UnitId values are project-defined for custom units.
        // Percent example: UnitId = 0.
        // Use LocalizedText(text, localeId) to populate Text/LocaleId.
        // LocalizedText("...") alone sets TextId, not Text.
        var units = new EngineeringUnitDictionaryItem[]
        {
            new EngineeringUnitDictionaryItem
            {
                UnitId = 0,
                DisplayName = new LocalizedText("%", "en-US"),
                Description = new LocalizedText("Percentage", "en-US"),
                PhysicalDimension = PhysicalDimension.None,
                Slope = 0.0,
                Intercept = 0.0
            },
            new EngineeringUnitDictionaryItem
            {
                UnitId = 10,
                DisplayName = new LocalizedText("bpm", "en-US"),
                Description = new LocalizedText("Beats per minute", "en-US"),
                PhysicalDimension = PhysicalDimension.Frequency,
                Slope = 60.0,
                Intercept = 0.0
            }
        };

        dictionary.Value = units;
        model.Add(dictionary);

        Log.Info("DesignTimeNetLogic1", $"Created {dictionaryName} with {units.Length} custom units");
    }

Read an EngineeringUnitDictionary

using FTOptix.Core;
using FTOptix.NetLogic;
using UAManagedCore;

public class DesignTimeNetLogic1 : BaseNetLogic
{
    [ExportMethod]
    public void PrintCustomEngineeringUnitDictionary()
    {
        var dictionary = Project.Current.GetVariable("Model/EngineeringUnitDictionary1");
        if (dictionary == null)
        {
            Log.Warning("DesignTimeNetLogic1", "EngineeringUnitDictionary1 not found");
            return;
        }

        if (dictionary.Value.Value is EngineeringUnitDictionaryItem[] typedUnits)
        {
            foreach (var unit in typedUnits)
            {
                Log.Info(
                    "DesignTimeNetLogic1",
                    $"UnitId={unit.UnitId}, DisplayName={unit.DisplayName}, Description={unit.Description}, " +
                    $"PhysicalDimension={unit.PhysicalDimension}, Slope={unit.Slope}, Intercept={unit.Intercept}");
            }

            return;
        }

        // Fallback in case runtime returns a raw Struct array.
        if (dictionary.Value.Value is Struct[] rawUnits)
        {
            foreach (var rawUnit in rawUnits)
            {
                var values = rawUnit.Values;
                if (values == null || values.Count < 6)
                    continue;

                Log.Info(
                    "DesignTimeNetLogic1",
                    $"UnitId={values[0]}, DisplayName={values[1]}, Description={values[2]}, " +
                    $"PhysicalDimension={values[3]}, Slope={values[4]}, Intercept={values[5]}");
            }

            return;
        }

        Log.Warning("DesignTimeNetLogic1", "Engineering unit dictionary has an unexpected value format");
    }
}