From 4e27ea5472fd1eee4413fe43bcd53d1add63a1e6 Mon Sep 17 00:00:00 2001 From: NormalParameter Date: Thu, 28 Apr 2022 14:54:53 +0200 Subject: [PATCH] User Manual --- 6.-User-Manual.md | 325 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 324 insertions(+), 1 deletion(-) diff --git a/6.-User-Manual.md b/6.-User-Manual.md index 0519ecb..b825654 100644 --- a/6.-User-Manual.md +++ b/6.-User-Manual.md @@ -1 +1,324 @@ - \ No newline at end of file + ##### Table of Contents + +* [Note] (#Note) +* [1\. Introduction](#Intro) + * [1.1 Overview](#Overview) + * [1.2 Glossar](#Glossar) +* [2\. Installation](#Installation) + * [2.1 Software requirements](#Requirements) + * [2.2 Installation process](#Installationprocess) + * [2.2.1 AutomationML Editor](#AMLEditor) + * [2.2.2 Modelling Wizard Plugin](#MLWP) +* [3\. Graphical User Interface](#GUI) + * [3.1 General Information](#GeneralInfo) + * [3.1.1 Generic Data Tab](#GenericData) + * [3.1.2 Interfaces Tab](#Interfaces) + * [3.1.3 Attachments Tab](#Attachments) + * [3.2 File Import](#FileImport) + * [3.3 File Export](#FileExport) +* [4\. Copyright](#Copyright) + +# Changelog + +| Version | Date | Author | Comment | +| ------------- |-------------|-------------|-------------| +| V0.1 | 19.03.2022 | Florian Kellermann | created | + + +*** +#Note + +Since most of the functionality has not been changed in comparison to the old version the user manual has similarities of some sorts. The main changes, as described in the SAS, SRS and CRS happened in the program now being a standalone application. + +# 1. Introduction +## 1.1 Overview +As said before the main task was to convert the plugin into a standalone application. Changes have also been made to improve the general usability of the program as described in this User Manual. + +The purpose of the user manual is to explain how to use the Modeling Wizard program. It writes that even novice users can understand how to use the standalone app. It includes instructions for installing the program, using the general interface, and importing and exporting files. +## 1.2 Glossar + +**AML** Automation mark-up language is an open standard data format for storing and exchanging plant planning data. + +**AML Editor** Abbreviation for the AutomationML-Editor + +**AMLX** AML Package + +**CAEX** Computer-Aided Engineering Exchange + +**C#** High level language often used for programming + +**GSD** General-Station-Description + +**GUI** Graphical User Interface + +**IODD** Input/Output Device Description + +**.NET** The .NET Framework is a software development and runtime environment developed by Microsoft for Microsoft Windows. + +**ZIP** archive file format + +*** + +# 2. Installation +## 2.1 Software Requirements + +### Please note that the AML Editor is a .NET application, it can only be used on Windows operating systems. There are no Linux or MacOS distributions provided yet. + + +To use our Modelling Wizard plugin, you need: + + * the AutomationML Editor (You can find the latest version of the Editor [Here](https://www.automationml.org/o.red.c/dateien.html?cat=1)) + * the ModellingWizard.dll file (Allocated in our [Repository](https://github.com/DekaAthlos/TINF19C-ModellingWizard/tree/master/EXECUTABLE)) + +## 2.2 Installation process +### 2.2.1 AutomationML Editor + +Download the latest version of the AML Editor by clicking on the link in [2.1 Software Requirements](#Requirements). + +After downloading the AMl Editor, you will receive a .zip-folder. Open it and you will see the following files: + +![.zip-folder after the download](https://user-images.githubusercontent.com/68180836/117531705-1edaeb80-afe4-11eb-8ca1-958b95a93624.png) + +Continue by starting the setup.exe. After the setup.exe is started, the AML Editor Setup Wizard will be opened. Click on "Next". + +In the next step, you have to agree the License Agreement by clicking on "I Agree", otherwise the installation can not be continued. + +Now there will be some information given by the creators, but you can go to the next step by clicking on "Next". + +To make sure you can follow this installation guide, **do not change the default installation folder**. The AML Editor will be installed under the Program Files on the Windows partition of your hard drive. Install the AML-Editor just for yourself and continue the installation. + +![image](https://user-images.githubusercontent.com/68180836/117535514-6ff3db00-aff6-11eb-92fd-674ea1faf5f8.png) + +In the next step the installation will be finished when you click on "Next". If there is a pop-up by your Windows OS, asking to make changes on a specific file on your C: folder, just click on "Yes". + +Now the installation of the AML-Editor is finished and you can close the installation windows by clicking on "Close". + +Use the windows search function and type "AutomationMLEditor". Start the program to check whether the installation was successfull or not. + +![success](https://user-images.githubusercontent.com/68180836/117532532-52b81000-afe8-11eb-8cc2-a1052acfbc18.png) + +If the application that has opened looks like this, the installation was completed successfully. + +When either no program with the name "AutomationMLEditor" can be found or the application does not open properly like shown in the picture above, try to uninstall the AML-Editor (Programs and Features -> Uninstall) and start the installation process again. + +*** + +### 2.2.2 Modelling Wizard Plugin +Before starting the installation of the Modelling Wizard Plugin, go to the installation directory of the AML-Editor (default: **C:\Program Files\AutomationML\AutomationML Editor** or with your custom installation directory) and check if there is a folder like "Plugin". If not, please create one. + +Now you have to select the "Plugin" folder in the AML-Editor Plugin Manager, otherwise the Modelling Wizard Plugin cannot be installed. Open the AML-Editor, navigate to "PlugIns" in the header bar and click on the "PlugIn-Manager". + +![image](https://user-images.githubusercontent.com/68180836/118929256-8f6afc00-b944-11eb-9f58-109e1445264a.png) + +In the PlugIn Manager, click on the gearwheel button ![image](https://user-images.githubusercontent.com/68180836/118929463-d8bb4b80-b944-11eb-8da9-0bb8136d5394.png) in the top right corner to open the settings for the manager. +Now a new PlugIn Source can be selected. For this, click on the ![image](https://user-images.githubusercontent.com/68180836/118929643-1029f800-b945-11eb-8795-8a8b70deb931.png) "add" button and a new, fillable field will open. In the "Name" field, please enter something like "PlugIn". In the "Source" field, you have to enter the the file path of the AML-Editor Plugin folder. If you followed the installation of the [AML-Editor](#AMLEditor), write in the following default path (or change the path, if you installed the AML-Editor anywhere else): + +**C:\Program Files\AutomationML\AutomationML Editor\Plugin** + +Please check the check field ![image](https://user-images.githubusercontent.com/68180836/118930900-9abf2700-b946-11eb-9533-de0537b72246.png) of the new source you just created. You can click on "OK" to confirm your entry if your new source looks like this: + +![image](https://user-images.githubusercontent.com/68180836/118930469-0eacff80-b946-11eb-8710-844df2db707b.png) + +The installation of the PlugIn folder is now finished, you can close the PlugIn Manager and the AML-Editor. + +To install the Modelling Wizard Plugin, you need to download the ModellingWizard.dll from our [Repository](https://github.com/DekaAthlos/TINF19C-ModellingWizard/tree/master/EXECUTABLE). After clicking on the link, click on the file named "ModellingWizard.dll", a new page will be loaded and you can click on the "View Raw" or "Download" button. The download will be started. + +In most cases, when the download is finished, your antivirus program or Windows Defender will give you a message that the file can be harmful or that it can do damage to your computer. You can ignore this message and save the file anyways, it is just an unusual file format that will be downloaded. + +To continue the installation, open the folder where the .dll is located or open a ![image](https://user-images.githubusercontent.com/68180836/117533614-0b348280-afee-11eb-82cf-a73aee34f8e7.png) windows explorer and go to the ![Download folder](https://user-images.githubusercontent.com/68180836/117533434-1b982d80-afed-11eb-98e1-d3ba9d352318.png) (*Downloads* Folder). + +It should look like this: + +![Files](https://user-images.githubusercontent.com/68180836/117533398-e25fbd80-afec-11eb-9914-4b2189195393.png) + +Now open a second windows explorer and use this navigation path to jump into the *Plugin* folder of the AML Editor: + +**C:\Program Files\AutomationML\AutomationML Editor\Plugin** + +When you followed the [Installation for the AML Editor](#AMLEditor) this path will open the *Plugin* folder successfully. +But if you selected another installation folder for the AML Editor, you have to search the folder by yourself. + +To add the Modelling Wizard.dll file to the AML Editor, drag and drop the .dll file from your *Downloads* folder into the *Plugin* folder. It should look like this: + +![Pluginfolder](https://user-images.githubusercontent.com/68180836/117534024-f6f18500-afef-11eb-84f6-32729286107b.png) + +When you added the .dll file like shown above, you can close your open folders. Now start the AML Editor and go to "PlugIns" in the header bar. + +![image](https://user-images.githubusercontent.com/68180836/117534380-73d12e80-aff1-11eb-89b5-cb98169d199c.png) + +Open the "PlugIn Manager" + +![image](https://user-images.githubusercontent.com/68180836/117534428-b2ff7f80-aff1-11eb-8eaa-52bc8b36f800.png) + +Proceed with the following steps: + +![image](https://user-images.githubusercontent.com/68180836/117534728-08885c00-aff3-11eb-886a-dd6ef5eca20f.png) + +1 - Click on "available" +2 - Scroll down and click on the "Modelling Wizard - owned by DHBW-Stuttart (v2.0.0.0) to select it" +3 - Click on the "install" button + +Now you can close the "PlugIn Manager" and the AML Editor to make sure that the Modelling Wizard will be installed properly. Open the AML Editor again and open "PlugIns" to check if the Modelling Wizard is installed. The installation was succesfull when it looks like this: + +![image](https://user-images.githubusercontent.com/68180836/117534902-a8de8080-aff3-11eb-8d0b-f0bbd30687fd.png) + +The Modelling Wizard can now be started. Click on the Modelling Wizard field to select it and click on "Start" to start the plugin. + +![image](https://user-images.githubusercontent.com/68180836/117534991-0bd01780-aff4-11eb-9b38-bcde41a11a1e.png) + +The plugins main interface will open and the installation process is finished. + +When you are not able to finish the installation with this guide because problems are occuring (e.g. the Modelling Wizard cannot be selected in the "PlugIn Manager"), try to delete the .dll file from the folder, download it and start the installation again. + +*** + +# 3. Graphical User Interface +![image](https://user-images.githubusercontent.com/68180836/117537035-d54bca00-affe-11eb-89d4-7106bf08a6bd.png) +## 3.1 General Information +This chapter explains how to use the user interface of the Modelling Wizard. +In the plugin, you have three different tabs that contain information. The function of each tab and its possibilites will be explained in its own subsection. + +![image](https://user-images.githubusercontent.com/68180836/117847090-55359680-b282-11eb-83e3-066281123ba7.png) + +General information of the device that will be created, is stored under the ["**Generic Data**"](#GenericData) tab. +In the ["**Interfaces**"](#Interfaces) you have the option to add interfaces to define detailed information about the device. +Under the ["**Attachments**"](#Attachments) tab, it is possible to add further attachments to the file. + +While creating a file, you have the option to add the "Vendor Name" and the "Device Name" in the header bar of the Modeling Wizard plugin. If you import a file, these fields will be filled automatically. They are synchronised with the "Manufacturer" and "Model" fields in the Attributes table under the [Generic Data tab](#GenericData), that means if you fill the fields in the header bar, they are also going to be filled in the Attributes table. + +![image](https://user-images.githubusercontent.com/68180836/118517209-501b9000-b737-11eb-9c74-9abfa31e1778.png) + +In the header bar, you can select the "Standard Libraries" dropdown button. It will display all the libraries that can be loaded into the plugin. If there is a library that you need to add more information to your device, you can select it from the dropdown and make it available in the "Role Class Library" section. + +![image](https://user-images.githubusercontent.com/68180836/118518885-e4d2bd80-b738-11eb-963f-d3fe40edb596.png) + +*** + +### 3.1.1 Generic Data Tab + +To add general information to the device, the Attributes table can be filled with information. The **red marked** fields are mandatory fields and must be filled with information. To display how it works, some dummy attributes are added to the device: + +![image](https://user-images.githubusercontent.com/68180836/118508676-aedd0b80-b72f-11eb-9ba1-bd255f462093.png) + + +Furthermore, it is possible to add **Role Class Libraries** to the Generic Information. The Role Class Libraries **will only be displayed** if you have selected the Generic Data tab. To add a Role Class Library, select the Role Class you want to add and then **drag and drop** it into the "Generic Information" table. The Generic Information table is located in the upper half of the Generic Data tab. In this case, the AdditionalDeviceDescription Class will be added to the device. + +*Please note that the drag and drop function works better if you use the right mouse button*. + +![image](https://user-images.githubusercontent.com/68180836/118511469-36c41500-b732-11eb-98c5-f99aa3c29a4b.png) + +**Generic Information table** + +![image](https://user-images.githubusercontent.com/68180836/118837263-ed57ff00-b8c4-11eb-913d-3609017581cf.png) + +To display the properties of the Role Class you just added to the device, select the Role Class in the Generic Information Table you drag and dropped it in and **double click** the new element that appears above the Attributes table. If any properties are saved, they will be displayed in the Attributes table. + +![image](https://user-images.githubusercontent.com/68180836/118512070-c7025a00-b732-11eb-85fc-9a1711b4c0a1.png) + +The Header tab of the Attributes table contains information about the Role Class that is added to the device. By adding a Role Class, the header tab will be filled with information that is stored in the certain Role Class, but you can add more information aswell. + +![image](https://user-images.githubusercontent.com/68180836/118513869-607e3b80-b734-11eb-9e4f-a156dd35f953.png) + +To delete a Role Class from your device, select the Role Class in the Generic Information table and press on the "Delete Button" that is placed on the top right side of the table. The Role Class will be deleted from the table and also from the file. + +*** +### 3.1.2 Interfaces tab +The use of the Interfaces tab strongly corresponds to the use of the Generic Data tab. Here you can add Interfaces Class Libraries to the device. The Interface Class Libraries **will only be displayed** if you are under the Interfaces tab. + +![image](https://user-images.githubusercontent.com/68180836/118515730-ee0e5b00-b735-11eb-9a1e-ca6cbfc85316.png) + +To add an Interface Class Library, follow the instructions under [3.1.1 Generic Data tab](#GenericData), they work the same way. + +*** +### 3.1.3 Attachments tab +The Attachments tab offers the possibility, to add attachments like images or PDFs to your device file. To do so, select the type of the attachment you want to add that will be displayed if you click on the the dropdown button. The following attachment types are included: + +![image](https://user-images.githubusercontent.com/68180836/118519534-80642e00-b739-11eb-9c9e-b2da56eea4b2.png) + +After selecting the type of the file you want to add, you can select a file from your computer with the "Select File" Button. If you want to select the file by giving it a certain path, e.g. the file is stored anywhere else, you can add a path in the "Add path" field. Here a file of the "Certificate" type will be attached. + +![image](https://user-images.githubusercontent.com/68180836/118520354-4d6e6a00-b73a-11eb-9f64-3c6b2aa144a1.png) + +After the file is attached, the type and the file path will be displayed in the table like you can see above. To delete an attachment, click on the "Delete" Button on the right side of the header bar of the table. +*** + +## 3.2 File Import +Like already mentioned, the Modelling Wizard plugin offers the ability to import a file and display its properties. Please note that you are only able to open files that are saved in the AML (.aml; .amlx; .xml;) file type. +To open a AML file, start the Modelling Wizard and select in the header bar bar "File" -> "Open". + +![image](https://user-images.githubusercontent.com/68180836/117537448-2c529e80-b001-11eb-878e-1c9dac5a3499.png) + +After this, a windows explorer opens where you can select a file that will be display in the Modelling Wizard. To display the file, select it and click on "Open". In this example, a .amlx file from the manufacturer "Balluff" will be displayed. + +![image](https://user-images.githubusercontent.com/68180836/117537504-a97e1380-b001-11eb-80bb-68c863f1292d.png) + +After the import of the file, the vendor name (in this case Balluff) and the device name will be displayed in the header bar of the plugin. + +![image](https://user-images.githubusercontent.com/68180836/117537913-1e524d00-b004-11eb-863a-a325c00ee9de.png) + +Other attributes are displayed in the "Attributes table" (e.g. the URL of the manufacturer) under the "Generic Data" tab. + +![image](https://user-images.githubusercontent.com/68180836/117538167-38d8f600-b005-11eb-8824-907aa55355f0.png) + +Furthermore, the interfaces and the attachments of the device that is created with the AML file can be seen in their "Interfaces" and "Attachments" tab. + +**Error Handling** +Meanwhile it is possible to import most of the AML files, nevertheless there are a few libraries that the Modelling Wizard plugin is not able to work with. If you try to import a file that contains such a library, the Modeling Wizard will put out a error message to inform you. + +## 3.3 File Export +In this section it will be shown how to save a file that is created with the Modelling Wizard plugin. The example file of [3.2 File Import](#FileImport) will be used to demonstrate how it works. If you want to create a new file, select "New" in the File dropdown button of the header bar. + +![image](https://user-images.githubusercontent.com/68180836/118528925-397b3600-b743-11eb-9345-a8ce1bc4ce95.png) + +**_Important Information_**: As already mentioned in [3.1.1 Generic Data Tab](#GenericData) following fields are mandatory fields and must be filled with information, otherwise you are not able to save a file: + +![image](https://user-images.githubusercontent.com/68180836/117690831-8f883080-b1bb-11eb-949d-f6c719048d6e.png) + + +Those fields are listed in the "Attributes" table under the "Generic Data" tab. If they are not filled when you try to safe the file, you will get an error message. + +If you want to save the file, go to the "File" button in the header bar. You will get 2 options: + +**1 - Save** +**2 - Save and Close File** + +![image](https://user-images.githubusercontent.com/68180836/117691933-bf840380-b1bc-11eb-9eea-daf37b993785.png) + +**Option 1 - Save:** Select a target location and save the file and all the data you filled in. After the save, you will be able to continue the editing of the file and add more information. Useful if you want to create temporary savings while creating a new file. + +**Option 2 - Save and Close File:** Select a target location and save the file. After saving, all information that is currently displayed in the Modelling Wizard plugin will be deleted from the fields. This option is useful when you have finished editing a file and want to create a new one. + +Please note that **all files that will be saved are automatically stored in the .amlx file type**. For this reason you are not able to select a file type by yourself while saving a file. + + +# 4. Copyright +## About the Modelling Wizard for Devices PlugIn + +The Modelling Wizard for Devices is a plugin that can be used to create or modify devices and interfaces. It can also be used to import IODD and GSDML, CAEX 2.15 and CAEX 3.0 files that will be converted to the AMLX (.aml; .amlx; .xml;) package. + +**Version 2.0.0.0** +*** +Design and Software development by + +**TINF17C DHBW Stuttgart** +and +**Master Student Raj Kumar Pulaparthi, Otto-von-Guericke University Magdeburg** +and +**TINF19C DHBW Stuttgart** +and +**TINF20C DHBW Stuttgart** +This plugin was created as a group project in the "Software Engineering" class. + +*** +**TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION** +The MIT License (MIT) +Copyright © 2021 TINF19C DHBW Stuttgart + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files ('the Software'). to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sub license, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFGRINGEMENT. IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF THE CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNENCTION WITH THE SOFTWARE OR THE USE OR THER DEALINGS IN THE SOFTWARE. +*** +**© TINF19C DHBW Stuttgart 2021** +This plugin uses third-party software for the convertions of IODD and GSDML. All rights are reserved by the corresponding copyright owner. +*** +Author: Florian Kellermann \ No newline at end of file