Table of Contents

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.

Basic Information

Level Beginner
Role component builder
Assumptions You know how to develop a software component
System Requirements Virtual Appliance installed, see ready-to-go virtual appliance
You will learn - how to …
- how to …
- how to …
Options - …

Introduction

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.

Part 2: Realize the Skill 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.

Skills by the Example of the Flexible Navigation Stack

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):

As component developer, you used the

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

Localization

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.

  1. SkillRealizationModel {
  2. CoordinationModuleRealization locModRealization coordModuleDef CommLocalizationObjects.LocalizationModule
  3. uses {
  4. CommLocalizationObjects.LocalizationCoordinationService intsName amcl
  5. }
  6. ...

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.

Part 2: Realize the Skill Definitions

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):

  1. (define-tcb (tcb-activate-localization)
  2. (module "LocalizationModule")
  3. (action (
  4. (format t "=========================>>> tcb-activate-localization~%")
  5. ;; set the state of the amcl component to Active
  6. (tcl-state :server 'amcl :state "Active"))))
  1. (define-tcb (tcb-deactivate-localization)
  2. (module "LocalizationModule")
  3. (action (
  4. (format t "=========================>>> tcb-deactivate-localization~%")
  5. ;; set the state of the amcl component to Active
  6. (tcl-state :server 'amcl :state "Neutral"))))
  1. (define-tcb (localizationSetRobotPose ?x ?y ?yaw) ;;x,y,yaw are incoming parameters
  2. (module "LocalizationModule") ;; module specifies to which module this skill belongs
  3. (action (
  4. (format t "=========================>>> localizationSetRobotPose~%")
  5. (format t "SetRobotPose x: ~s y: ~s phi: ~s ~%" ?x ?y ?yaw)
  6. ;; set the state of the amcl component to Neutral
  7. (tcl-state :server 'amcl :state "Neutral")
  8.  
  9. ;; set initial pose through the given parameters
  10. (tcl-param :server 'amcl :slot 'CommLocalizationObjects.LocalizationParameter.INITIALPOSE :value '(?x ?y ?yaw))
  11.  
  12. ;; set the state of the amcl component to Active
  13. (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.

Mapping, Planning, Motion Control

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.

  1. SkillRealizationModel {
  2. CoordinationModuleRealization MovementMod2 coordModuleDef CommNavigationObjects.NavigationModule
  3. uses {
  4. CommNavigationObjects.CdlCoordinationService intsName cdl
  5. CommNavigationObjects.MapperCoordinationService intsName mapper
  6. CommNavigationObjects.PlannerCoordinationService intsName planner
  7. }
  8. ...

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).

Part 2: Realize the Skill Definitions

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 first code listing shows the realization of the skill initNavigation.

  1. (realize-tcb (initNavigation) ;; realize-tcb defines the skill. TCB = Task Coordination Block
  2. (module "NavigationModule") ;; module specifies to which module this skill belongs
  3. (action ( ;; action specifies what is executed in this TCB
  4. (format t "=========================>>> initNavigation ~%")
  5.  
  6. ;; query the knowledge base to get the name of the current room in which robot is present
  7. (let* ((robot (tcl-kb-query :key '(is-a) :value '((is-a robot))))
  8. (robot-current-room-name (get-value (tcl-kb-query :key '(is-a) :value '((is-a robot))) 'current-room))
  9. (robot-room (tcl-kb-query :key '(is-a name) :value `((is-a room)(name ,robot-current-room-name)))))
  10.  
  11. ;; set the state of the mapper component to Neutral
  12. (tcl-state :server 'mapper :state "Neutral")
  13.  
  14. ;; send default runtime parameters to the mapper component
  15. (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.LTMPARAMETER :value (append (get-value robot-room 'size)
  16. (get-value robot-room 'offset)
  17. (list 0)))
  18. (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.LTMLOADYAML :value (get-value robot 'default-nav-map))
  19. (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.CURLTM :value '(DISABLE 30))
  20. (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.CUREMPTY :value 'ACCUMULATE)
  21. (tcl-param :server 'mapper :slot 'COMMIT)
  22.  
  23. ;; set the state of the cdl component to Neutral
  24. (tcl-state :server 'cdl :state "Neutral")
  25. ;; send runtime parameters to the cdl component
  26. (tcl-param :server 'cdl :slot 'CommNavigationObjects.CdlParameter.FREEBEHAVIOR :value 'ACTIVATE)
  27. (tcl-param :server 'cdl :slot 'CommNavigationObjects.CdlParameter.LOOKUPTABLE :value 'DEFAULT)
  28. (tcl-param :server 'cdl :slot 'CommNavigationObjects.CdlParameter.APPROACHDIST :value 100)
  29. (tcl-param :server 'cdl :slot 'COMMIT)
  30. '(SUCCESS ())))))

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

  1. (realize-tcb (loadNavigationMap ?map) ;; map parameter contains path to the yaml file
  2. (module "NavigationModule")
  3. (action (
  4. (format t "=========================>>> loadNavigationMap ~s ~%" '?map)
  5. ;; query the knowledge base to get the name of the current room in which robot present now
  6. (let* ((robot (tcl-kb-query :key '(is-a) :value '((is-a robot))))
  7. (robot-current-room-name (get-value (tcl-kb-query :key '(is-a) :value '((is-a robot))) 'current-room))
  8. (robot-room (tcl-kb-query :key '(is-a name) :value `((is-a room)(name ,robot-current-room-name)))))
  9.  
  10. ;; set the state of the mapper component to Neutral
  11. (tcl-state :server 'mapper :state "Neutral")
  12. ;; send map parameters to the mapper component
  13. (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.LTMPARAMETER :value (append (get-value robot-room 'size)
  14. (get-value robot-room 'offset)
  15. (list 0)))
  16.  
  17. (tcl-param :server 'mapper :slot 'CommNavigationObjects.MapperParams.LTMLOADYAML :value ?map)
  18. (tcl-param :server 'mapper :slot 'COMMIT)
  19.  
  20. ;; set the state of the mapper component to BuildCurrMap, after this mapper component will update the map with information from incoming laser scans.
  21. (tcl-state :server 'mapper :state "BuildCurrMap")
  22. '(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.

  1. (define-tcb (approachLocation ?location) ;; location parameter contains location identifier
  2. (module "NavigationModule")
  3.  
  4. ;; Rules are used for error handling in the tcb. Also specifies which errors invoke the rules
  5. ;; Rules get executed when tcb generates error.
  6. ;; If the given location is not available in the knowledge base, rule-unknown-location will be executed.
  7. (rules (rule-unknown-location rule-location-success rule-robot-blocked rule-abort-job-error-ack))
  8.  
  9. ;; check that location is of type region
  10. (precondition (equal '(region) (get-value (tcl-kb-query :key '(is-a name) :value '( (is-a location) (name ?location))) 'approach-type)))
  11. ;; used for selecting the skill when multiple matching skills are avaible
  12. (priority 99)
  13.  
  14. ;; action to be taken in case of aborting the current tcb
  15. ;; useful for cleanup actions
  16. ;; Here, in case of an unknown location, cdl, mapper, planner components will be set in Neutral state.
  17. (abort-action (
  18. (tcl-state :server 'cdl :state "Neutral")
  19. (tcl-state :server 'mapper :state "Neutral")
  20. (tcl-state :server 'planner :state "Neutral")))
  21. ;; plan call the skills in a sequence by default
  22. ;; Use 'parallel' clause if you want more than one skill to run parallel
  23. ;; Use 'one-of' clause if you want skills to run parallel but abort others in the plan, if one of the tcb is finished
  24. (plan (
  25. (tcb-move-robot 'approach-region ?location)
  26. (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.

What to do next?

Now you can proceed with tutorial «to be added»

Acknowledgements

DokuWiki Appliance - Powered by TurnKey Linux