Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
886 lines (742 sloc) 21.1 KB

Vorto Language for Digital Twins

Version 1.0

Contents

Information Model
Function Block
Properties
Event
Operation
Primitive Types
Enum
Dictionary
Entity
Model Property

Introduction

This document specifies the Vorto Language (vortolang 1.0), a language for describing models and interfaces for IoT Digital Twins. Digital twins are models of entities in the physical world such as a (multi) sensor device, smart power plant, and other entities that participate in IoT solutions. Modeling enables IoT solutions and IoT platforms to provision, use, and configure IoT devices and logical entities from multiple sources in a single solution. Using the vortolang and describing the entities's capabilities, IoT platforms and IoT solutions can leverage the semantics of these IoT entities.

Digital Twin Vorto Language

Digital twins are described using the vortolang, which is domain-specific language (DSL). This DSL underlies a very simple grammar, making it very easy to describe digital twin models. In order to be used in IoT Platforms and solutions, the vortolang can easily be converted into well adopted languages, such as JSON-LD, where additional context-specific attributes can be added. Many (free) libraries are available to process these language files. At definition time, developers can use the vortolang without any knowledge about JSON-LD or others, and fully focus on describing the device capabilities in a very expressive way.

The vortolang is made up of a set of metamodel classes (described later in more detail) that define the capabilities of digital twins. There are two top-level classes, Information Model and Function Block, that describe a digital twin and the capabilities of digital twins, respectively. There are three metamodel classes that describe capabilities: Properties, Events, and Operations. When writing a digital twin definition, it's necessary to specify the version of the vortolang being used (currently 1.0)

Information Models and Function Blocks

There are two top-level metamodel classes: Information Model and Function Block. Information Models describe a complete digital twin, such as a physical device. Often, Information Models are associated with a specific device product, such as a "Bosch Dinion IP Starlight 8000MP" security camera, while Function Blocks describe the related capabilities of an digital twin (its status- and configuration properties, events, and operations). Function Blocks can be reused across different Information Models. Information Models are often made up of multiple Function Blocks (interfaces).

Information Model

An Information Model describes a complete digital twin, such as a physical device and defines the set of interfaces as Function Blocks, implemented by the digital twin.

Information Model properties

Keyword Required Data type Description
vortolang required string Identifies which vortolang version used to define the Information Model. Currently '1.0'
namespace required string The name must match the regular expression: name('.' name )*
version required string The name must match the regular expression: /^\d+\.\d+\.\d+(-\\w+)*$/
displayname optional string a name of the information model for human display
description optional string A description for human display.
category optional string Custom tag to categorize the model, e.g. sensor, smarthome/kitchen etc.
The name must match the regular expression: name('/' name )*
using required A set of Model References Defines the imported models that are referenced by this Information Model under 'functionblocks'
infomodel required string The name must match the regular expression: ^[A-Z][a-zA-Z0-9]*$
functionblocks required A set of Model Property of type Function Block A set of Function Block properties.

BNF (Backus normal form)

InformationModel:
    'vortolang' 1.0

    'namespace' qualifiedName
    'version' version
    ('displayname' string)?
    ('description' string)?
    ('category' ID('/' ID)*)?

    (modelReference)*

    'infomodel' ID '{'
    'functionblocks' '{'
        (functionblockProperty)*
    '}'
;

functionblockProperty: 
	('mandatory' | 'optional')? ('multiple')? ID 'as' [FunctionBlock::ID | qualifiedName] (description)?

qualifiedName: ID ('.' ID)*;

version : int('.' int)*('-'ID)?;

ID:
    '^'?('a'..'z'|'A'..'Z'|'_') ('a'..'z'|'A'..'Z'|'_'|'0'..'9')*
;

description: STRING

modelReference: 
	'using' qualifiedName ';' version;

Example:

vortolang 1.0

namespace com.mycompany
version 1.0.0
description "Information model for FabLab.eu's IoT Octopus"
category multisensor

using com.ipso.smartobjects.Accelerometer ; 1.1.0
using com.ipso.smartobjects.Barometer ; 1.1.0

infomodel IoTOctopus {

	functionblocks {
		mandatory accelerometer as Accelerometer "some description"
		optional barometer as Barometer
	}
}

Function Block

A Function Block describes related capabilities that are implemented by a digital twin. Function Blocks are reusable and can be reused across different Information Models.

Function Block properties

Keyword Required Data type Description
vortolang required string Identifies which vortolang version used to define the Function Block. Currently '1.0'
namespace required string The name must match the regular expression: name('.' name )*
version required string The name must match the regular expression: /^\d+\.\d+\.\d+(-\\w+)*$/
displayname optional string a name of the information model for human display
description optional string A description for human display.
category optional string Custom tag to categorize the model, e.g. sensor, smarthome/kitchen etc.
The name must match the regular expression: name('/' name )*
using required A set of Model References Defines the imported models that are referenced by this Information Model under 'functionblocks'
functionblock required string The name must match the regular expression: ^[A-Z][a-zA-Z0-9]*$
extends optional ID of a Function Block Extends another Function Block by specializing it with extended properties
configuration optional Configuration Properties An object describing configuration Properties. Configuration properties are read-writable by default.
status optional Status Properties An object describing status Properties. Status properties are read-only by default.
events optional a set of Events Describes data emitted by a device or other entity
operations optional a set of Operations Describes functions that can be performed on the device or entity.

