Example: Component Developer - Realizing Skills of a Component

This tutorial explains how a component developer describes which skills his/her software components can execute. The tutorial walks through selected components of the flexible navigation stack.

You already know how to develop a software component (see Develop Your First Software Component). The next step is to describe which skills a (set) of software component(s) can execute.

A skill arranges different services such that they become a particular robot capability. It translates between a generic name for a capability like move (from above) and configurations and parameterizations specific to the used services (downward). Services serve as the only access point to components to exchange information at a proper level of abstraction. Services separate the internal and external view of a component. They define the boundaries between components. Components realize services and might depend on the existence of a certain type of service(s) in a later system.

Skills provide access to capabilities realized by components. A skill is the bridge between generic descriptions of capabilities (independent of a particular implementation) and specific behavior interfaces (configuration: resources, parameters, wiring; coordination: modes, lifecycle, events) of a (set of) component(s) to achieve that capability (specific to the used components). A skill is important in decoupling implementations of capabilities (technology - individual and alternative implementations by different arrangements of software components) and agreed vocabularies for capabilities (application - domain-specific names and meanings for capabilities). A skill lifts the level of abstraction from a component-specific level to a domain-specific level. Thus, different implementations for the same capabilities become replaceable as they are accessed in a uniform way.

A skill allows to access the capabilities provided by a (set) of software component(s) via an agreed vocabulary. This vocabulary comes with a clear meaning and is understood in a domain. These so-called skill definitions are modeled and provided by tier-2 domain experts. A skill definition is the view from above. It comprises the domain-specific name of the skill, its in-/out-parameters and what kind of success/error values it returns. These can be found in the domain model in the skills file.

A coordination service definition is also defined by a tier-2 domain expert. It comprises an agreed vocabulary to refer in a standardized way to states and configuration parameters of an arrangement of software component(s). For example, one arrangement can be just one component providing all the skills (as below by the example of the localization), another one might be to foresee three components to provide the skills (as below by the example of the navigation). Different foreseen arrangements of software components result in different offered coordination service definitions in the services file in the domain model.

The component developer (tier 3) provides realizations of the skill definitions to represent a capability. The component developer uses the domain-specific skill definitions and the domain-specific coordination service definitions and maps them onto individual configurations and parameterizations of his/her component(s). Basically, the component developer must specify what skill definitions are realized by using which coordination service definitions in order to connect the upward interface of a skill (towards tasks) with the downward interface of a skill (interacting with the components).

In this way, only the component developer needs to know - and he/she knows of course - which component-specific individual settings produce which behavior. In particular, users such as system builders do not need to know component-specific individual settings - they just use the standardized skill vocabulary to access the capabilities implemented by the components.

The steps of this skill realization are always as following:

This step is done in the skillRealization file and defines the link between skill definitions and coordination service definitions to realize a skill. In practice, component developers do not reference single skill definitions but a coordination module definition that is just a collection of skill definitions. Hence, the component developer must specify which coordination module is realized by using which coordination service definitions.

Realizing a skill definition means to define a sequence of component configurations and parameterizations using the types defined in the associated coordination service definition (see part 1). In the future, this step will be done in the skillRealization file. At the moment, this editor is not finalized yet. Hence, we still have to do all the realizations and mappings manually in a separate smartTcl file without support of the tooling. This file contains different functions of the form (define-tcb (name) code) or (realize-tcb (name) code) (both forms are fully equivalent, there is no difference!) containing the code sequence of component service interactions for a specific skill definition by using the task coordination language SmartTCL. Since there is currently no automatic mapping between a define-tcb and a skill definition, the specific naming of a define-tcb is secondary but in the ideal case it should be named the same as the corresponding skill definition in order to allow for an easy manual association.

A coordination service definition can have so-called CommunicationServiceUsage(s) that reference specific service definitions (tier 2) to indicate that the sequencer has to interact with these services for realizing the coordination service. If a component developer implements a component using a coordination service definition containing one or several CommunicationServiceUsage(s), the component developer must specify in the textual component file as part of the CoordinationSlavePort which concrete component port realizes the referenced service definition of each CommunicationServiceUsage.

