With the Building Block Feature we can model Building Blocks and their decomposition structure and define their variability types. Such Building Blocks can represent specific implementations or task requirements.

Building Block models are closely connected with DVG models because before it is possible to specify how variability of Building Blocks relate, they need to be defined first. Hence, the Building Block models describe what variabilities exist and the DVG models describe how these relate.

A Building Block model is the trigger for the code generator to create the variability solver. It requires that a DVG model is referenced:

BuildingBlockDescription <DesiredName> dvg <DesiredDVGModel> {
  ...
}

Each time you save the textual model after changes, the code generator will be triggered. If you want to trigger the code generator without model changes, just add a whitespace somewhere in the textual model and press save.

Go to the src-gen folder of this Building Block model where you can find the generated java file. Compile and execute it.

We can use the feature to create the model of a specific Building Block implementation, for example the behavior of a specific robot task like Order Picking or Serve Coffee, a skill like Navigation or a component like CDL. Such Building Blocks are assumed to be executed by a predetermined single robot resource which means that there is no independence between a task description requirement and the provided capabilities of potential resources. Due to this predetermination, decisions with respect to the resolution of variability is only based on non-functional requirements.

Such a model must start as following:

BuildingBlockDescription <DesiredName> {
  BuildingBlock <DesiredName> {
    ...
  }
  ...
}

A simple Building Block example at a task level where a service robot must collect a box from a specific station and deliver it to another station. The associated DVG model is explained here and the complete project can be found here

BuildingBlockDescription Transportation dvg Transportation { 

We define a new BuildingBlockDescription that is named Transportation and we link a DVG model named Transportation that describes how the variability entities defined in the following building block model relate. The example of this DVG model can be found in Transportation Example (DVG)

  BuildingBlock Transportation {      
      VariabilityEntitySet {
          PropertySet { 
              Time is UdoTime
          }
      }
      Decomposition (Seq_Transportation) 
  }

We define a new Building Block that is named Transportation and which defines Time as a Property instance. After the is must follow the Data Object. In this case we reference UdoTime which is defined in a DataObjectRepo in a different project. Finally, we define that Transportation is a Sequential Decomposition named Seq_Transportation.

  Sequential Seq_Transportation {
      Container C1 => CollectBox,
      Container C2 => DeliverBox
  }
  BuildingBlock CollectBox {
          VariabilityEntitySet {
          PropertySet { 
              Time is UdoTime
          }
      }
      Decomposition(Seq_CollectBox)      	
  }
  BuildingBlock DeliverBox {
          VariabilityEntitySet {
          PropertySet { 
              Time is UdoTime
          }
      }
      Decomposition(Seq_DeliverBox)      	
  }   

Seq_Transportation is a sequence of the Containers C1 and C2 which reference the definitions of the Building Blocks CollectBox and DeliverBox. Both definitions model the Property instance Time. CollectBox then decomposes sequentially to Seq_CollectBox and DeliverBox decomposes sequentially to Seq_DeliverBox.

  Sequential Seq_CollectBox {
      Container C1 { 
          BuildingBlock GotoLocation { 
              Inputs { 
                  Mandatory M1 GoalPosition is UdoLocation2D 
              }
              VariabilityEntitySet {
                  ParameterSet {
                      Velocity is UdoTranslationalVelocity
                  }
                  PropertySet {
                      Time is UdoTime 
                  }
                  ContextSet {
                      CurrentPosition is UdoLocation2D
                  }
              }
          }
      },
      Container C2 { 
          BuildingBlock DockToStation {
              VariabilityEntitySet {
                  PropertySet { 
                      Time is UdoTime
                  }
              }
          }
      },
      Container C3 {
          BuildingBlock LoadFromStation {
              VariabilityEntitySet {
                  PropertySet { 
                      Time is UdoTime
                  }
              }               
          }
      },
      Container C4 {
          BuildingBlock UndockFromStation {
              VariabilityEntitySet {
                  PropertySet { 
                      Time is UdoTime
                  }
              }                       
          }
      }       
  }

Seq_CollectBox is a sequence of the four Containers C1, C2, C3 and C4 that contain the Building Blocks GotoLocation, DockToStation, LoadFromStation and UndockFromStation. All Building Blocks have the Property instance Time. In addition, GotoLocation defines the following variabilities:

• A Mandatory Input GoalPosition which references a UdoLocation2D Data Object.
• A Parameter instance Velocity which references a UdoTranslationalVelocity Data Object.
• A Context instance CurrentPosition which references a UdoLocation2D Data Object.

  Sequential Seq_DeliverBox { 
      Container C1 => "Seq_CollectBox.C1.GotoLocation",
      Container C2 => "Seq_CollectBox.C2.DockToStation",
      Container C3 {
          BuildingBlock UnloadToStation {
              VariabilityEntitySet {
                  PropertySet {
                      Time is UdoTime
                  }
              }     
          }
      },
      Container C4 => "Seq_CollectBox.C4.UndockFromStation"
  }

Seq_DeliverBox is a sequence of the four Containers C1, C2, C3 and C4 that contain the Building Blocks GotoLocation, DockToStation, UnloadToStation and UndockFromStation. Since, GotoLocation, DockToStation and UndockFromStation are already defined in Seq_CollectBox we just reference them from there. The new Building Block UnloadToStation is defined here and also defines the Property instance Time.

}

