Function Block Model DSL Reference

This section details the following topics:

Function Block DSL Syntax

Function Block DSL Semantics

Function Block DSL Syntax

The following code represents the Function Block Model DSL syntax. Function block model use all variables that are defined in Data Type DSL.

functionblockmodel:
    'namespace' qualifiedName
    'version' version
    'displayname' displayname
    ('description' description)?
    'category' category
    (modelReference)*
    'functionblock' id ('extends' functionblockmodel)? '{'
        functionblock
    '}'
;

functionblock:
    'configuration' '{' 
        (property)*  
    '}'

    ('status' '{'
        (property)*
    '}')?

    ('fault' '{'
        (property)*
    '}')?

    ('events' '{'
        (event)*
    '}')?

    ('operations' '{'
        (operation)*
    '}')?
;

operation :
    ('breakable')? id '(' (param (paramDescription)?)? ')' ('returns'  returnType)? (returnTypeDescription)?
;

returnType :
    returnObjectType | returnPrimitiveType
;

returnObjectType :
    ('multiple')? [datatype::type | qualifiedName]
;

returnPrimitiveType :
    ('multiple')? primitiveType ('<'constraintType [constraintIntervalType] ("," constraintType [constraintIntervalType])*'>')?
;

primitiveParam:
    (multiple')? id 'as' primitiveType ('<'constraintType [constraintIntervalType] ("," constraintType [constraintIntervalType])*'>')?
;

refParam:
    ('multiple')? id 'as' [datatype::type|qualifiedName]
;

param:
    primitiveParam | refParam
;

event:
    id '{'
        (property)*
    '}'
;

string:
    '"' ( '\\' ('b'|'t'|'n'|'f'|'r'|'u'|'"'|"'"|'\\') | !('\\'|'"') )* '"' |
    "'" ( '\\' ('b'|'t'|'n'|'f'|'r'|'u'|'"'|"'"|'\\') | !('\\'|"'") )* "'"
;

qualifiedName: id ('.' id)*;

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

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

Function Block DSL Semantics

This section details the following topics:

Function Block Model

Function Block

Property

Operation

Event

Entity

Enum

Function Block Model

A function block model describes a function block with its properties and behavior. For this it can contain a functionblock element (refer to Function Block) and no or several entity elements (refer to Entity).

Syntax

Refer to functionblockmodel in Function Block DSL Syntax.

Example

namespace com.mycompany.fb
version 1.0.0
functionblock Lamp {  
  displayname "Lamp"  
  description "A lamp makes the environment bright"  
  category demo  
  configuration{  
    mandatory blinking as boolean "if the lamp is currently blinking or not"  
    mandatory on as boolean "if the lamp is currently switched on"  
    mandatory powerConsumption as int
      "the amount of power the lamp is consuming"  
  }  
  fault{  
  mandatory bulbDefect as boolean
    "true if the light bulb of the lamp is defect"  
  }  
  operations{  
    blink(blinkType as int <MIN 0, MAX 5> "The type of blink") "sets the blinking type for the lamp"  
    getPowerConsumption() returns int <MIN 0, MAX 5> "gets the amount of power being consumed by the lamp"  
    isOn() returns boolean "checks if the lamp is switched on"  
    breakable off() "turns the lamp off"  
    breakable on() "turns the lamp on"  
    stopBlinking() "stops the blinking of the lamp"  
    toggle() "switches the lamp on or off"  
    toggleWithDelay(delayInSeconds as int)
      "switches the lamp on or off with a delay of the specified seconds"  
    }  
  }  

Function Block

A functionblock element describes the properties and behavior of a function block. A functionblock element contains

  • General metadata parameters (displayname, description, vendor, category, version).
  • Property elements (configuration, status, fault).
  • An operations element.

Syntax

Refer to FunctionBlock in Function Block DSL Syntax.

Usage

The following table describes the parameters and elements of a functionblock. Mandatory parameters or elements are marked with Y in the column Mandatory

Parameter/Element Mandatory Description Type Examples
displayname A descriptive and user friendly name of the function block. String enclosed in quotation marks displayname "Vending Machine"
description Extra information about the function block. String enclosed in quotation marks description "A vending machine withdraws food or drinks"
category Y The category should be used to logically group function blocks that semantically belong to the same domain. top level category (mandatory) and a sub category (optional), separated by aslash (/) IAP/smarthome</br>indego
configuration Y Contains one or many configuration properties for the function block. complex type containing properties (see grammar for Property) ...</br>configuration {</br>  // properties</br>}
status Contains one or many status properties for the function block. complex type (see grammar for Property) ...</br>status {</br>  // properties</br>}
fault Contains one or many fault properties for the function block. complex type (see grammar for Property) ...</br>fault {</br>  // properties</br>}
operations Contains one or many operations for the function block. complex type (see grammar for Operation) ...</br>operations {</br>  // operations</br>}
events Contains one or many events for the function block. complex type (see grammar for Event) ...</br>events {</br>  // events go here</br>}

Example

namespace com.mycompany.fb
version 1.0.0
functionblock Lamp {  
  displayname "Lamp"
  description "A lamp makes the environment bright"
  category demo
  configuration{
    mandatory blinking as boolean "if the lamp is currently blinking or not"
    mandatory on as boolean "if the lamp is currently switched on"
    mandatory powerConsumption as int
      "the amount of power the lamp is consuming"
  }

  fault{
    mandatory bulbDefect as boolean
      "true if the light bulb of the lamp is defect"
  }
  events{
    defect{
      mandatory on as boolean "if on is true"
      mandatory powerConsumption as int "if powerConsumption is 0"
    }

  }
  operations{
    blink(blinkType as int <MIN 0, MAX 5> "The type of blink") "sets the blinking type for the lamp"
    getPowerConsumption() returns int <MIN 1, MAX 3000>
      "gets the amount of power being consumed by the lamp"
    isOn() returns boolean "checks if the lamp is switched on"
    breakable off() "turns the lamp off"
    breakable on() "turns the lamp on"
    stopBlinking() "stops the blinking of the lamp"
    toggle() "switches the lamp on or off"
    toggleWithDelay(delayInSeconds as int)
      "switches the lamp on or off with a delay of the specified seconds"
    }
}

Property

Syntax

Refer to property in Function Block DSL Syntax.

Usage

The following table describes the property elements. Mandatory property elements are marked with Y in the column Mandatory

Property element Mandatory Description Type
optional | mandatory Y Declares if the property is optional or mandatory.
multiple Defines if the property can have more than one value.
<property_name> Y A descriptive name of the property. String (identifier, without spaces)
as <type> Y The data type of the property. Supported types:</br>
  • boolean
  • dateTime
  • float
  • int
  • string
  • long
  • short
  • double
  • base64Binary
  • byte
  • Dictionary (with optional key and value types)
  • Another Entity
  • Another Enum
with { [propertyAttribute] } N Additional property attributes Supported property attributes:</br>
  • measurementUnit : an Enum literal
  • readable: [true or false]
  • writable: [true or false]
  • eventable: [true or false]
<constraints> Key value pair(s) enclosed by <>, following the pattern:</br><CONSTRAINT_KEYWORD value> <STRLEN value>, defining the length of a string</br> <MIN value>, defining the maximum of a numeric property</br> <MAX value>, defining the minimum of a numeric property</br> <REGEX value>, defining the regular expression pattern of the property</br> <REGEX value>, defining the regular expression pattern of the string property. Value format expected should be of XML schema pattern format, e.g: [A-Z], [0-9], ([a-z][A-Z])+
<description> Extra information about the property. String enclosed in quotation marks

Examples

optional multiple products as Product
  "the products that are offered by the vending machine"

optional vendingMachineIdentifier as string <STRLEN 8>
  "the id of the vending machine"

mandatory engineTemperature as float 
  with { measurementUnit: Temperature.Celsius, readable: true, writable: true }

mandatory positiveNum as int <MIN 0 , MAX 1111>
  "Positive numbers that is within [0 , 1111]"

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 noKeyAndValueTypeMap as Dictionary "example of a map with no key and value types"

mandatory biggerThanInt as long <MAX 999999999999999999>
  "Value for constraint is validated according to the property type,
  in this case, Long instead of Int"

mandatory deviceName as string <REGEX '[a-zA-Z][a-zA-Z][0-9]'>
  "Only allow 2 uppercase or lowercase characters and 1 digit for
  device name"

Operation

An operation can be seen as a function the function block can perform. Function block operations support the one-way as well as request-response operation pattern and are composed inside the operations element of a functionblock.

Syntax

Refer to operation in Function Block DSL Syntax.

Usage

The following table shows the operation types.

Operation type Examples
Without parameter(s)
  • resetConfiguration()
  • switchOn()
With parameter(s)
  • setTemperature(temperature as int)
  • setProductConfigurationList(multiple products as Product)
With return type
  • getProductIdsList() returns multiple string
  • getProductConfiguration() returns Product
With parameter(s) and return type
  • withdraw(productId as string, amount as int) returns boolean

All operations may have a <description> at the end of each parameter declaration and the operations definition.

Example

getProductConfigurationList() returns multiple Product
  "Gets the current configured products from the vending machine"
getProductConfigurationList(count as int "Number of products to return", offset as int "What row to start") 
  returns multiple Product "Gets the current configured products from the vending machine"

The parameters and return type can also have constraints.

Example

setRedComponent(R as int <MIN 0, MAX 255>)
getRedComponent() returns int <MIN 0, MAX 255>

Event

An event can be seen as a combination of zero or more properties. The events element of a functionblock can contain 0 or many event elements.

Syntax

Refer to event in Function Block DSL Syntax.

Usage

Refer to Usage in Property.

Example

...  
  events {  
    ready {  
      optional since as dateTime  
    }  
  }  
...