View source for Papyrus/customizations/robotics/compdef

= 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 ROS 2 (see [http://design.ros2.org/articles/node_lifecycle.html lifecycle in ROS 2]). 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 ==

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.

<center>
[[Image:Papyrus-customizations-robotics-functions.png|950px]]<br/>
List of functions, option to create or edit a function
</center>

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 ROS 2. 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 midd leware. 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 ROS 2, 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<ROS service>::SharedFuture</code> in case of ROS 2)
* QUERY (server side): two parameters, "request" and "response", typed with a (<code><ROS 2 service>::Request::SharedPtr</code> and <code><ROS service>::Response::SharedPtr</code> respectively in case of ROS 2)

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 ROS 2, please read the [https://wiki.eclipse.org/Papyrus/customizations/robotics/ros2 ROS 2 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 [[Papyrus/customizations/robotics/compdefscratch|component definition from scratch]] shows step-by-step how to develop a new component from scratch.