UnboundedDataObjectDef UdoTime {
  ElementDef Time is Real
}
UnboundedDataObjectDef UdoLocation2D {
  ElementDef x is Real,
  ElementDef y is Real
}
UnboundedDataObjectDef UdoTranslationalVelocity {
  ElementDef TranslationalVelocity is Real
}    

We can also use the feature to create the model of a task requirement that is independent of a concrete implementation by a specific robot resource. Hence, in contrast to Describing a Specific Implementation (Single Fixed Robot), there is an additional type of variability associated with such model types which is the set of available robot resources and it must be checked which robots of this set are able to deal with the required task. After this capable set of robot resources is determined, their non-functional properties are analyzed.

Such a model must start as following:

BuildingBlockDescription <DesiredName> {
  ALLOCATABLE BuildingBlock <DesiredName> {
    allocationCandidates (robotModel_1, robotModel_2, ..., robotModel_n)
    ...
  }
  ...
}

So it is important that the first BuildingBlock directly after a BuildingBlockDescription is of block type ALLOCATABLE in order to classify this model as a task requirement description. Furthermore you need to specify the list of allocation candidates, so the list of robot models that wants to be checked against this task requirement description. The required references for these models are the names of the corresponding BuildingBlockDescriptions.

Besides ALLOCATABLE there are the following additional block types:

• IDENTIFYING
• SUPER_IDENTIFYING
• COMPOSED

All following BuildingBlock elements in such a model must be characterized by one of these three block types. Note that these characterizations are only required here and not in Describing a Specific Implementation (Single Fixed Robot) because they impact the building block matching algorithm that determines if a robot resource is capable to execute the required task description and which is only required here. If the type is not specified, it will be treated as IDENTIFYING. The matching algorithm checks if all the required BuildingBlocks of this task description are provided by the specified allocationCandidates. The identifier of each BuildingBlock is its name. The block types impact which names are added to the set of BuildingBlock identifiers for which will be checked if the allocationCandidates provide them as following:

<IDENTIFYING|SUPER_IDENTIFYING|COMPOSED> BuildingBlock <Name> {
  ...
  Decomposition(child-BuildingBlock_1, child-BuildingBlock_2, ..., child-BuildingBlock_n)
}

• IDENTIFYING: <Name> is added to the set of BuildingBlock identifiers to check. The child-BuildingBlocks of <Name> will be considered.
• SUPER_IDENTIFYING: <Name> is added to the set of BuildingBlock identifiers to check. The child-BuildingBlocks of <Name> will be not considered.
• COMPOSED: <Name> is not added to the set of BuildingBlock identifiers to check. The child-BuildingBlocks of <Name> will be considered.

ALLOCATABLE BuildingBlock <BName1> {
  sharedresources 3
  Decomposition (<DName1>)	
}

In an ALLOCATABLE BuildingBlock you can specify its number of shared resources. This means that the child-BuildingBlocks can not be executed by a single allocationCandidate but must be shared between at least two allocationCandidates. In the example above, we defined three sharedresources.

Sequential <DName1> {
  Container <CName1> [0] { IDENTIFYING BuildingBlock <BName2> { Decomposition (<DName2>) } },
  Container <CName2> [1] => "<BName3>",
  Container <CName3> [2] => "<BName4",
  Container <CName4> [0] => "<BName5>"
} 

Because the parent Building Block specified three sharedresources we must assign the child-Containers a resourcegroupid to cluster the defined or referenced BuildingBlocks that must be executed by the same allocationCandidate. In the example above, <BName2> and <BName5> belong together because their Containers have assigned the same resourcegroupid [0]. That means, they must be assigned to the same allocationCandidate but to a different allocationCandidate than <BName3> and <BName4> because their Containers have different resourcegroupids assigned. Child-Containers will automatically derive the resourcegroupid from its parents. In the example above, the Child-Containers of <DName2> get the resourcegroupid [0] from its parent <CName1> assigned.

