Latest revision as of 09:50, 29 October 2020

Service definition principle

Defining a service in Papyrus for Robotics is defining a communication mean between components. A service is indeed a way to synchronize and exchange data between components. It is a generic mechanism, i.e. it is reusable between several components and it is not component-specific.

A service definition is based on a given communication pattern and on a set of associated Communication Objects. Service definitions reference one of the 4 communication patterns identified in RobMoSys. Depending on the communication pattern, a service definition needs to reference one or more communication objects, i.e. the object(s) that are exchanged by an interaction. This is outlined in the following for each pattern:

• Push: a single "message" element
• Send: a single "message" element
• Query: a "request" message and a corresponding "reply" message
• Event: a "message", a "parameter" and a "state" object

For more details on each pattern, see [communication patterns]. A new action/coordination pattern is currently under definition with a "goal", a "response" and a "feedback" object.

A Communication Object defines the data conveyed by a given service. Communication objects and data types have both a set of typed attributes. The only difference is that communication objects can directly be referenced from service definitions. In order to avoid duplicates, the palette of the diagram only enables the creation of the different data-type variants. At any moment, a data-type can be converted into a communication object and vice versa, as shown in the following dialog:

How to edit

We can create a service definition with Papyrus for Robotics in a specific service definition model. We use the palette to create a new service definition. The tool will prompt for the different communications objects. They are either already defined in another service definition model or edited in the service definition model itself.

It is recommended to use a textual editor for editing the data types. This editor is available via the F2 short-cut or inside the property view (the latter is recommended, since the editors directly in the diagram use a constraint area).

As shown below, Papyrus offers an xtext editor provided content assist (control-space) and validation. If the validation does not pass, the editor contents is stored in an annotation awaiting corrections. We can specify attributes along with their type and a comment which becomes part of the attribute's description. In order to obtain completion assistance, we write the prefix of package containing the type (but please note that this only covers models already loaded into the resource set - use the type selection attribute to load additional registered models).

A service definition from scratch

Forewords

For service definition, component definition and system design, we provide an example as a main theme to illustrate how to define a system from scratch.

We suppose the user is familiar with the different views of Papyrus, see [Papyrus User Guide]. The purpose of this example is to develop an application (i.e. a system) compounded of 3 components that exchange data. In each chapter, a section named “<this element> from scratch” illustrates the way to use Papyrus for Robotics in order to edit the expected content of this example.

The component main replies to any request it receives and counts each time it has to process a request. There are 2 other components of the same type, right and left, that are both periodic, that read the last value of the counter of processed requests by main and that may send new requests to main. From a computation point of view, the main component multiplies 2 integers sent in the request and then increases its number of processed requests by 1. The 2 other components sends a couple (x,y) of integer values acquired via some sensors and actuates with the given computed value in return, if possible. The acquisition of data via some sensors depends on the current number of requests processed by main.

This development will be performed in 3 stages: we define the services, then the components that use the services and finally the system that uses the components and the services.

Step-by-step procedure

We launch Papyrus for Robotics:

1. We select in the Menu File “create a new Robotics project” with “Define services” as the main objective
2. We click on “Next” and choose the project’s name, for example fromscratch_services, before clicking on “Finish”.

Here is the illustrated procedure:
Project creation with Papyrus for Robotics

We now define the services that are used by the 3 components. In the “msg” Package of the “Fromscratch_services” root of the Model Explorer:

1. We create a “Data Structure Definition Diagram” by right-clicking on the package and selecting it as a New diagram.
2. We may name it “Requests I/O”. This will contain the definition of the types of inputs and output of the request under modeling.
3. From the Palette to the main editing view, we drag-and-drop a new “Comm. Object” (communication object) with multIn as name for example.
4. We drag-and-drop twice an Attribute from the Palette to the multIn communication object.
5. In the “Properties” view, we name them xval and yval and set their “Datatypes” to “uint16_t” from the “AnsiCLibrary”.
6. From the Palette to the main editing view, we drag-and-drop a new “Comm. Object” (communication object) with multOut as name for example.
7. We drag-and-drop twice an Attribute from the Palette to the multOut communication object.
8. In the “Properties” view, we name them result & validity and set their respective “Datatypes” to “uint32_t” & “bool” from the “AnsiCLibrary”. The validity boolean represents the fact that the computation of the result led to an overflow and cannot be represented in the “uint32_t” type (the result value is truncated and cannot be taken into account).

Here is the resulting diagram:

In the “msg” Package of the “Fromscratch_services” root of the Model Explorer:

1. We create a new “Data Structure Definition Diagram” by right-clicking on the package and selecting it as a New diagram.
2. We may name it “Published data”. This will contain the definition of the type of data publish under modeling.
3. From the Palette to the main editing view, we drag-and-drop a new “Comm. Object” (communication object) with NumOfRequests as name for example.
4. We drag-and-drop an Attribute from the Palette to the NumOfRequests communication object.
5. In the “Properties” view, we name it value and set its “Datatypes” to “uint32_t” from the “AnsiCLibrary”.

Here is the resulting diagram:

We now double-click on the “Fromscratch_services diagram” in the Model Explorer. The view to edit them is then opened:

1. We drag-and-drop a “Query (Svc. definition)” from the Palette to the main editing view.
2. We “Choose CO for request” (CO means Communication Object) as Model matches/msg/multIn and “Choose CO for request” as Model matches/msg/multOut. The query is automatically named based on the 2 communication object names but we may rename it as QueryMultItMultOut.
3. We drag-and-drop a “Push (Svc. definition)” from the Palette to the main editing view. We “Choose CO for message” as Model matches/msg/NumOfRequests. It is named Push_NumOfRequests.

We have defined the 2 services that will be used by the components to communicate:

1. In the Model Explorer, we unfold the QueryMultItMultOut service definition and drag-and-drop the Template Binding from the Model Explorer to the main editing view.
2. In the Model Explorer, we unfold the Push_NumOfRequests service definition and drag-and-drop the Template Binding from the Model Explorer to the main editing view.

Here is the resulting diagram:

Here is the complete illustrated procedure:
Service definition with Papyrus for Robotics

Position with respect to the robotics domain

A service definition is a tier-2 activity, i.e. an activity that is typically done by a domain expert. The objective is to define common service definitions usable across several projects and service definitions. These service definitions are typically structured in specific robotics domains such as mapping, planning, localization.

If ROS is targeted, the ROS message and service definitions that are shipped with a distribution are a de-facto standardization of these service definitions and available in Papyrus for Robotics as a set model libraries. However, it is sometimes necessary to define new service definitions. In case of ROS2, service definitions are mapped to the ROS2 counterpart:

• Push and Send: .msg file
• Query: .srv file

Please note, the contents of a communication object appears in the generated message file, not the object itself. For instance, in case of a Query, the CommunicationObject "multIn" does not appear in the QueryMultInMultOut.srv file, but its attributes (xval,yval), as shown below:

# query pattern - request
# attributes of request multIn
uint16 xval
uint16 yval
---
# attributes of response multOut
uint32 result
bool validity