[ThingModel] Example of Eclipse Vorto model

[kolotu]

Here is an example of an Eclipse Vorto model that is being used in a real-life application. The device / digital twin that is modelled represents a washer. The model consists of an InformationModel that describes the specific type of the Washer (Bosch WAT286H8SG).

vortolang 1.0

namespace com.bshg
version 2.0.0
displayname "WasherWAT286H8SG"
description "Information model for BSH Washer WAT286H8SG"
category smarthome
using com.bshg.programs.Washer ; 2.0.0
using com.bshg.common.RemoteControlActivationState ; 2.0.0
using com.bshg.common.RemoteStartAllowanceState ; 2.0.0
using com.bshg.common.LocalControlState ; 2.0.0
using com.bshg.common.OperationState ; 2.0.0
using com.bshg.common.DoorState ; 2.0.0
using com.bshg.common.PowerState ; 2.0.0

infomodel WasherWAT286H8SG {

	functionblocks {
		washer as Washer
		remoteControlActivationState as RemoteControlActivationState
		remoteStartAllowanceState as RemoteStartAllowanceState
		localControlState as LocalControlState
		operationState as OperationState
		doorState as DoorState
		powerState as PowerState
	}
}

This InformationModel contains the FunctionBlocks that describe the capabilities of this specific washer. One of those FunctionBlocks is a generic Washer FunctionBlock that describes capabilities of washers in general.

vortolang 1.0

namespace com.bshg.programs
version 2.0.0
displayname "Washer"
description "Function block model for Washer functionality of Home Appliances"
category smarthome
using com.bshg.types.programs.washer.options.Program ; 2.0.0
using com.bshg.types.programs.washer.options.Temperature ; 2.0.0
using com.bshg.types.programs.washer.options.SpinSpeed ; 2.0.0
using com.bshg.types.common.EventPresentState ; 2.0.0

functionblock Washer {
	status {
		mandatory program as Program
		mandatory temperature as Temperature
		mandatory spinSpeed as SpinSpeed
		optional delayedStart as int <MIN 0 , MAX 86340>
		"If this option is set, the program will be activated but not started until the defined time span elapses."

		optional delayedStartUnit as string
	}

	events {
		SelectedProgramChanges {
			mandatory timestamp as long
			mandatory value as Program
			mandatory level as string
			mandatory handling as string
		}

		ActiveProgramChanged {
			mandatory timestamp as long
			mandatory value as Program
			mandatory level as string
			mandatory handling as string
		}

		TemperatureChanged {
			mandatory timestamp as long
			mandatory value as Temperature
			mandatory level as string
			mandatory handling as string
		}

		SpinSpeedChanged {
			mandatory timestamp as long
			mandatory value as SpinSpeed
			mandatory level as string
			mandatory handling as string
		}

		RemainingProgramTimeChanged {
			mandatory timestamp as long
			mandatory value as int <MIN 0 , MAX 86340>
			mandatory level as string
			mandatory handling as string
			mandatory unit as string
		}

		ProgramProgress {
			mandatory timestamp as long
			mandatory value as int <MIN 0 , MAX 100>
			mandatory level as string
			mandatory handling as string
			mandatory unit as string
		}

		ProgramFinished {
			mandatory timestamp as long
			mandatory value as EventPresentState
			mandatory level as string
			mandatory handling as string
		}

	}

	operations {
		startWashing(program as Program,
			temperature as Temperature,
			spinSpeed as SpinSpeed)
	}

}

In general, InformationModels describe specific types of devices / digital twins, while FunctionBlocks are reusable descriptions of capabilities. FunctionBlocks can be used by multiple InformationModels and FunctionBlocks can be extended by other FunctionBlocks to create greater specificity. A FunctionBlock can only extend one other FunctionBlock (no multi-inheritance). When a new FunctionBlock is created that extends an existing FunctionBlock it is not allowed to override any existing property, so naming conflicts cannot occur.

The inheritance feature of Vortolang is very rarely used - and if so mostly for trivial use-cases, that's why the Vorto specification does not cover every edge-case that can occur when using inheritance.

[kolotu]