An order picking task that must be shared between two different robots (one for transportation, one for manipulation). The complete project can be found here

BuildingBlockDescription AllocSharedOrderPicking dvg AllocSharedOrderPicking {

The corresponding DVG model can be found here.

  ALLOCATABLE BuildingBlock AllocSharedOrderPicking {              
	  Inputs { 
		  Mandatory M1 NumberObjects is UdoSimpleInteger         
	  }
	  allocationCandidates (Robotino, Larry, Macy, Robotino_2)   
	  VariabilityEntitySet {   
		  PropertySet {   
			  Time is UdoTime    
		  }
	  }
	  sharedresources 2
	  Decomposition(Pa_SharedOrderPicking, Seq_Collaboration) 
  }

Four allocationCandidates are specified for this ALLOCATABLE BuildingBlock (Robotino, Larry, Macy, Robotino_2). The number of sharedresources is two, i.e. two distinct allocationCandidates are needed to solve this task description. Finally, it defines a Sequential Decomposition of Pa_SharedOrderPicking and Seq_Collaboration.

  Parallel Pa_SharedOrderPicking {        
	  policy WAITFORALL
	  Container C1 [0] => "BBRepo.CollectBox",    
	  Container C2 [1] { 
		  COMPOSED BuildingBlock ApproachAndDetect {
			  VariabilityEntitySet { 
				  PropertySet { 
					  Time is UdoTime  
				  }
			  }
			  Decomposition(Seq_ApproachAndDetect)
		  }
	  } 
  }
  Sequential Seq_ApproachAndDetect {
	  Container C1 => "BBRepo.GotoLocation", 
	  Container C2 { 
		  BuildingBlock DetectObjects { 
			  VariabilityEntitySet { 
				  PropertySet { 
					  Time is UdoTime
				  }
			  }
		  }
	  }
  }

Pa_SharedOrderPicking is a Parallel Decomposition. The policy WAITFORALL means that all following BuildingBlocks must finish to proceed. The first Container C1 refers to CollectBox which we already know from the previous example. We assume that this building block is defined in a different model/project so that it can be easily reused. In such cases you can define the resourcegroupid within the Container that specifies the BuildingBlock reference. Container C2 defines the BuildingBlock that must be executed in parallel to C1 and is named ApproachAndDetect. This BuildingBlock is of type COMPOSED, because it decomposes to a simple Sequential composition of GotoLocation and DetectObjects. Because of this composition, the name ApproachAndDetect is meaningless and is therefore not added to the set of BuildingBlock identifiers for which will be checked if the allocationCandidates provide them (see Block Types Impacting the Matching Algorithm). Due to the parallel execution, it is clear that different resources (allocationCandidates) must be assigned to the building blocks. Therefore, CollectBox gets resourcegroupid 0 and ApproachAndDetect gets resourcegroupid 1.

  Sequential Seq_Collaboration {
	  Container C1 [0] => "BBRepo.GotoLocation",
	  Container C2 [0] { 
		  IDENTIFYING BuildingBlock DockToRobot { 
			  VariabilityEntitySet { 
				  PropertySet { 
					  Time is UdoTime
				  }
			  } 
		  }
	  }, 
	  Container C3 [1] { 
		  IDENTIFYING BuildingBlock PickAndPlace { 
			  VariabilityEntitySet { 
				  PropertySet { 
					  Time is UdoTime
				  }
			  } 
		  }
	  },
	  Container C4 [0] => "BBRepo.GotoLocation"
  }

The sequence is GotoLocation (resourcegroupid [0]), DockToRobot (resourcegroupid [0]), PickAndPlace (resourcegroupid [1]) and GotoLocation (resourcegroupid [0]).

}

The corresponding DVG model is explained here and the complete project can be found here.

BuildingBlockDescription Robotino dvg Robotino {  
  BuildingBlock CollectBox {}  
  BuildingBlock DockToRobot {}
  BuildingBlock DeliverBox {}
  Container GotoLocation => "BBRepo.GotoLocation" 
}

The corresponding DVG model is explained here and the complete project can be found here.

BuildingBlockDescription Larry dvg Larry {    
  BuildingBlock DetectObjects { } 
  BuildingBlock PickAndPlace { }
  Container GotoLocation => "BBRepo.GotoLocation" 
}

The corresponding DVG model is explained here and the complete project can be found here.

