|
|
|
[[getting_started]]
|
|
|
|
== Getting Started
|
|
|
|
|
|
|
|
The Papyrus for Robotics customizations supports the creations of models that are compliant with the https://www.robmosys.eu[RobMoSys] approach.
|
|
|
|
|
|
|
|
In this section, we assume that you've already downloaded and installed Papyrus for Robotics either via its update-site or an RCP available on https://www.eclipse.org/papyrus/components/robotics/[eclipse.org]. We will walk through an example that is available once Papyrus for Robotics is installed. In order to open the example, click _New->Example_, select _Robotic examples_ in the category _Papyrus examples_ and then choose the _RobMoSys_ example in the wizard.
|
|
|
|
|
|
|
|
image:figs/diy-runexample.png[DIY example, 950]
|
|
|
|
|
|
|
|
== Introduction
|
|
|
|
|
|
|
|
This example shows how Papyrus4Robotics supports the https://robmosys.eu/wiki/composition:service-based-composition:start[service-based approach for the composition of software components].
|
|
|
|
|
|
|
|
https://robmosys.eu/wiki/general_principles:ecosystem:start[Composition in an Ecosystem organized in tiers] is the RobMoSys for system integration.
|
|
|
|
The next sections discuss how tier 2 and tier 3 participants use Papyrus4Robotics to model a simple service-based composition of two components that publish and consume a simple map, respectively.
|
|
|
|
|
|
|
|
Although the process implies multiple tiers and stakeholders, the provided example is stored in a single model to keep things simple. For real projects, the different aspects would be stored in multiple models to facilitate collaboration.
|
|
|
|
The illustration below corresponds to the role descriptions, as taken from the RobMoSys wiki.
|
|
|
|
|
|
|
|
image:figs/5ee339a0319fdd950261bb8b116e14d8/Service-based-composition-approach.png[Service based composition approach, 900] +
|
|
|
|
Roles and interactions in a service-based composition of software components, see also https://robmosys.eu/wiki/start[RobMoSys Wiki]
|
|
|
|
|
|
|
|
|
|
|
|
[[domain_expert_tier_2]]
|
|
|
|
== Domain Expert (Tier 2)
|
|
|
|
|
|
|
|
Tier 2 are robotics experts who define a //complete// characterization of services in robotics domains, e.g., mapping, planning, localization, etc. Tier 2 structures each robotics domain by creating domain-models that cover a number of aspects, including data structures and communication semantics. https://robmosys.eu/wiki/general_principles:ecosystem:roles:service_designer[Service designers] are the domain experts on Tier 2 that design individual service definitions for use by Tier 3.
|
|
|
|
|
|
|
|
The picture below shows a portion of data structures defined for the mapping domain in this example.
|
|
|
|
|
|
|
|
image:figs/SimpleExampleDataTypes.png[Simple example data types, 800] +
|
|
|
|
Model of data types for the robotic mapping domain
|
|
|
|
|
|
|
|
Papyrus4Robotics leverages concepts from https://robmosys.eu/wiki/https://www.omg.org/spec/MARTE/%7COMG's[MARTE]] NFP and VSL profiles to comply with RobMoSys' specifications on digital data representation. Built-in type definitions can be imported from the _BasicNFP_Types_ MARTE library and specialized for a specific domain by using a dedicated palette (right side of the picture). Leveraging on MARTE, **Papyrus4Robotics supports physical units descriptions** to formally define unambiguous semantics of units of measurements in data types.
|
|
|
|
|
|
|
|
Not all data types are communication objects. 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.
|
|
|
|
|
|
|
|
image:figs/ToggleCommunicationObject.png[Toggle between data-type and communication object] +
|
|
|
|
Toggle between data-type and communication object
|
|
|
|
|
|
|
|
Once the communicated data structures (Communication Objects, identified with the _CO_ icon on the top left corner) are defined, the communication pattern usage can be formalized. The next picture shows the model that describes the _MappingSdef_ service. In this example, _MappingSdef_ _uses_ the _Push_ pattern and selects the _Map_ data type as communicated data structure. Please note that it is possible to toggle between ``normal'' data types and communication objects via the context menu.
|
|
|
|
|
|
|
|
|
|
|
|
image:figs/SimpleExampleServiceDef.png[Example service definition] +
|
|
|
|
Model of service definition for the robotic mapping domain}}
|
|
|
|
|
|
|
|
[[component_suppliers_tier_3]]
|
|
|
|
== Component Suppliers (Tier 3)
|
|
|
|
|
|
|
|
Component suppliers at Tier 3 provide models of software component definitions.
|
|
|
|
|
|
|
|
[[periodic_publisher]]
|
|
|
|
=== Periodic publisher
|
|
|
|
|
|
|
|
The model below shows a component that publishers a Map periodically.
|
|
|
|
|
|
|
|
image:Papyrus-customizations-robotics-SimpleExampleComponentDef.png[Papyrus-customizations-robotics-SimpleExampleComponentDef.png,title="fig:Papyrus-customizations-robotics-SimpleExampleComponentDef.png"] +
|
|
|
|
Model of a publisher that is fully compliant to MappingSdef
|
|
|
|
|
|
|
|
The example focuses on the modeling of a single component port (_pMap_) providing the mapping service.
|
|
|
|
|
|
|
|
_PeriodicPublisher_ contains one _Parameter_ structure, that represents a set of parameters that make the component configurable for reuse in different scenarios by the system builder or even at run-time. The _Parameter_ structure content is visualized in the model editor by selecting the _Paramter_ icon and the _Parameters Settings_ tab in the property view (see below). The selected parameter block has been moved in the screenshot below to keep image dimensions relatively small.
|
|
|
|
|
|
|
|
image:figs/SimpleExampleParameters.png[Simple Example Paramters] +
|
|
|
|
Visualization of parameter set of PeriodicPublisher
|
|
|
|
|
|
|
|
In this simple example, _PeriodicPublisher_ has 2 configurable parameters with built-in types. However composite value specifications (collection, tuple, choice, etc.) can be specified as well, using the MARTE VSL syntax.
|
|
|
|
|
|
|
|
_PeriodicPublisher_ defines one activity (it could define more), which is a OS-agnostic representation of a thread. Activities provide wrappers for functions (algorithms). Activities do have set of parameters for configuration (e.g., inter-arrival range, that is max and min activation frequencies). Similarly to component parameters, activity paramters can be viewed and set through the _Parameters Settings_ tab in the property view.
|
|
|
|
|
|
|
|
=== Subscriber
|
|
|
|
|
|
|
|
The model is a component that subscribes to Map data delivered by the periodic publisher, not shown here.
|
|
|
|
|
|
|
|
The example has a single port _rMap_ that **requires** (consumes, in case of Push) a fully compliant implementation of _MappingSdef_.
|
|
|
|
|
|
|
|
[[system_builder_tier_3]]
|
|
|
|
== System Builder (Tier 3)
|
|
|
|
|
|
|
|
System builders instantiate component definitions to provide a platform-independent specification of a software system. The model below shows the instantiation and connection of one instance of _PeriodicPublisher_ and one instance of _Subscriber_.
|
|
|
|
|
|
|
|
image:figs/SimpleExampleAssembly.png[Simple example assembly, 600] +
|
|
|
|
Model of system component architecture
|
|
|
|
|
|
|
|
It is now assumed that the publisher component instance must work outdoor. The default configuration of _PeriodicPublisher_ component definition was indoor, so the component instance _m_ must be re-configured by the system builder.
|
|
|
|
|
|
|
|
For a component instance the parameter set is accessible by clicking on the instance itself and selecting the _Parameters Settings_ tab in the property view. The next picture shows the value of _indoor_ parameter is set to _false_. Yellow highlighting visually enforces the message that the parameter value is now different from the default one.
|
|
|
|
|
|
|
|
image:figs/SimpleExampleParametersInstance.png[Simple parameter instance] +
|
|
|
|
Re-Configuration of PeriodicPublisher Instance
|
|
|
|
|
|
|
|
== Conclusions
|
|
|
|
|
|
|
|
This example shows a structural model in the context of composition of software components. It shows how different tiers contribute models to achieve composition of software components, using service-definitions as central architectural element for it. Then it focuses on one instance of the publisher component and shows a simple reconfiguration of one of its parameters. |