@kolotu map this model to ThingDescription

[kolotu]

This is the output of the tentative Vortolang -> WoT TM converter. Not all features are implemented yet, this is just to outline, how it will work. I used the Functionblock of the generic Washer for this example: https://vorto.eclipse.org/#/details/com.bshg.programs:Washer:2.0.0

{
  "@context": ["https://www.w3.org/2019/wot/td/v1"],
  "@type" : "ThingModel",
  "title": "com.bshg.programs.Washer:2.0.0",
  "description" : "Function block model for Washer functionality of Home Appliances",
  "properties": {
    "program": {
      "type": "com.bshg.types.programs.washer.options.Program:2.0.0",
      "readOnly": true
    },
    "temperature": {
      "type": "com.bshg.types.programs.washer.options.Temperature:2.0.0",
      "readOnly": true
    },
    "spinSpeed": {
      "type": "com.bshg.types.programs.washer.options.SpinSpeed:2.0.0",
      "readOnly": true
    },
    "delayedStart": {
      "type": "int",
      "readOnly": true
    },
    "delayedStartUnit": {
      "type": "string",
      "readOnly": true
    }
  },
  "events": {
    "SelectedProgramChanges": {
      "data": {"type": "string"}
    },
    "ActiveProgramChanged": {
      "data": {"type": "string"}
    },
    "TemperatureChanged": {
      "data": {"type": "string"}
    },
    "SpinSpeedChanged": {
      "data": {"type": "string"}
    },
    "RemainingProgramTimeChanged": {
      "data": {"type": "string"}
    },
    "ProgramProgress": {
      "data": {"type": "string"}
    },
    "ProgramFinished": {
      "data": {"type": "string"}
    }
  },
  "actions": {
    "startWashing": {
    }
  }
}

[sebastiankb]

type should rely on JSON Schema types like string, integer, object, etc. Thus I would suggest to introduce a context that allows to point to specific data types that relates to Vorto types. In addition, I would use the id term to provide the identifier of the model.

{
  "@context": ["https://www.w3.org/2019/wot/td/v1",
  {"vorto":"https://bshg.com/vorto#"}
   ],
  "@type" : "ThingModel",
  "title": "Washer 2.0",
  "id" : "com.bshg.programs.Washer:2.0.0",
  "description" : "Function block model for Washer functionality of Home Appliances",
  "properties": {
    "program": {
     "type" : "string",
      "vorto:type" : "com.bshg.types.programs.washer.options.Program:2.0.0",
      "readOnly": true
    },
    "temperature": {
      "type": "string",
      "vor:type" : "com.bshg.types.programs.washer.options.Temperature:2.0.0",
      "readOnly": true
    },
    "spinSpeed": {
      "type": "string",
      "vorto:type": "com.bshg.types.programs.washer.options.SpinSpeed:2.0.0",
      "readOnly": true
    },
    "delayedStart": {
      "type": "int",
      "readOnly": true
    },
    "delayedStartUnit": {
      "type": "string",
      "readOnly": true
    }
  },
  "events": {
    "SelectedProgramChanges": {
      "data": {"type": "string"}
    },
    "ActiveProgramChanged": {
      "data": {"type": "string"}
    },
    "TemperatureChanged": {
      "data": {"type": "string"}
    },
    "SpinSpeedChanged": {
      "data": {"type": "string"}
    },
    "RemainingProgramTimeChanged": {
      "data": {"type": "string"}
    },
    "ProgramProgress": {
      "data": {"type": "string"}
    },
    "ProgramFinished": {
      "data": {"type": "string"}
    }
  },
  "actions": {
    "startWashing": {
    }
  }
}

[egekorkan]

However, from what I have understood, the types are not necessarily just string but are more complex, thus they need to be modelled in JSON Schema in order to represent them for other TD Consumers.

[sebastiankb]

In that case the properties are string values with a sections as enum as shown here

https://vorto.eclipse.org/#/details/com.bshg.types.programs.washer.options:Program:2.0.0

Providing JSON Schema would be alternative.

[egekorkan]

This was just an input right? Not really an issue. I would propose closing it