BuildingBlockDescription Macy dvg Macy {        
  BuildingBlock CollectBox { }
  BuildingBlock DockToRobot { }
  BuildingBlock DeliverBox { } 
  BuildingBlock DetectObjects { }
  BuildingBlock PickAndPlace { }
  Container GotoLocation => "BBRepo.GotoLocation"
}

The corresponding DVG model is explained here and the complete project can be found here.

BuildingBlockDescription Robotino_2 dvg Robotino_2 {           
  BuildingBlock CollectBox {}
  BuildingBlock DockToRobot {}  
  BuildingBlock DeliverBox {}
  Container GotoLocation => "BBRepo.GotoLocation"
}

There are two special model of models composition types for ALLOCATABLE BuildingBlocks described in the following.

The EquivalenceFork (EQUF) model of models has the following structure:

BuildingBlockDescription <DesiredName> {
  ALLOCATABLE BuildingBlock <DesiredName> {
    ...
    allocationCandidates (robotModel_1, robotModel_2, ..., robotModel_n)
    ...
    Decomposition(<DesiredName>)
  }
  EquivalenceFork <DesiredName> {
    Container <DesiredName> => <Model_1>
    Container <DesiredName> => <Model_2>
    ...
    Container <DesiredName> => <Model_n>
  }
}

The Containers in the EquivalenceFork reuse n already existing (independently developed) ALLOCATABLE BuildingBlock models. Therefore the BuildingBlocks have to be referenced from a Container and can not be defined within a Container. The EquivalenceFork composition describes that the building block alternatives are equivalent with respect to the realized functionality but not with respect to non-functional properties. It means that all possible allocation combinations with respect to this variability will be evaluated but only one will be executed in the end depending on the evaluation result.

The complete project can be found here.

BuildingBlockDescription AllocOrderPickingEQUF dvg OrderPickingEQUF {
  ALLOCATABLE BuildingBlock AllocOrderPickingEQUF {
    Inputs {
      Mandatory M1 NumberObjects is UdoSimpleInteger
    }
    allocationCandidates (Robotino, Larry, Macy, Robotino_2)
    VariabilityEntitySet { PropertySet { Time is UdoTime } }
    Decomposition(OrderPickingVsSharedOrderPicking)
  }
  EquivalenceFork OrderPickingVsSharedOrderPicking {
    Container C1 => "AllocOrderPicking.AllocOrderPicking",
    Container C2 => "AllocSharedOrderPicking.AllocSharedOrderPicking"
  }
}

The associated DVG model is explained here. We reuse two alternative ALLOCATABLE BuildingBlocks named AllocOrderPicking and AllocSharedOrderPicking. We know the latter one already from the previous example. The former one describes an order picking procedure that can be executed by a single robot (the complete project can be found here.). So in the end, both models realize the same functionality and therefore the EquivalenceFork (de)composition.

The Parallel model of models has the following structure:

BuildingBlockDescription <DesiredName> {
  ALLOCATABLE BuildingBlock <DesiredName> {
  ...
  allocationCandidates (robotModel_1, robotModel_2, ..., robotModel_n)
  ...
  Decomposition(<DesiredName>)
  }
  Parallel <DesiredName> {
    policy <DesiredPolicy>
    Container <DesiredName> => <Model_1>
    Container <DesiredName> => <Model_2>
    ...
    Container <DesiredName> => <Model_n>
  }
}

The Containers in the Parallel decomposition type reuse n already existing (independently developed) ALLOCATABLE BuildingBlock models. Therefore the BuildingBlocks have to be referenced from a Container and can not be defined within a Container. The referenced BuildingBlocks can also be a EQUF Model of Models. The Parallel composition describes that the building block alternatives have to be executed in parallel. It means that all possible allocation combinations will be evaluated.

The complete project can be found here.

BuildingBlockDescription AllocProblem dvg AllocProblem {
  ALLOCATABLE BuildingBlock AllocProblem {
    allocationCandidates (Robotino, Larry, Macy, Robotino_2)
    VariabilityEntitySet { PropertySet { Time is UdoTime } }
    Decomposition(ParallelAllocProblem)
  }
  Parallel ParallelAllocProblem { 
    policy WAITFORALL
    Container C1 => "AllocTransportation.AllocTransportation",
    Container C2 => "AllocOrderPickingEQUF.AllocOrderPickingEQUF"
  }
}

The associated DVG model is explained here. We reuse two alternative ALLOCATABLE BuildingBlocks named AllocTransportation and AllocOrderPickingEQUF. The former one we already know from this example, but now it is defined as ALLOCATABLE BuildingBlock. The latter one is the EQUF model of models we already know from the previous example. So the task requirement of this parallel model of models is to allocate a transportation and a order picking task at the same time.