Version: 2.8

DataNodes

Defines a data value in the node space. The data node manages a single entity, often a value of primitive datatype. This node type can be used to observe machine states and memory values of devices.

Attribute	Description	Data Type
Id	Id of the data value	`System.Guid`
Name	Name of the data value	`System.String`
DataType	Data type of the value	`System.String`
DataClass	Data class of the value (Event (default): Data value is event based; Stream: Data value is stream based)	`EDataClass`
Unit	Physical unit of the value	`System.String`
HistoryMode	Historization model of the data node. The history mode declares how to historize the messages in the database.

The data class describes the kind of data acquired from the device. Two types exist: events and streams.

Data Class	Description
`Event`	Events are value changes which occur. No further values exist between two events.
`Stream`	Value streams have infinite values between two acquired values.

NOTE

Technically event and stream based data nodes are both treated equally on value refresh by a driver. In combination with history, there however are differences. If specified as 'sampled' type, only value changes are historized, whereas a sampling based type is recorded at its set history sampling rate.

Notes for MT-Connect: DataClass Event maps to data item type EVENT, and DataClass Stream maps to SAMPLE.

Example:

{
  "Id": "95C03595-6408-4ADD-A927-96A50C4D2598",
  "Name": "RunningState",
  "DataType": "System.Int32",
  "DataClass": "Event", 
  "Value": 1001,
  "Unit":  "km",
  "HistoryMode": {
    "Retention": 20,
    "SamplingRate": 2000
  }
}

Data Types

Following data types are allowed for "DataType":

System.String and System.String[]
System.Single and System.Single[]
System.Double and System.Double[]
System.Decimal and System.Decimal[]
System.SByte and System.SByte[]
System.Int16 and System.Int16[]
System.Int32 and System.Int32[]
System.Int64 and System.Int64[]
System.Byte and System.Byte[]
System.UInt16 and System.UInt16[]
System.UInt32 and System.UInt32[]
System.UInt64 and System.UInt64[]
System.Boolean and System.Boolean[]
System.DateTime and System.DateTime[]
System.Guid and System.Guid[]
HumanOS.Kernel.DataModel.Entity.TGenericEntity, HumanOS.Kernel.Base
HumanOS.Kernel.DataModel.Entity.TGenericEntity[], HumanOS.Kernel.Base

NOTE

The data type HumanOS.Kernel.DataModel.Entity.TGenericEntity, HumanOS.Kernel.Base is used to aggregate information into a single data node. Often the aggregation is realized with data processors.

NOTE

If using HumanOS.Kernel.DataModel.Entity.TGenericEntity, HumanOS.Kernel.Base, the property SelectedEntityType can be used to reference a specific entity type specification for this data node.

Trigger Types

The trigger type defines how a data node handles value and state events.

TriggerType	Description
`Default`	Default settings of the HumanOS Kernel. Currently set to `OnChange`
`OnEvent`	The data node is triggered on any event (value or state).
`OnChange`	The data node is triggered if the value or the state has been changed.
`OnPositiveFlank`	The data node is triggered if the value has a positive flank to its previous value.
`OnNegativeFlank`	The data node is triggered if the value has a negative flank to its previous value.
`None`	The data node is not triggered at all.

NOTE

OnPositiveFlank and OnNegativeFlank can only be used for numerical values and strings. For strings, a positive flank is a string in higher alphabetical order, a negative flank vis-versa.

DataNode Extension for UHAL Plugins

There are some extensions for data node specifications on the UHAL. Here, the binding to outside system is configured.

Attribute	Description	Data Type
Address	Hardware address used by the connector to get or set data.	`System.String`
Access	Defines the details of the access to the outside system.	`TDataAccessInfo`

The TDataAccessInfo has following attributes:

Attribute	Description	Data Type
Read	Flag, if the synchronous reading is allowed	`System.Boolean`
Receive	Flag, if the asynchronous reading is allowed (event based)	`System.Boolean`
Write	Flag, if the synchronous writing is allowed	`System.Boolean`
ReadConversion	Optional instructions to convert the data before passing to node space	`TDataConversionInfo`
WriteConversion	Optional instructions to convert the data before passing to the system	`TDataConversionInfo`

The TDataConversionInfo is defined by following attributes:

Attribute	Description	Data Type
Type	Conversion type None SimpleExpression Mapping .	`EConversionType`
Instruction	Instruction syntax depending on the type field	`System.String`

Simple Conversion Expressions

Values can be transformed using a simple expression notation. The expression contains a variable called Value denoting the value to convert.

Depending the data type, different function can be used.

Functions for Numbers