BNF (Backus normal form)

FunctionBlock:
    'vortolang' 1.0

    'namespace' qualifiedName
    'version' version
    ('displayname' string)?
    ('description' string)?
    ('category' ID('/' ID)*)?

    (modelReference)*

   'functionblock' ID ('extends' [Functionblock::ID | qualifiedName])? '{'
		('configuration' '{' 
			(Property)*
		'}')?
		
		('status' '{' 
			(Property)*
		'}')?

		('events' '{' 
			(ID '{'
				(Property)*
			'}')*
		'}')?
		
		('operations' '{'
			(Operation)*
		'}')?	
		
	'}'	
;

qualifiedName: ID ('.' ID)*;
version : int('.' int)*('-'ID)?;
ID: '^'?('a'..'z'|'A'..'Z'|'_') ('a'..'z'|'A'..'Z'|'_'|'0'..'9')*;
modelReference: 'using' qualifiedName ';' version;
description: STRING

Property: Please refer to chapter Model Property for details

Operation:
 ('extension')? ('mandatory' | 'optional')? ('breakable')? ID '(' (OperationType (',' OperationType)*)?')' ('returns' OperationType)? (description)?;

OperationType: DictonaryOperationType | OperationPrimitiveType | OperationObjectType;

DictonaryOperationType:
('multiple')? ID 'as' DictionaryType ('<' ConstraintRule '>')?  (description)?;

OperationPrimitiveType: ('multiple')? ID 'as' PrimitiveType ('<' ConstraintRule '>')?  (description)?;

OperationObjectType: ('multiple')? ID 'as' ObjectType (description)?;

Example:

vortolang 1.0

namespace com.mycompany
version 1.0.0

functionblock Accelerometer {

	configuration {
		mandatory enable as boolean
	}

	status {
		mandatory xValue as float "The measured value along the X axis."
		optional yValue as float "The measured value along the Y axis."
		optional zValue as float "The measured value along the Z axis."
	}
	
	operations {
		reset() returns boolean "resets the accelerometer"
	}
}

Properties

Properties describe both read-only and read-write state of a digital twin. Read-only properties are defined as status properties, whereas read-write properties as configuration properties. For example, a device serial number may be a status property and the temperature set point on a thermostat may be a configuration property.

Function Block property is defined as a Model Property

Status Property Example

functionblock Thermostat {
...
	status {
		mandatory serialNumber as string
	}
}

Configuration Property Example

functionblock Thermostat {
...

	configuration {
		optional temperature as float <MIN 0, MAX 35> "writable temperature with a range constraint"
		mandatory enable as boolean "enables the sensor to start sending data"
	}
}

Event

Events define data that is emitted by the device or entity. This kind of data would need to be transmitted to an IoT business solution in a reliable way.

An Event property is defined as a Model Property

Event Example

functionblock Geolocation {
...
	events {
		enterFence {
			entryPoint as Location3D
			timestamp as dateTime		
		}
		leaveFence {
			exitPoint as Location3D
			timestamp as dateTime	
		}
	}
}	

Operation

An operation represents a function that can be performed on a Digital Twin. Operations may have request params as well as a return type

Keyword Required Description
breakable Optional Signals, that it could eventually cause an error when performing the operation on the device
operation name required Name of the operation
request params optional request params, separated by ,
response type optional Specifies a response of the operation. Response type must comply to Data Type
description optional A description for human display

Example

op() "A simple operation without request and response types"

breakable op() "An operation that could cause an error when performed"

op() returns int "Operation that returns a primitive type"

op() returns multiple int "Operation that returns an array of a primitive type"

op(msg as string) "Operation with a single primitive param"

op(multiple msg as string "msg description") "array param with description"

op(msg as int <MIN 0, MAX 100>) "Param with constraint"

Data Types

Primitive Types

A full set of primitive data types are provided and can be specified directly as a type value of a model property.

Primitive Schema Description
boolean a boolean value
dateTime A date and time in ISO 8601 format
double An IEEE 8-byte floating point number
float An IEEE 4-byte floating point number
int A signed 4-byte integer
long A signed 8-byte integer
string A UTF8 string
base64Binary Represents an arbitrary binary content
base64Binary Represents an arbitrary binary content
short A short 16-bit integer between -32768 and 32767
byte A 8-bit integer between -128 and 127

Enum

An enum is an enumeration of values of the same type similar to an enum in Java.

