Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Papyrus/customizations/robotics/compdef"

(Creating parameters)
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Component Definition =
+
= Component definition principle =
  
A component definition is an encapsulated entity that consists of activities (which in turn have functions), ports and parameters. See also [https://robmosys.eu/wiki/modeling:metamodels:component Component Definition meta-model]  
+
A component definition is an encapsulated entity that consists of activities, ports and parameters. It defines the type of an element that will be instantiated at the system design stage. A component has different lifecycle phases, like nodes in ROS2 (see [http://design.ros2.org/articles/node_lifecycle.html lifecycle in ROS2]). A component definition meta-model can be found [https://robmosys.eu/wiki/modeling:metamodels:component here].
 +
 
 +
The parameters are the interface constants of the component.
 +
 
 +
Its ports are its interfaces for the interaction with the other components. They can be either “Provided” or “Required” and are typed by a Service definition.
 +
 
 +
Activities have functions and ports. They structure a kind of internal behavior of the component. An activity gathers functions that may be executed:
 +
* As an handler, i.e. in relationship with an activity port itself connected to a component port
 +
* Periodically, if the Activity is marked as Periodic Task,
 +
* Manually, i.e. called internally by another function,
 +
* On a component lifecycle’s transition, i.e. on configure, on activate, on deactivate, on cleanup or on error.
 +
 
 +
 
 +
Moreover, the code of the functions may be written in the model or outside, as separate files to be provided in conformity with the prototypes that will be generated by the code generation.
 +
 
 +
= How to edit =
 +
 
 +
The following Palette is used to edit the selected component:
 +
<center>
 +
[[Image:Papyrus-customizations-robotics-comp-palette.png|200px]]<br/>
 +
Component definition palette
 +
</center>
  
 
== Creating parameters ==
 
== Creating parameters ==
  
A parameter entry is part of a parameter block. If you create a new component definition using the wizard, the parameter block is already part of your component. A new parameter can be created in two different ways
+
A parameter entry is part of a parameter block. If you create a new component definition using the wizard, the parameter block is already part of your component. A new parameter can be created in different ways  
(1) Use the diagram and add a parameter entry to the parameter block (Note that you cannot drop an entry on the icon itself).
+
 
 +
(1) Select the "Parameters Settings" tab in the Property view and add an element via the "+" button embedded into the table.
 +
 
 
(2) Opening the textual editor for the component definition. This editor appears in a property view tab called "Textual Spec." when the component is selected.
 
(2) Opening the textual editor for the component definition. This editor appears in a property view tab called "Textual Spec." when the component is selected.
  
An overview of the properties along with their type an description is available along with their type, if either the component itself or the parameter block is selected.
+
An overview of the properties along with their type and description is available, if either the component itself or the parameter block is selected.
  
 
== Component ports ==
 
== Component ports ==
  
A ports can be created via the "Component Port" tool from the palette. It must be placed on the border of the component. When a new port is created, the tool will first ask whether this is a provided or required port.
+
A port can be created via the "Component Port" tool from the palette. It must be placed on the border of the component. When a new port is created, the tool will first ask whether this is a “Provided” or “Required” port. Afterwards, the user has to select an existing service definition, either from a model already loaded into the resource set (since already referenced by another element of your model), a registered model or a model in the workspace.
Afterwards, the user has to select an existing service definition, either from a model already loaded into the resource set (since already referenced by another element of your model), a registered model or a model in the workspace.
+
  
 
== Activities ==
 
== Activities ==
Line 26: Line 48:
 
<center>
 
<center>
 
[[Image:Papyrus-customizations-robotics-functions.png|950px]]<br/>
 
[[Image:Papyrus-customizations-robotics-functions.png|950px]]<br/>
Creation and editing of functions
+
List of functions, option to create or edit a function
 
</center>
 
</center>
  
=== Linking functions with Activities ===
+
Please note that if you edit a function, the pop-dialog will initially present the ID tab used to edit its name, you need to navigate explicitly to the function tab.
 +
The association of a function with an activity port can be expressed by means of an activity port reference. visible in the upper right corner of the function edit dialog, see below.
 +
 
 +
<center>
 +
[[Image:Papyrus-customizations-robotics-function-edit.png|850px]]<br/>
 +
Edit a function
 +
</center>
 +
 
 +
=== Function code ===
 +
 
 +
A function can optionally contain C or C++ code. If present (the property "code in model" is calculated automatically), the code will be embedded into the generated code by the code generator, for instance for ROS2. As the editor in the popup dialog is a text editor without programming language specific support (such as syntax checking or completion), it is recommended to embed to small code fragments into the model. If the code is present on the model level, generated code (placed into the src-gen folder) contains a full implementation.
 +
 
 +
If the code is not part of the model, the code generator will create an implementation skeleton (in a folder called src-skel). This skeleton file is overwritten in each code generation step. Therefore, the developer should create a copy of the skeleton file in the "src" folder (while preserving relative paths, e.g. a src-skel/folderA/fileA.cpp should be copied to src/folderA/fileA.cpp). The copied file can then be completed with a C++ editor such as Eclipse CDT in order to profit from
 +
syntax checking and code completion.
 +
 
 +
=== Function parameters ===
 +
 
 +
Functions that act as callback handlers are called by the middleware. When called, the middleware passes data to (or obtains data from) these functions via parameters. The number and name of the parameters will depend on the communication protocol and the used middleware. In case of ROS2, the following list outlines the parameters for each:
 +
* PUSH or SEND (server side): a single parameter, <code>name</code> = name of the communication object in lower case
 +
* QUERY (client side): single parameter "future", callback function for obtaining the result (typed with a <code>rclcpp::Client<ROS2 service>::SharedFuture</code> in case of ROS2)
 +
* QUERY (server side): two parameters, "request" and "response", typed with a (<code><ROS2 service>::Request::SharedPtr</code> and <code><ROS2 service>::Response::SharedPtr</code> respectively in case of ROS2)
 +
 
 +
If the user provides a code fragment on the model level, the parameters are not visible directly in the dialog. But they can be checked out by opening the generated files in the src-gen folder. This issue is not present, if the code is completed later in the complete C++ file in the src folder (copied from the skeletons, as written in the previous paragraph).
 +
 
 +
For more information specific for ROS2, please read the [https://wiki.eclipse.org/Papyrus/customizations/robotics/ros2 ROS2 specific section].
 +
 
 +
=== Linking functions with activities ===
  
 
In order to link a function with a a port on the component level, a function is linked with an activity port (via an activity port reference that can be set via the property view). The activity port is linked with the component port via a connector that is available in palette.
 
In order to link a function with a a port on the component level, a function is linked with an activity port (via an activity port reference that can be set via the property view). The activity port is linked with the component port via a connector that is available in palette.
  
 
When the user creates the link between a component port and an activity port, the tool will automatically create a handler function (with correctly setup activity port), if there is no function yet that is associated with the activity port.
 
When the user creates the link between a component port and an activity port, the tool will automatically create a handler function (with correctly setup activity port), if there is no function yet that is associated with the activity port.
 +
 +
== Non functional properties, assertions and contracts ==
 +
 +
In addition to parameters, components can be enriched with additional properties that enable further analysis. All of these can be provided in tables that are available in the property view, when a component definition is selected.
 +
 +
* Non functional properties are calculated expressions. For instance, the maximal power consumption of a robotic arm could be calculated from the number and type of motors. The editor offers extensible languages, including a simple "parameter" language and OCL
 +
 +
* Assertions: Assertions are boolean expressions, for instance written in OCL that enable reasoning about system properties and are referenced from contracts
 +
 +
* Contracts: A contract is a set of assumptions and guarantees. If the assumptions hold, the system assures that the guarantees will hold as well.
 +
 +
= Component definition from scratch =
 +
 +
The section [[Papyrus/customizations/robotics/compdefscratch|component definition from scratch]] shows step-by-step how to develop a new component from scratch.

Revision as of 08:33, 17 September 2020

Component definition principle

A component definition is an encapsulated entity that consists of activities, ports and parameters. It defines the type of an element that will be instantiated at the system design stage. A component has different lifecycle phases, like nodes in ROS2 (see lifecycle in ROS2). A component definition meta-model can be found here.

The parameters are the interface constants of the component.

Its ports are its interfaces for the interaction with the other components. They can be either “Provided” or “Required” and are typed by a Service definition.

Activities have functions and ports. They structure a kind of internal behavior of the component. An activity gathers functions that may be executed:

  • As an handler, i.e. in relationship with an activity port itself connected to a component port
  • Periodically, if the Activity is marked as Periodic Task,
  • Manually, i.e. called internally by another function,
  • On a component lifecycle’s transition, i.e. on configure, on activate, on deactivate, on cleanup or on error.


Moreover, the code of the functions may be written in the model or outside, as separate files to be provided in conformity with the prototypes that will be generated by the code generation.

How to edit

The following Palette is used to edit the selected component:

Papyrus-customizations-robotics-comp-palette.png
Component definition palette

Creating parameters

A parameter entry is part of a parameter block. If you create a new component definition using the wizard, the parameter block is already part of your component. A new parameter can be created in different ways

(1) Select the "Parameters Settings" tab in the Property view and add an element via the "+" button embedded into the table.

(2) Opening the textual editor for the component definition. This editor appears in a property view tab called "Textual Spec." when the component is selected.

An overview of the properties along with their type and description is available, if either the component itself or the parameter block is selected.

Component ports

A port can be created via the "Component Port" tool from the palette. It must be placed on the border of the component. When a new port is created, the tool will first ask whether this is a “Provided” or “Required” port. Afterwards, the user has to select an existing service definition, either from a model already loaded into the resource set (since already referenced by another element of your model), a registered model or a model in the workspace.

Activities

Activities can be created from the palette. Activities have functions that are handling requests arriving at a component port (being called) or actively sending messages or requests (calling) to a port.

Functions

Functions can be created via the property view of activities, via the "+" icon in the dialog shown below.

Papyrus-customizations-robotics-functions.png
List of functions, option to create or edit a function

Please note that if you edit a function, the pop-dialog will initially present the ID tab used to edit its name, you need to navigate explicitly to the function tab. The association of a function with an activity port can be expressed by means of an activity port reference. visible in the upper right corner of the function edit dialog, see below.

Papyrus-customizations-robotics-function-edit.png
Edit a function

Function code

A function can optionally contain C or C++ code. If present (the property "code in model" is calculated automatically), the code will be embedded into the generated code by the code generator, for instance for ROS2. As the editor in the popup dialog is a text editor without programming language specific support (such as syntax checking or completion), it is recommended to embed to small code fragments into the model. If the code is present on the model level, generated code (placed into the src-gen folder) contains a full implementation.

If the code is not part of the model, the code generator will create an implementation skeleton (in a folder called src-skel). This skeleton file is overwritten in each code generation step. Therefore, the developer should create a copy of the skeleton file in the "src" folder (while preserving relative paths, e.g. a src-skel/folderA/fileA.cpp should be copied to src/folderA/fileA.cpp). The copied file can then be completed with a C++ editor such as Eclipse CDT in order to profit from syntax checking and code completion.

Function parameters

Functions that act as callback handlers are called by the middleware. When called, the middleware passes data to (or obtains data from) these functions via parameters. The number and name of the parameters will depend on the communication protocol and the used middleware. In case of ROS2, the following list outlines the parameters for each:

  • PUSH or SEND (server side): a single parameter, name = name of the communication object in lower case
  • QUERY (client side): single parameter "future", callback function for obtaining the result (typed with a rclcpp::Client<ROS2 service>::SharedFuture in case of ROS2)
  • QUERY (server side): two parameters, "request" and "response", typed with a (<ROS2 service>::Request::SharedPtr and <ROS2 service>::Response::SharedPtr respectively in case of ROS2)

If the user provides a code fragment on the model level, the parameters are not visible directly in the dialog. But they can be checked out by opening the generated files in the src-gen folder. This issue is not present, if the code is completed later in the complete C++ file in the src folder (copied from the skeletons, as written in the previous paragraph).

For more information specific for ROS2, please read the ROS2 specific section.

Linking functions with activities

In order to link a function with a a port on the component level, a function is linked with an activity port (via an activity port reference that can be set via the property view). The activity port is linked with the component port via a connector that is available in palette.

When the user creates the link between a component port and an activity port, the tool will automatically create a handler function (with correctly setup activity port), if there is no function yet that is associated with the activity port.

Non functional properties, assertions and contracts

In addition to parameters, components can be enriched with additional properties that enable further analysis. All of these can be provided in tables that are available in the property view, when a component definition is selected.

  • Non functional properties are calculated expressions. For instance, the maximal power consumption of a robotic arm could be calculated from the number and type of motors. The editor offers extensible languages, including a simple "parameter" language and OCL
  • Assertions: Assertions are boolean expressions, for instance written in OCL that enable reasoning about system properties and are referenced from contracts
  • Contracts: A contract is a set of assumptions and guarantees. If the assumptions hold, the system assures that the guarantees will hold as well.

Component definition from scratch

The section component definition from scratch shows step-by-step how to develop a new component from scratch.

Back to the top