Some functions useful from the System.Math library:

Math.Abs(Value) : absolute value
Math.Round(Value, n) : round the value to n-digits.
Math.Ceiling(Value) : ceiling the value
Math.Floor(Value) : floor the value
Math.Sin(Value) and Math.Asin(Value) : Sinus and arcus sinus value
Math.Cos(Value) and Math.Acos(Value) : Co-sinus and arcus co-sinus value
Math.Tan(Value) and Math.Atan(Value) : Tangents and arcus tangents value
Math.Sqrt(Value) : square root of value
Math.Pow(Value, n) : n-th power of value
Math.Log10(Value) : 10-th logarithm of value
Math.Log(Value, n) : n-th logarithm of value

Constants

Math.E: number e
Math.PI: number PI
Math.Tau: number tau

Functions for Strings

NOTE

Strings and arrays are using zero based indexes. [0] accesses the first element in a string.

Some useful string manipulations:

Value.Substring(s) : Extracting a substring starting from start index s to the end of the string.
Value.Substring(s, len) : Extracting a substring starting from start index s and length len.
Value.Insert(\"Test\", n) : Inserts Test at position n in the string.
Value.Length.ToString() : gets the length of the string and converts it as string

Example

The following example shows a data node defining the cycle time in [min]. The hardware system delivers this value in seconds. Therefore, a conversion is defined:

Reading conversion: Value/60
Writing conversion: Value*60

{
  "Id": "{7EF11D14-E07E-4AAF-9F7A-7B25A0F3D3C9}",
  "Name": "CycleTimeInMin",
  "DataType": "System.Double",
  "Address": "Nc1.CycleTime",
  "Unit": "min",
  "DataClass": "Stream",
  "Access": {
    "Read": true,
    "Receive": true,
    "Write": true,
    "WriteConversion": {
      "Type": "SimpleExpression",
      "Instruction": "Value*60"
    },
    "ReadConversion": {
      "Type": "SimpleExpression",
      "Instruction": "Value/60"
    }
  }
}

Mapping Conversion Expression

Values can be transformed using a mapping expression. The mapping is a simple list of value mappings.

Each mapping must be separated with ;. The wildcard * indicates "any value".

Example

The following example shows how a value of the hardware is mapped by

Value 1 to 55
Value 2 to 66
Any other value to 0

{
  "Id": "{7EF11D14-E07E-4AAF-9F7A-7B25A0F3D3C9}",
  "Name": "OperationMode",
  "DataType": "System.Int32",
  "Address": "Nc1.OperationMode",
  "Unit": "",
  "DataClass": "Event",
  "Access": {
    "Read": true,
    "Receive": true,
    "ReadConversion": {
      "Type": "Mapping",
      "Instruction": "1=55;2=66;*=0"
    }
  }
}

Entity Conversion

Data nodes hosting complex data types must be of type HumanOS.Kernel.DataModel.Entity.TGenericEntity, HumanOS.Kernel.Base or HumanOS.Kernel.DataModel.Entity.TGenericEntity[], HumanOS.Kernel.Base.

There is an implicit conversion between native data like byte[] and the generic entity.

Following properties are supported for this kind of conversion:

Property Name	Description	Data Type
SelectedEntityType	Id of the entity type node declaring the generic entity	`System.Guid`
InvertByteOrder	[OPT] Flag, if the byte order is inverted (coming from controller memory)	`System.Boolean`

Example:

{
  "Id": "1724b330-87e3-4c53-8737-4d0be8a9abb8",
  "Name": "ReadComplexData",
  "Address": "Plc1.DataBlock.ByteArray:2.20[100]",
  "DataType": "HumanOS.Kernel.DataModel.Entity.TGenericEntity, HumanOS.Kernel.Base",
  "Unit": "",
  "Access": {
    "Read": true,
    "ReadConversion": {},
    "Receive": true,
    "WriteConversion": {}
  },
  "Properties": [
    {
      "Name": "InvertByteOrder",
      "DataType": "System.Boolean",
      "Value": "true"
    },
    {
      "Name": "SelectedEntityType",
      "DataType": "System.Guid",
      "Value": "31daf84d-8ff0-464b-9715-8ee7470299fe"
    }
  ]
}

Data Types​

Trigger Types​

DataNode Extension for UHAL Plugins​

Simple Conversion Expressions​

Functions for Numbers​

Functions for Strings​

Mapping Conversion Expression​

Entity Conversion​

Data Types

Trigger Types

DataNode Extension for UHAL Plugins

Simple Conversion Expressions

Functions for Numbers

Functions for Strings

Mapping Conversion Expression

Entity Conversion