From 56b1ad57a022885988716fd9344fbc31713d94ae Mon Sep 17 00:00:00 2001 From: SofiaFaraci Date: Thu, 7 Nov 2024 11:09:25 +0100 Subject: [PATCH 1/4] edit path for API Signed-off-by: SofiaFaraci --- docs/source/Doxyfile.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/Doxyfile.in b/docs/source/Doxyfile.in index fe634f5..a3e934f 100644 --- a/docs/source/Doxyfile.in +++ b/docs/source/Doxyfile.in @@ -864,7 +864,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../code/include +INPUT = ../../include # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses From a45dc2d154ae5a1675fe968d5392ec8ac09a595d Mon Sep 17 00:00:00 2001 From: SofiaFaraci Date: Thu, 7 Nov 2024 14:45:58 +0100 Subject: [PATCH 2/4] mv specification folder and template skill Signed-off-by: SofiaFaraci --- .../skills/template_skill => template_skill}/CMakeLists.txt | 0 .../template_skill => template_skill}/include/TemplateSkill.h | 0 .../include/TemplateSkillDataModel.h | 0 {templates/skills/template_skill => template_skill}/package.xml | 0 .../template_skill => template_skill}/src/TemplateSkill.cpp | 0 .../src/TemplateSkillDataModel.cpp | 0 {templates/skills/template_skill => template_skill}/src/main.cpp | 0 {templates => tutorials}/specifications/full-model.xml | 0 {templates => tutorials}/specifications/interfaces.xml | 0 9 files changed, 0 insertions(+), 0 deletions(-) rename {templates/skills/template_skill => template_skill}/CMakeLists.txt (100%) rename {templates/skills/template_skill => template_skill}/include/TemplateSkill.h (100%) rename {templates/skills/template_skill => template_skill}/include/TemplateSkillDataModel.h (100%) rename {templates/skills/template_skill => template_skill}/package.xml (100%) rename {templates/skills/template_skill => template_skill}/src/TemplateSkill.cpp (100%) rename {templates/skills/template_skill => template_skill}/src/TemplateSkillDataModel.cpp (100%) rename {templates/skills/template_skill => template_skill}/src/main.cpp (100%) rename {templates => tutorials}/specifications/full-model.xml (100%) rename {templates => tutorials}/specifications/interfaces.xml (100%) diff --git a/templates/skills/template_skill/CMakeLists.txt b/template_skill/CMakeLists.txt similarity index 100% rename from templates/skills/template_skill/CMakeLists.txt rename to template_skill/CMakeLists.txt diff --git a/templates/skills/template_skill/include/TemplateSkill.h b/template_skill/include/TemplateSkill.h similarity index 100% rename from templates/skills/template_skill/include/TemplateSkill.h rename to template_skill/include/TemplateSkill.h diff --git a/templates/skills/template_skill/include/TemplateSkillDataModel.h b/template_skill/include/TemplateSkillDataModel.h similarity index 100% rename from templates/skills/template_skill/include/TemplateSkillDataModel.h rename to template_skill/include/TemplateSkillDataModel.h diff --git a/templates/skills/template_skill/package.xml b/template_skill/package.xml similarity index 100% rename from templates/skills/template_skill/package.xml rename to template_skill/package.xml diff --git a/templates/skills/template_skill/src/TemplateSkill.cpp b/template_skill/src/TemplateSkill.cpp similarity index 100% rename from templates/skills/template_skill/src/TemplateSkill.cpp rename to template_skill/src/TemplateSkill.cpp diff --git a/templates/skills/template_skill/src/TemplateSkillDataModel.cpp b/template_skill/src/TemplateSkillDataModel.cpp similarity index 100% rename from templates/skills/template_skill/src/TemplateSkillDataModel.cpp rename to template_skill/src/TemplateSkillDataModel.cpp diff --git a/templates/skills/template_skill/src/main.cpp b/template_skill/src/main.cpp similarity index 100% rename from templates/skills/template_skill/src/main.cpp rename to template_skill/src/main.cpp diff --git a/templates/specifications/full-model.xml b/tutorials/specifications/full-model.xml similarity index 100% rename from templates/specifications/full-model.xml rename to tutorials/specifications/full-model.xml diff --git a/templates/specifications/interfaces.xml b/tutorials/specifications/interfaces.xml similarity index 100% rename from templates/specifications/interfaces.xml rename to tutorials/specifications/interfaces.xml From bcc85bb563441e6a664ea2880d4c5f254fb12627 Mon Sep 17 00:00:00 2001 From: SofiaFaraci Date: Thu, 7 Nov 2024 14:46:35 +0100 Subject: [PATCH 3/4] add tutorial and edit description Signed-off-by: SofiaFaraci --- README.md | 10 +++--- docs/source/index.rst | 7 ++++- docs/source/tutorials.rst | 66 ++++++++++++++++++++++++++++++++++++++- 3 files changed, 76 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 7df831e..aedfbc7 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ git clone https://github.com/convince-project/model2code.git cd model2code mkdir build cd build -cmake ../code +cmake .. make install ``` @@ -40,17 +40,17 @@ model2code --input_filename "input_model.scxml" --model_filename "project_model_ ``` replace `input_model.scxml`, `project_model_definition.scxml`, `interface_definition.scxml`, `path/to/output/directory` and `path/to/template_skill/directory` with your needs. -By default the `path/to/output/directory` is set to the location of `input_model.scxml`, and `path/to/template_skill/directory` is set to the 'templates/skills/template_skill' directory of this repository. +By default the `path/to/output/directory` is set to the location of `input_model.scxml`, and `path/to/template_skill/directory` is set to the 'template_skill' directory of this repository. -Example XML files with the required structure for defining the project's model and interfaces are available in the `template/specifications` folder. +Example XML files with the required structure for defining the project's model and interfaces are available in the `tutorials/specifications` folder. ## Run examples To run an example of MODEL2CODE go to the main directory and run the following commands: Example 1: ``` -model2code --input_filename "tutorials/skills/first_tutorial_skill/src/FirstTutorialSkill.scxml" --model_filename "templates/specifications/full-model.xml" --interface_filename "templates/specifications/interfaces.xml" --output_path "tutorials/skills/first_tutorial_skill" +model2code --input_filename "tutorials/skills/first_tutorial_skill/src/FirstTutorialSkill.scxml" --model_filename "tutorials/specifications/full-model.xml" --interface_filename "tutorials/specifications/interfaces.xml" --output_path "tutorials/skills/first_tutorial_skill" ``` Example 2: ``` -model2code --input_filename "tutorials/skills/second_tutorial_skill/src/SecondTutorialSkill.scxml" --model_filename "templates/specifications/full-model.xml" --interface_filename "templates/specifications/interfaces.xml" +model2code --input_filename "tutorials/skills/second_tutorial_skill/src/SecondTutorialSkill.scxml" --model_filename "tutorials/specifications/full-model.xml" --interface_filename "tutorials/specifications/interfaces.xml" ``` \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index a9c6ae7..4febf8f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,6 +2,10 @@ CONVINCE model2code Documentation ================================== The model2code tool is developed as part of the CONVINCE project and is used to generate skill-level code from the high-level SCXML model of a skill. +Model2code can be used when the SCXML model representing the state machine of the skill is executed using an SCXML compiler. +To handle interfacing between the skill and the rest of the system, there is the need to write the corresponding code. +Model2code allows to generate the code for the skill, based on a given template. Allowing the user to focus on the high-level design of the system. + Program inputs: - An SCXML model that describes the behavior of the skill, @@ -14,6 +18,7 @@ Program outputs: - A C++ file containing skill code. - A header file declaring the skill. - A main C++ file that includes the main function of the skill. +- An SCXML standard file containing the compilable SCXML code of the skill. - A package.xml file with information about the ROS package. - A CMakeLists.txt file that incorporates the generated files. @@ -28,7 +33,7 @@ By default, the program generates the code in the same directory as the SCXML fi Additionally, the program uses files from the ``templates`` directory by default to generate the code, but you can specify a different directory with the ``--templates_path`` parameter. -The generated skills are based on a behavior tree structure. Skills defined as conditions will have a ROS2 tick service, while skills defined as actions will have both tick and halt services. +The generated skills are based on a behavior tree structure. Skills corresponding to condition nodes will have a ROS2 tick service, while skills corresponding to action nodes will have both tick and halt services. Contents ---------- diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 94693a8..c44886d 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -1,3 +1,67 @@ Tutorials ========= -To see the tutorial please visit the `model2code repository `_. \ No newline at end of file + +This section provides a tutorial on the model2code tool and how to use it to generate skill-level code from the high-level SCXML model of a skill. + +The output code is a ROS package that can be compiled and run on a ROS2 system, that handles the SCXML events and translate them into ROS2 service calls or responses. + +Prerequisites +-------------- +MODEL2CODE has been tested on Ubuntu 22.04 with Python 3.10.12. + +Before you can use the model2code tool, you need to follow the dependency installation and compiling steps in the model2code repository `README `_. + +Code generation guide +-------------------------------------------- + +Input and Output Models +``````````````` +The main input is an SCXML model, extended with ROS-specific features, that describes the behavior of the skill. Visit the `(ROS) SCXML Model Implementation `_ description page for more information on how to create an SCXML model of a ROS node. +The required inputs are also the files defining the system model and interfaces. The `full-model.xml `_ file contains a list of the components and specifies their interfaces, which are described in the `interfaces.xml `_ file. +The output is a ROS2 package containing the generated code. The package includes the following files: a standard SCXML file, C++ source and header files, a main C++ file, a package.xml file, and a CMakeLists.txt file. The templates for the generated files are located in the `templates `_ folder. + +The `tutorial_skills `_ are written for a system based on a behavior tree structure. The leaf nodes of the behavior tree are conditions or actions handled by plugins that propagate the tick from the behavior tree to the skills. +Skills corresponding to condition nodes will have a ROS2 tick service, while skills corresponding to action nodes will have both tick and halt services. Skills can interface with components through ROS2 services and topics. +The interface of the 'TemplateComponent' is the 'template_interfaces', which includes two functions 'Function1' and 'Function2', respectively a sample service and a topic. + +Parameters +``````````````` +To run the model2code use the following parameters: + - `--input_filename` (required): The path to the SCXML file that describes the behavior of the skill. + - `--model_filename` (required): The path to the XML file that describes the full model of the program. + - `--interface_filename` (required): The path to the XML file that describes the interfaces used. + - `--template_path`: The path to the directory containing the templates for the files to be generated. By default, the program uses the `templates` directory. + - `--output_path`: The path to the directory where the generated files will be placed. By default, the program generates the code in the same directory as the SCXML file specified by the `--input_filename` parameter. + +First example +``````````````` +The `first_tutorial_skill `_ is a simple skill corresponding to an action node of the behavior tree. +It provides ROS2 services for tick and halt, and it is a client for the 'Function1' service provided by the 'TemplateComponent'. +The model is composed of two states. In the 'idle' state, when the skill receives a tick request it sends a request to the 'Function1' service and goes to the 'start' state. In the 'start' state it waits for the response from the 'Function1' service and eventually responds to the tick request. In both states when the skill receives a halt request it responds right away. + +To generate the code for this skill, move to the model2code folder and run the following command: + +.. code-block:: bash + + model2code --input_filename "tutorials/skills/first_tutorial_skill/src/FirstTutorialSkill.scxml" --model_filename "tutorials/specifications/full-model.xml" --interface_filename "tutorials/specifications/interfaces.xml" --output_path "tutorials/skills/first_tutorial_skill" + +The generated code will be placed in the `tutorials/skills/first_tutorial_skill` folder. +The 'FirstTutorialSkillSM.scxml' file is the translation of the input SCXML model in standard SCXML, so that it is runnable with any SCXML compiler. +The 'FirstTutorialSkill.cpp' and 'FirstTutorialSkill.h' files contain the C++ code of the skill that handles the SCXML events and ROS2 communication. +The 'main.cpp' file contains the main function of the skill. +The CMakeLists.txt file incorporates the generated files. +The package.xml file with information about the ROS package and the inclusion of the 'template_interfaces' package as a dependency. + + +Second example +``````````````` +The `second_tutorial_skill `_ corresponds to a condition node of the behavior tree, therefore it does not provide a halt service. +It provides ROS2 services for tick, and is a subscriber for the 'Function2' topic provided by the 'TemplateComponent'. + +To generate the code for this skill, move to the model2code folder and run the following command: + +.. code-block:: bash + + model2code --input_filename "tutorials/skills/second_tutorial_skill/src/SecondTutorialSkill.scxml" --model_filename "tutorials/specifications/full-model.xml" --interface_filename "tutorials/specifications/interfaces.xml" --output_path "tutorials/skills/second_tutorial_skill" + +The generated code will be placed in the `tutorials/skills/second_tutorial_skill` folder. The structure of generated files follows that of the first example, with the only difference being that 'SecondTutorialSkill.cpp' omits the halt service and includes a subscriber for 'Function2'. \ No newline at end of file From ae0a1790310591296fef7b45aa703ef33e581cb5 Mon Sep 17 00:00:00 2001 From: SofiaFaraci Date: Thu, 7 Nov 2024 14:46:56 +0100 Subject: [PATCH 4/4] edit template folder path Signed-off-by: SofiaFaraci --- include/Data.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/Data.h b/include/Data.h index 9b38a8f..5ddfce1 100644 --- a/include/Data.h +++ b/include/Data.h @@ -18,7 +18,7 @@ #define modelFilePath "./templates/specifications/full-model.xml" #define interfaceFilePath "./templates/specifications/interfaces.xml" -#define templateFilePath "./templates/skills/template_skill/" +#define templateFilePath "./template_skill/" #define cppTemplateFileRelativePath "/src/TemplateSkill.cpp" #define hTemplateFileRelativePath "/include/TemplateSkill.h" #define cppDataModelTemplateFileRelativePath "/src/TemplateSkillDataModel.cpp"