documentation:skiros:skill_description [robotwiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Skill Description ======

This page will refer to example skills from [[https://git.cs.lth.se/robotlab/skill_examples/-/tree/master/|this]] repository written by Pontus Rosqvist.

A skill description extends [[https://git.cs.lth.se/robotlab/rvmi/skiros2/-/blob/master/skiros2_common/src/skiros2_common/core/abstract_skill.py|SkillDescription]] and is an object which keeps track of which parameters a skill has, what type the parameters are and if they  are required, can be inferred or optional. In the skill description one also specifies any conditions which need to be met, these can be pre-conditions (before the skill is executed), hold-conditions (while the skill is executing) and post-conditions (after the skill has been executed). These conditions only need to be specified, SkiROS then takes care of checking that they hold. An example of a skill description can be seen in [[https://git.cs.lth.se/robotlab/skill_examples/-/blob/master/src/skill_examples/basic_primitive_skill.py|basic_primitive]], [[https://git.cs.lth.se/robotlab/skill_examples/-/blob/master/src/skill_examples/skill_phases.py|skill_phases]] and [[https://git.cs.lth.se/robotlab/skill_examples/-/blob/master/src/skill_examples/infer_parameters.py|infer_parameters]] among others.

===== Parameters =====

The parameters a skill has is specified in the skill description. A parameter can be a python object or an object from the world model. A float could be specified as a parameter in the following way:

<cli>
class DescriptionName(SkillDescription):
  def createDescription(self):
    self.addParam('NameOfParameter', 0.0, ParamTypes.Required)
</cli>

Here the value "0.0" becomes the default value for that parameter, one can also specify that the parameter has to be a float without specifying a default parameters:

<cli>
class DescriptionName(SkillDescription):
  def createDescription(self):
    self.addParam('NameOfParameter', Float, ParamTypes.Required)
</cli>

A parameter has a name which is a string which determines the key that the parameter is saved with in the dict self.params in the skill. One also needs to specify if the parameter is required optional or similar. The types of parameters are

  * ParamTypes.Required
  * ParamTypes.Optional
  * ParamTypes.Inferred

Required parameters need to be specified, optional parameters do not :). Inferred parameters are parameters which are required but the skill description can infer them with the help of the world model. Parameters can be inferred if they are the only parameter which satisifes that condition, these conditions might be that the object is the only object of that type in the world model or if the pre-conditions uniquely determine the object in the world model. An example of how one can infer a parameter can be seen in [[https://git.cs.lth.se/robotlab/skill_examples/-/blob/master/src/skill_examples/infer_parameters.py|infer_parameters]].

The type of a parameter can also be a type which exists in the world model, these are specified in the following way

<cli>
class DescriptionName(SkillDescription):
  def createDescription(self):
    self.addParam('NameOfParameter', Element('PREFIX:TYPE'), ParamTypes.Required)
</cli>

Concrete examples of how this can be done can be seen in [[https://git.cs.lth.se/robotlab/skill_examples/-/blob/master/src/skill_examples/update_world_model.py|update_world_model]], [[https://git.cs.lth.se/robotlab/skill_examples/-/blob/master/src/skill_examples/infer_parameters.py|infer_parameters]] and [[https://git.cs.lth.se/robotlab/skill_examples/-/blob/master/src/skill_examples/world_model_interface.py|world_model_interface]].

===== Pre-conditions =====

The purpose of pre conditions are two-fold. Firstly pre conditions specify if a skill can be run or not, if the pre conditions cannot be satisfied the skill will not execute. Secondly pre conditions help SkiROS infer parameter, these do not need to be specified in the SkiROS gui, instead they are inferred when the skill is run.

Pre-conditions can be specified in the skill description in the following way

<cli>
def createDescription(self):
      self.addParam('param1', Element('skiros:TransformationPose'), ParamTypes.Required)
      self.addParam('param2', Element('skiros:TransformationPose'), ParamTypes.Required)
      
      self.addPreCondition(self.getRelationCond('1_has_2', 'skiros:hasA', 'param1', 'param2', True))
</cli>

A precondition for a skill with this skill description will then be that param1 is related to param2 with a hasA relation. This can be used to infer parameters from the world model, an example of this can be seen in [[https://git.cs.lth.se/robotlab/skill_examples/-/blob/master/src/skill_examples/infer_parameters.py|infer_parameters]]. If the preconditions are not satisfied the skill will not even start. Sometimes SkiROS tells you why and which preconditions failed, sometimes it does not tell you.

The relationship between parameters specified can't be overly complicated because then SkiROS will not be able to infer them correctly. Exactly when SkiROS fails to infer parameters is unknown at the moment. A normal relationship as above and chained relationships are however fine. When several elements are related to several other elements it gets more hairy.

===== Hold-conditions =====

A hold condition is a condition which SkiROS either checks while the skill is running or your responsible for checking it continuously. Only SkiROS knows. They are specified similarly to the other conditions, i.e.:

<cli>
      self.addHoldCondition(""" condition """)
</cli>

===== Post-conditions =====

A post condition is a condition which needs to be true when the skill has concluded. These are primarily used for skill planning. A post condition is specified similarly to the other conditions, i.e.

<cli>
      self.addPostCondition(""" condition """)
</cli>