Let's assume you just completed the development of the following set of software components for navigation capabilities (these components are part of the flexible navigation stack that you can see in action in other lessons):

• SmartAmcl - Localization
• SmartMapperGridMap - Mapping
• SmartPlannerBreadthFirstSeach - Path Planner
• SmartCdlServer - Motion Control

As component developer, you used the

• tier-2 domain model for localization called CommLocalizationObjects for the first component
• tier-2 domain model for navigation called CommNavigationObjects for the next three components.

You now want to make the capabilities of the above four software components accessible in the form of skills.

Make sure that you open the view of the component supplier (tier 3) in the toolchain as indicated by (1) in the picture. The software component SmartAmcl provides all the localization services in a single component. We now assign the skills of the SmartAmcl component to this component. Thus, we open the SmartAmcl component as indicated by (2) in the below figure.

The software component SmartAmcl provides all the localization services in a single component. We now assign the skills of the SmartAmcl component to this component. Thereto, we open the SmartAmcl component as indicated by (2) in the below figure.

We navigate to the model folder in the SmartAmcl component and click on the file with the extension skillRealization (the skill realization model file, see (3) in the above figure).

Currently only the below shown snippet (also indicated by (4) in the above figure) is of interest in this file.

SkillRealizationModel {
    CoordinationModuleRealization locModRealization coordModuleDef CommLocalizationObjects.LocalizationModule
    uses {
        CommLocalizationObjects.LocalizationCoordinationService intsName amcl
    }
...

Line 2 defines that we realize the coordination module definition CommLocalizationObjects.LocalizationModule by using the name locModRealization for this coordination module realization.

Also as part of the coordination module realization locModRealization, line 3 and 4 state that we refer to the coordination service definition CommLocalizationObjects.LocalizationCoordinationService by using the instance name amcl.

We now click on the file with the extension smartTcl in the model folder of the SmartAmcl component.

Below code listings show the realization of three selected skill definitions contained in this file (with comments added for explanation purposes):

• the skill realization tcb-activate-localization of skill definition activateLocalization
• the skill realization tcb-deactivate-localization of skill definition deactivateLocalization
• the skill realization localizationSetRobotPose of skill definition setRobotPose

(define-tcb (tcb-activate-localization)
  (module "LocalizationModule")
  (action (
    (format t "=========================>>> tcb-activate-localization~%")
    ;; set the state of the amcl component to Active
    (tcl-state :server 'amcl :state "Active"))))

(define-tcb (tcb-deactivate-localization)
  (module "LocalizationModule")
  (action (
    (format t "=========================>>> tcb-deactivate-localization~%")
    ;; set the state of the amcl component to Active
    (tcl-state :server 'amcl :state "Neutral"))))

(define-tcb (localizationSetRobotPose ?x ?y ?yaw) ;;x,y,yaw are incoming parameters
  (module "LocalizationModule")                   ;; module specifies to which module this skill belongs
  (action (
    (format t "=========================>>> localizationSetRobotPose~%")
    (format t "SetRobotPose x: ~s y: ~s phi: ~s ~%" ?x ?y ?yaw)
    ;; set the state of the amcl component to Neutral
    (tcl-state :server 'amcl :state "Neutral")
 
    ;; set initial pose through the given parameters
    (tcl-param :server 'amcl :slot 'CommLocalizationObjects.LocalizationParameter.INITIALPOSE :value '(?x ?y ?yaw))
 
    ;; set the state of the amcl component to Active
    (tcl-state :server 'amcl :state "Active"))))

We now click on the file with the extension .component in the model folder of the SmartAmcl component. In line 15, we can see that the coordination slave port of this component implements the coordination service definition CommLocalizationObjects.LocalizationCoordinationService (the same that we also specified in the skillRealization file (part 1)). In line 20, we define that the communication service usage localizationEvent from CommLocalizationObject.LocalizationCoordinationService is realized by the LocalizationEventServiceOut output port of this component defined in line 34. Finally we need to specify a SkillRealizationsRef to the coordination module realization locModRealization.

Make sure that you open the view of the component supplier (tier 3) in the toolchain as indicated by (1) in the picture. The three components SmartMapperGridMap, SmartPlannerBreadthFirstSearch and SmartCdlServer require each other to provide navigation capabilities. A single component with its services is not enough. We decide to assign the skills for these three components to the SmartCdlServer component. This is an arbitrary decision and you could have assigned the skills to either of the three components. Thus, we open the SmartCdlServer component as indicated by (2) in the below figure.

We navigate to the model folder in the SmartCdlServer component and click on the file with the extension skillRealization (the skill realization model file, see (3) in the below figure).

Currently only the below shown snippet (also indicated by (4) in the above figure) is of interest in this file.

SkillRealizationModel {
    CoordinationModuleRealization MovementMod2 coordModuleDef CommNavigationObjects.NavigationModule
    uses {
        CommNavigationObjects.CdlCoordinationService intsName cdl
        CommNavigationObjects.MapperCoordinationService intsName mapper
        CommNavigationObjects.PlannerCoordinationService intsName planner
   }
...

Line 2 defines that we realize the coordination module definition CommNavigationObjects.NavigationModule by using the name MovementMod2 for this coordination module realization.

Also as part of the coordination module realization MovementMod2, line 3-7 state that we refer to the coordination service definitions CommNavigationObjects.CdlCoordinationService (using the instance name cdl), CommNavigationObjects.MapperCoordinationService (using the instance name mapper) and CommNavigationObjects.PlannerCoordinationService (using the instance name planner).

We now click on the file with the extension smartTcl in the model folder of the SmartCdlServer component. This file contains all the skills realized by our three components.

Below code listings show the realization of three selected skill definitions contained in this file (with comments added for explanation purposes):

• the skill realization initNavigation of skill definition initNavigation
• the skill realization loadNavigationMap of skill definition loadNavigationMap
• the skill realization approachLocation of skill definition approachLocation

The first code listing shows the realization of the skill initNavigation.

(realize-tcb  (initNavigation) ;; realize-tcb defines the skill. TCB = Task Coordination Block
  (module "NavigationModule")  ;; module specifies to which module this skill belongs
  (action (                    ;; action specifies what is executed in this TCB      
            (format t "=========================>>> initNavigation ~%")
 
            ;; query the knowledge base to get the name of the current room in which robot is present
            (let* ((robot (tcl-kb-query :key '(is-a) :value '((is-a robot))))
                   (robot-current-room-name (get-value (tcl-kb-query :key '(is-a)  :value '((is-a robot))) 'current-room))
                   (robot-room (tcl-kb-query :key '(is-a name) :value `((is-a room)(name ,robot-current-room-name)))))
 
            ;; set the state of the mapper component to Neutral
            (tcl-state :server 'mapper  :state "Neutral")
 
            ;; send default runtime parameters to the mapper component
            (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.LTMPARAMETER :value (append (get-value robot-room 'size)
                                            (get-value robot-room 'offset)
                                            (list 0)))
            (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.LTMLOADYAML :value (get-value robot 'default-nav-map))
            (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.CURLTM      :value '(DISABLE 30))
            (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.CUREMPTY    :value 'ACCUMULATE)
            (tcl-param :server 'mapper :slot 'COMMIT)
 
	     ;; set the state of the cdl component to Neutral
            (tcl-state :server 'cdl :state "Neutral")
            ;; send runtime parameters to the cdl component
            (tcl-param :server 'cdl :slot 'CommNavigationObjects.CdlParameter.FREEBEHAVIOR :value 'ACTIVATE)
            (tcl-param :server 'cdl :slot 'CommNavigationObjects.CdlParameter.LOOKUPTABLE  :value 'DEFAULT)
            (tcl-param :server 'cdl :slot 'CommNavigationObjects.CdlParameter.APPROACHDIST :value 100)
            (tcl-param :server 'cdl :slot 'COMMIT)
            '(SUCCESS ())))))

The second code listing shows the realization of the skill loadNavigationMap, again with added comments.

(realize-tcb  (loadNavigationMap ?map)  ;; map parameter contains path to the yaml file
  (module "NavigationModule")
  (action (
            (format t "=========================>>> loadNavigationMap ~s ~%" '?map)
            ;; query the knowledge base to get the name of the current room in which robot present now
            (let* ((robot (tcl-kb-query :key '(is-a) :value '((is-a robot))))
                   (robot-current-room-name (get-value (tcl-kb-query :key '(is-a)  :value '((is-a robot))) 'current-room))
                   (robot-room (tcl-kb-query :key '(is-a name) :value `((is-a room)(name ,robot-current-room-name)))))
 
            ;; set the state of the mapper component to Neutral
            (tcl-state :server 'mapper  :state "Neutral")
            ;; send map parameters to the mapper component
            (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.LTMPARAMETER :value (append (get-value robot-room 'size)
                                            (get-value robot-room 'offset)
                                            (list 0)))
 
            (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.LTMLOADYAML :value ?map)
            (tcl-param :server 'mapper :slot 'COMMIT)
 
            ;; set the state of the mapper component to BuildCurrMap, after this mapper component will update the map with information from incoming laser scans.
            (tcl-state :server 'mapper :state "BuildCurrMap")
            '(SUCCESS ())))))

The third code listing shows the realization of the skill approachLocation, again with added comments. The approachLocation skill has multiple definitions and below definition is for the case when the given location has approach type as region.

(define-tcb (approachLocation ?location) ;; location parameter contains location identifier
  (module "NavigationModule")
 
  ;; Rules are used for error handling in the tcb. Also specifies which errors invoke the rules
  ;; Rules get executed when tcb generates error.  
  ;; If the given location is not available in the knowledge base, rule-unknown-location will be executed.
  (rules (rule-unknown-location rule-location-success rule-robot-blocked rule-abort-job-error-ack))
 
  ;; check that location is of type region
  (precondition  (equal '(region) (get-value (tcl-kb-query :key '(is-a name) :value '( (is-a location) (name ?location))) 'approach-type)))
  ;; used for selecting the skill when multiple matching skills are avaible
  (priority 99)
 
  ;; action to be taken in case of aborting the current tcb
  ;; useful for cleanup actions
  ;; Here, in case of an unknown location, cdl, mapper, planner components will be set in Neutral state.
  (abort-action (
                  (tcl-state :server 'cdl :state "Neutral")
                  (tcl-state :server 'mapper :state "Neutral")
                  (tcl-state :server 'planner :state "Neutral")))
  ;; plan call the skills in a sequence by default
  ;; Use 'parallel' clause if you want more than one skill to run parallel
  ;; Use 'one-of' clause if you want skills to run parallel but abort others in the plan, if one of the tcb is finished 
  (plan (
          (tcb-move-robot 'approach-region ?location)
          (tcb-move-robot 'orientate-region ?location))))

We now click on the file with the extension .component in the model folder of the SmartCdlServer component. In line 31, we can see that the coordination slave port of this component implements the coordination service definition CommNavigationObjects.CdlCoordinationService (the same that we also specified in the skillRealization file (part 1)). In line 39, we define that the communication service usage blockedEvent from CommNavigationObjects.CdlCoordinationService is realized by the RobotBlockedEventServer output port of this component. In line 40, we define that the communication service usage goalEvent from CommNavigationObjects.CdlCoordinationService is realized by the GoalEventServer output port of this component. Finally we need to specify a SkillRealizationsRef to the coordination module realization MovementMod2.

Now you can proceed with tutorial «to be added»