# Graphical User Interface for SMACHA

## Overview

After launching the GUI the window will look as follows:

![Overview of the SMACHA GUI](smacha_gui_overview.png "Overview of the SMACHA GUI")

The GUI is divided into three parts. First, on the left side there is the block list and general functions. In the middle there is the block placement grid and on the right side there is the block parameter menu.

1.  [The block list](#the-block-list): Here, all loaded blocks are shown. They are either loaded from a local folder or from the SMACHA server. Double click adds a block to the block grid.
2.  [General functions](#general-functions): Selected containers can be deleted, SMACHA script generated, the workspace can be saved/loaded and or the application can be terminated.
3.  [Block grid](#block-grid): Any block from the block list can be added here by double clicking it. Selecting one block opens the parameter menu on the right side.
4.  [Sequence starters:](#sequence-starters) Any sequence must start at either the `Robot0Start` or `Robot1Start` block.
5.  [Blocks:](#blocks) A selected block. Selection opens the parameter menu on the right. Pressing `<Ctrl>` allows the selection of multiple blocks. This opens the container menu instead of the parameter menu on the right side. Right click on a block removes the block and any of its connections.
6.  [Parameter/Container menu](#parameter-container-menu) Parameter menu or container menu is shown here.

### The block list

This list shows all blocks, where one block resembles one SMACHA state. Double click adds the block to the [block grid](#block-grid). The ROS launch file located in `src/smacha_gui/launch/gui.launch` sets the option from where the blocks are loaded.

If the SMACHA server is set to `/smacha/templates` as in the following example

```xml
<arg name="path_smachaservertemplate" default="/smacha/templates"/>
```

blocks will be loaded from there. Set it to an empty value, to ignore the server:

```xml
<arg name="path_smachaservertemplate" default=""/>
```

In this case, blocks will be loaded from the local hard drive. The GUI tries to locate all blocks in the local block folder:

```xml
<arg name="path_blocks" default="$(find smacha_gui)/blocks.conf"/>
```

To load blocks from the server and the local folder, please define the SMACHA server as shown in the first example and add the blocks to the variable `path_blocks_alwaysload`:

```xml
<arg name="path_blocks_alwaysload" default="[Robot0Start.conf, Robot1Start.conf]"/>
```

In this example, the blocks `Robot0Start` and `Robot1Start` are always loaded. They are the blocks, which define the start points of any sequence.

### General functions

The buttons include:
*  Delete Container: This button will remove a container from the block list. First, select the container in the list. Afterwards, this button will remove the container.
*  Generate Code: This button will create SMACHA script based on the block sequences.
*  Save: This will store the workspace to a user defined file.
*  Load: This will load the workspace from a user defined file.
*  Quit: This will terminate the application.

### Block grid

A new button is always placed on the first empty cell on the grid. The grid has a fixed size of 4x19 cells. Cells can be moved freely on the grid.

### Sequence starters

Any SMACHA state sequence starts at either `Robot0Start` or `Robot1Start`. Blocks, which are not connected to a sequence starting from any of those two blocks are ignored during SMACHA script generation. The blocks are loaded from the files `blocks.conf/Robot0Start.conf` and `blocks.conf/Robot1Start.conf`.

If one of the sequence starters is removed from the grid, it can be re-added by double clicking on it in the block menu. If multiple Starters for the same robot are present on the workspace, the most upper left is chosen.

### Blocks

Blocks can be added to the [block grid](#block-grid) by double clicking an entry from the [block list](#the-block-list). Right click will remove a block from the grid. Left click will open a parameter menu on the right side.

Pressing `<Ctrl>` allows to select multiple blocks. This will open the container menu on the right side, which allows to combine the selected blocks to a container.

One block may have multiple outputs to allow branching, but must have only one input. A `Data` connection allows to transfer results from one block to another.

### Parameter/Container menu

Selecting one block opens the parameter menu on the right side. Here, detailed parameters of the SMACHA state can be set. Additionally, there is a short help text at the bottom.

If multiple blocks are selected, the container menu is displayed. A short, descriptive container's name can be entered. The button `Save` will store the container in the folder `path_blocks` as defined in the launch file `src/smacha_gui/launch/gui.launch`:

```xml
<arg name="path_blocks" default="$(find smacha_gui)/blocks.conf"/>
```

## Mandatory ROS services

The GUI depends on several ROS services.

### roscore

The roscore can be started via

```bash
roscore
```

and opens a ROS server.

### SMACHA server

The SMACHA server can be started via

```bash
roslaunch industrial_solutions reconcell_smacha_server.launch
```

and it is used to load SMACHA templates, which act as blocks, and to create SMACHA script.

### Mongo Database

The mongo database can started via

```bash
roslaunch mongodb_store mongodb_store.launch
```

and it is used to load additional block parameters.

### rosapi

The rosapi can started via

```bash
rosrun rosapi rosapi_node
```

and it is used to load a list of ROS services and their corresponding service parameters.

## Adapting the launch file

An example launch file is as follows:

```xml
<launch>
  <!-- Arguments -->

  <!-- Template Folder -->
  <!-- Path to folder containing blocks*.conf files on hard drive. This folder must always exist to store container blocks. -->
  <arg name="path_blocks" default="$(find smacha_gui)/blocks.conf"/>


  <!-- This templates will always be loaded from file. They are searched for in path_blocks -->
  <!-- <arg name="path_blocks_alwaysload" default="[Robot0Start.conf, Robot1Start.conf, ServiceState.conf]"/> -->
  <arg name="path_blocks_alwaysload" default="[Robot0Start.conf, Robot1Start.conf]"/>


  <!-- Path to SMACHA Server. If this variable is set, the here given SMACHA Server is used to load templates. Please mind that the gui templates contain additional information and are not the standard SMACHA templates. -->
  <!-- <arg name="path_smachaservertemplate" default="/smacha/templates"/> -->
  <!-- <arg name="path_smachaservertemplate" default=""/> -->
  <arg name="path_smachaservertemplate" default="/smacha/templates"/>


  <!-- Path to SMACHA Generate Server. -->
  <!-- <arg name="path_smachagenerategenerate" default="/smacha/generate"/> -->
  <arg name="path_smachaservergenerate" default="/smacha/generate"/>


  <!-- Launch the dynamic_script_generate_service_example node -->
  <node pkg="smacha_gui" name="smacha_gui" type="smacha_gui_node" output="screen">

    <!-- Parameters -->

    <!-- Local template folder -->
    <param name="path_blocks" value="$(arg path_blocks)"/>

    <!-- SMACHA Server Templates -->
    <param name="path_smachaservertemplate" value="$(arg path_smachaservertemplate)"/>

    <!-- SMACHA Server Generate -->
    <param name="path_smachaservergenerate" value="$(arg path_smachaservergenerate)"/>

    <!-- Local template always load list -->
    <param name="path_blocks_alwaysload" value="$(arg path_blocks_alwaysload)"/>

  </node>

</launch>
```

### path_blocks

This variable holds the path on the local hard drive to

1.  Load (if the SMACHA server is not set, see below) blocks.
2.  Store containers.
3.  Load blocks from the always-load list (see below).

### path_blocks_alwaysload

Files listed in this variable must exist in the folder defined by `path_blocks`. They are always loaded and diplayed, regardless of settings of the SMACHA server.

### path_smachaservertemplate

This variable points to the ROS SMACHA template service. If it is set, templates are loaded from the server, otherwise from `path_blocks`.

### path_smachaservergenerate

This variable points to the SMACHA generate service. It is used to create SMACHA script from SMACHA templates.