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)
Line 59: Line 59:
 
Edit a function
 
Edit a function
 
</center>
 
</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 ==
 
== Linking functions with Activities ==
Line 133: Line 152:
  
 
A component definition is a '''tier-3''' activity, i.e. an activity that is typically done by a '''component developer'''. A component developer manages the design and configuration of components as well as their parameters. He can edit its architecture in the Architecture Model Explorer and he can specify in each component which port uses a given service.
 
A component definition is a '''tier-3''' activity, i.e. an activity that is typically done by a '''component developer'''. A component developer manages the design and configuration of components as well as their parameters. He can edit its architecture in the Architecture Model Explorer and he can specify in each component which port uses a given service.
 
= ROS2 code generation =
 
 
Please read [https://wiki.eclipse.org/Papyrus/customizations/robotics/ros2 here] for more details on ROS2 code generation.
 
 
== Function ==
 
 
A function can optionally contain 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.
 
 
If not, the ROS2 generator will create an implementation skeleton (in a folder called src-skel) that needs to be edited after code generation. In order to avoid that the file is overwritten by subsequent calls of the generator, the developer should create a copy the skeleton in the "src" folder.
 
 
== Function parameters ==
 
 
During code generation for ROS2, Papyrus will add the required arguments for functions that act as a callback handler. The number and name of the function will depend on the communication protocol. In the following list, the parameters are outlined.
 
* 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, he can check which parameters are used in the generated method in the src-gen folder. If he does not provide a code fragment on the model level, Papyrus will place the code of the method in the src-skel folder. In this case, the method signature is visible in the editor when completing the skeleton.
 

Revision as of 16:41, 31 August 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) (Deprecated) use the diagram and add a parameter entry to the parameter block (Note that you cannot drop an entry on the icon itself). While this is still possible, we recommend the use one of the two other options.

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

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

Component definitions from scratch

Forewords

Please read here for the description of the example taken as reference in this section.

Step-by-step procedure

We may now define the types of the components to be created:

  1. We create a new Robotics project with “Create a component” as the main objective.
  2. Then, we click on “Next” and choose the project’s name, for example fromscratch_components, before clicking on “Finish”.
  3. As we aim to define two component types that will be named Mult_client (that send the data to be multiplied) and Mult_server (that performs the multiplication), we suppress the initial model by right-clicking on fromscratch_components/components/fromscratch_components.compdef and selecting Delete.
  4. We then select the fromscratch_components/models/components, we right-click on it, we select New Robotics model with “Create a component” as the main objective.
  5. Then, we click on “Next”, we see the parent folder as fromscratch_components/models/components, we replace the File name by mult_server.compdef.di, before clicking on “Finish”.
  6. We now click on the “Mult_server diagram” view in the “Notation Views” part of the “Welcome” panel. By default, a component named Mult_server has been created.
  7. We drag-and-drop a Parameter Entry from the Palette to the Parameters internal structure of the component that exists by default in the main component.
  8. We select the parameter type as the primitive uint32.
  9. In the Properties view, we change the name as initial_number_of_requests and we set its Default value to 0.
  10. We then drag-and-drop an Activity from the Palette to the main component.
  11. We name it mult_activity.
  12. We drag-and-drop an Activity Port from the Palette to the mult_activity Activity.
  13. We drag-and-drop a Component Port from the Palette to the main component limits. We select it as Provided and Workspace matches/services.servicedef.uml/svcdefs/Query_MultInMultOut.
  14. We name it multiply.
  15. We connect via the Palette connects definition the Activity port and the component Port. It creates a multiply_handler Function in the mult_activity Activity to manage the requests that will be sent to the component.
  16. We drag-and-drop another Activity Port from the Palette to the mult_activity Activity. We drag-and-drop another Component Port from the Palette to the main component limits. We select it as Provided and Workspace matches/services.servicedef.uml/svcdefs/Push_NumOfRequests. We name it processed_requests.
  17. We connect via the Palette connects definition the Activity port and the component Port. A no handler is needed for pushing elements, no handler function is created.


Here is the resulting diagram:

Papyrus-customizations-robotics-fromscratch-4.png
Server component model

We now model the client:

  1. We then select the fromscratch_components/models/components, we right-click on it, we select New Robotics model with “Create a component” as the main objective.
  2. Then, we click on “Next”, we see the parent folder as fromscratch_components/models/components, we replace the File name by mult_client.compdef.di, before clicking on “Finish”.
  3. We now click on the “Mult_client diagram” view in the “Notation Views” part of the “Welcome” panel. By default, a component named Mult_client has been created.
  4. We drag-and-drop a Parameter in the Mult_client component.
  5. We drag-and-drop two Parameter Entry from the Palette to the Parameters internal structure of the Mult_client component, one for the init_xVal and the other for the init_yVal, set to 1.
  6. We then drag-and-drop an Activity from the Palette to the main component.
  7. We name it Activity1.
  8. We drag-and-drop an Activity Port from the Palette to the Activity1 Activity.
  9. We drag-and-drop a Component Port from the Palette to the main component limits.
  10. We select it as Required and Workspace matches/services.servicedef.uml/svcdefs/Query_MultInMultOut.
  11. We name it multiply.
  12. We connect via the Palette connects definition the Activity port and the component Port.
  13. We drag-and-drop another Activity Port from the Palette to the Activity1 Activity.
  14. We drag-and-drop another Component Port from the Palette to the main component limits.
  15. We select it as Required and Workspace matches/services.servicedef.uml/svcdefs/Push_NumOfRequests.
  16. We name it processed_requests.
  17. We connect via the Palette connects definition the Activity port and the component Port. It creates a processed_requests_handler Function in the Activity1 Activity to manage the pushed messages that will be sent to the component.
  18. We then drag-and-drop a Periodic Task from the Palette to the Activity1 Activity.
  19. In the Properties view, we select the Activities tab and set its period to “500ms”.
  20. We select the Activity1 Activity, the Functions tab and add a new function named by default fNewFunction and triggers by default by a handler.
  21. We change the name to mainClientFunction and its Kind as PERIODIC. This is the (main) function of left and right components that will be executed each 500ms.


Here is the resulting diagram:

Papyrus-customizations-robotics-fromscratch-5.png
Client component model

Position with respect to the robotics domain

A component definition is a tier-3 activity, i.e. an activity that is typically done by a component developer. A component developer manages the design and configuration of components as well as their parameters. He can edit its architecture in the Architecture Model Explorer and he can specify in each component which port uses a given service.

Back to the top