Keyword Required Data type Description
vortolang required string Identifies which vortolang version used to define the Enumeration. Currently '1.0'
namespace required string The name must match the regular expression: name('.' name )*
version required string The name must match the regular expression: /^\d+\.\d+\.\d+(-\\w+)*$/
displayname optional string a name of the enumeration model for human display
description optional string A description for human display.
category optional string Custom tag to categorize the model, e.g. sensor, smarthome/kitchen etc.
The name must match the regular expression: name('/' name )*
literal required a set of literal values Multiple literal values are separated by , It must match the regular expression: ('a'..'z'|'A'..'Z'|'_'|'0'..'9')*
literal description optional string A description for human display.

BNF (Backus normal form)

Enumeration:
    'vortolang' 1.0

    'namespace' qualifiedName
    'version' version
    ('displayname' string)?
    ('description' string)?
    ('category' ID('/' ID)*)?

   'enum' ID '{'
		(enumLiteral) (',' enumLiteral)*
	'}'	
;

qualifiedName: ID ('.' ID)*;
version : int('.' int)*('-'ID)?;
ID: '^'?('a'..'z'|'A'..'Z'|'_') ('a'..'z'|'A'..'Z'|'_'|'0'..'9')*;
description: STRING

 enumLiteral: ID (description)?

Example

vortolang 1.0

namespace com.mycompany
version 1.0.0

enum Unit {
	kg "Kilogram unit" , 
	g "gram unit"
}	

Entity

Keyword Required Data type Description
vortolang required string Identifies which vortolang version used to define the Enumeration. Currently '1.0'
namespace required string The name must match the regular expression: name('.' name )*
version required string The name must match the regular expression: /^\d+\.\d+\.\d+(-\\w+)*$/
displayname optional string a name of the enumeration model for human display
description optional string A description for human display.
category optional string Custom tag to categorize the model, e.g. sensor, smarthome/kitchen etc.
The name must match the regular expression: name('/' name )*
using required A set of Model References Defines the imported models that are referenced by this Entity
extends optional Entity name Expresses inheritance of entities
properties optional A set of Model Property elements A set of Model Property elements

BNF (Backus normal form)

Entity:
    'vortolang' 1.0

    'namespace' qualifiedName
    'version' version
    ('displayname' string)?
    ('description' string)?
    ('category' ID('/' ID)*)?

    (modelReference)*

   'entity' ID ('extends' [Entity::ID | qualifiedName])? '{'
		(property)*			
	'}'	
;

qualifiedName: ID ('.' ID)*;
version : int('.' int)*('-'ID)?;
ID: '^'?('a'..'z'|'A'..'Z'|'_') ('a'..'z'|'A'..'Z'|'_'|'0'..'9')*;
modelReference: 'using' qualifiedName ';' version;
description: STRING

Property: Please refer to chapter Model Property for details

Example

vortolang 1.0

namespace com.mycompany
version 1.0.0

entity Color {  
	mandatory red as int <MIN 0, MAX 255> "The red component of a color"  
    mandatory green as int <MIN 0, MAX 255> "The green component of a color"    
    mandatory blue as int <MIN 0, MAX 255> "The blue component of a color"  
}

Dictionary

A dictionary describes values in a map.

Example

mandatory lookupTable as dictionary[string, Color] "Lookup table conversion for color"

mandatory lookupRGBTable as dictionary[Color, RGB] "Lookup table conversion for color from description to RGB"

mandatory temperatureLabelConversion as dictionary[int, string] "map of temperature to description"

mandatory simpleMap as dictionary "example of a map with no key and value types"

Model Property

A model property can be used by events, function block properties or entities.

Keyword Required Description
extension optional Indicates that the property is extended from a supertype with additional meta data
mandatory or optional optional Whether the property is mandatory or optional. Default is optional.
multiple optional Indicates if the property is an array type
with optional additional meta - data about the property, such as measurementUnit or if the property is readable or writable

BNF (Backus normal form)

Property:
		('extension')? ('mandatory] | 'optional')? ('multiple')? ID 'as' PropertyType
		('with' '{' PropertyAttribute (',' PropertyAttribute)* '}')?
		('<' ConstraintRule '>')?
		(description=STRING)?
	;

	PropertyType: ObjectType | PrimitiveType | DictionaryType;

	ObjectType: [Type::ID | qualifiedName];
	
	PrimitiveType: 
		'string' | 'int' | 'float' | 'boolean' | 'dateTime' | 'double' | 'long' | 'short' |'base64Binary' | 'byte';
	
	DictionaryType: 'dictionary' ('['PropertyType ',' PropertyType ']')?
	
	PropertyAttribute: BooleanPropertyAttribute | EnumLiteralPropertyAttribute;

	BooleanPropertyAttribute: ('readable' | 'writable') ':' ('true' | 'false');
	
	EnumLiteralPropertyAttribute: 'measurementUnit' ':' [Enum::ID | QualifiedName];

	Constraint: ('MIN' | 'MAX' | 'STRLEN' | 'REGEX' | 'MIMETYPE' | 'SCALING' | 'DEFAULT' | 'NULLABLE') IntervalType;

	IntervalType: INT | SIGNEDINT | FLOAT | DATETIME | STRING | BOOLEAN;

Further links

You can’t perform that action at this time.