One of the extremely powerful tools of graphical programming is compounding a set of modules into a single new module. Nevertheless even if this is a fully automated process, the compiler is not smart enough to generate useful documentation, nor is it able to fixate or reorder parameters. This post elaborates on how to merge a set of TiViPE modules to a new module.
Example NaoRobot2
The NaoRobot2 module is found in
Modules->TVP->Robotics->SCIS->Nao.
Please select it and double click on the NaoRobot2 module.
(a)
(b)
Figure 1: NaoRobot2 module (in red) is a compounded module that contains 5 basis modules (green).
The NaoRobot2 consists of 5 modules as illustrated in Figure 1. This module includes the “writeSharedData5D” module that is used to create a virtual loop for the states, a “showInfo” module that provides information over the states that are active and what is currently being done. This module is the robotics equivalent of the subtitling in a movie. The “SendCommand2” and “NaoRobot” modules are responsible for sending the appropriate commands to the physical robot. When these modules are running in TiViPE, the execution order is first “splitSCIS”, and when this module is ready 3 modules are executed in parallel “writeSharedData5D”, “ShowInfo”, and “SendCommand2” followed by “NaoRobot. When these modules are merged to a single one, the order is serialized. Hence, the grey connectors are used to insure that “writeSharedData5D” is the second module that is executed, and “ShowInfo” the third, followed by “SendCommand2”, and “NaoRobot”.
Let us mark the modules that need to be merged to a single one. This is done by pressing down the left button and drawing a rectangle around the modules that need to be merged. As soon as the button is released the modules are marked in green. This process is illustrated in Figure 2.
(a)
(b)
(c)
(d)
Figure 2: Marking a group of modules. (a) All icons are unmarked (b) drawing a rectangle by keeping the left mouse button pressed. (c) Resulting marked icons. This is the same as illustrated in Figure 1. (d) The merge button is pressed, see position of the mouse.
As soon as the merge button is pressed a window pops up, which looks like Figure 3. If this is the first time you need to type a useful name in the pink area behind the (M). This is a so-called Main group, eventually subgroups at different levels starting at (0) can be constructed. Most importantly a non-existing module name needs to be given at the bottom of the window. In the example the “MyNaoRobot2” is given. Note that this name is different from “NaoRobot2”, but we redo the construction of the NaoRobot2 module in the MyNaoRobot2 module.
Figure 3: Creating a new module called “MyNaoRobot2”.
Press “Ok” and the new “MyNaoRobot2” module is created in its default settings. In case we press the “Ok” button of the window illustrated in Figure 4, the newly created module will be compiled and is ready to be used.
Figure 4: Generated “MyNaoRobot2” module.
Pressing the “Ok” button will popup the so-called compile window. It is illustrated in Figure 5.
Figure 5: Compile window.
When compilation is done. Press the “Close” button. The module has been compiled and can be found under “(M) TVP – (0) Test – MyNaoRobot2” which is the same as
Modules->TVP->Test->MyNaoRobot2.
This module is still not exactly the same. The documentation is not exactly as desired. Lets edit the module by selecting
File->Module->Edit
or typing Ctrl-E. A window will pop up that is illustrated in Figure 6. Note that this window is very similar to the window for a new module.
(a)
(b)
Figure 6: Editing a module. (a) Goto desired module. (b) Left click on Module to select it.
When the desired module is selected, click on “Ok” and we are back to the same window as illustrated in Figure 4. The brief description given is not desired. By pressing Ctrl-A in the window all text is selected. Hitting backspace removes all text. Change the text for the brief description as given in Figure 7.
(a)
(b)
Figure 7: Modification of brief description. (a) Initial text. (b) Final text.
The same is done for the full description, Figure 8.
(a)
(b)
Figure 8: Modification of full description. (a) Initial text. (b) Final text.
Also for the Input, Output, Parameters, and Examples, as illustrated in Figure 9.
(a)
(b)
(c)
(d)
(e)
(f)
(g)
(h)
Figure 9: Modification of input, output, parameter description, and examples. (a, c, e, and g) Initial text. (b, d, f, and h) Final text.
The Libraries, Includes, and Routine tabloids are fixated, since they are constructed from existing routines the user cannot modify them, but can see in what order the routines are executed. The tabloids modified so far are purely used for documentation, but after compounding many routines we have caused a cascade of parameters and they are all represented in the GUI-tabloid. The GUI-tabloid could have obtained the name parameter-tabloid as well. Since, for every routine all parameters are described. The parameters as generated by TiViPE for the “NaoRobot2” module are illustrated in Figure 10. Most of the lines contain square brackets, and between these brackets the routine number is followed by the argument number. For instance [0:1] denotes the first parameter of routine number 0. In the routine tabloid, routine number 0 is the first in the list, computer scientist have a habit of starting with 0 rather than 1, which is the “splitSCIS” routine. When evaluating these numbers carefully and when familiar with the C programming language, one can make a mapping between the order the routines are executed with their respective parameters. For instance the “splitSCIS” routine contains 5 parameters, 0:1 is an input parameter of type SCIS, 0:2 is and output parameter of type DATA5D, 0:3 is a string output, 0:4 is a string output, and 0:5 is an integer typed output. This routine does not contain any internal parameters, as can be verified when clicking on the right upper rectangle of such a module in the TiViPE environment. When an input and an output of two different modules are connected, the connection is fixed. This is because in graphical programming there can be only one input connection, and that can not be modified without changing the program itself. In this case the input and output parameters are overlayed and renamed to an output connection that is fixated. For instance Output (“Output states”, “-os” DATA5D, DATA5D_INT, FIXED) [0:2, 1:2];. This line states that the second parameter of routine 0 is connected to the second parameter of routine 1. Mapping this to C code, would mean that output of “splitSCIS” forms the input for “writeSharedData5D”.
Figure 10: The GUI tabloid.
The last output parameter from the “splitSCIS” module was not connected and that means that this module is visible in “MyNaoRobot2” module by default. We don’t need this output connection. Hence we change
Output("Output status", "-ostatus", INTEGER) [0:5];
to
Output("Output status", "-ostatus", INTEGER, FIXED) [0:5];
For input parameters we can do this only if the input is OPTIONAL, in that case we can change OPTIONAL to NOTUSED.
Next we evaluate all the internal parameters:
BeginGroup(2);
String("Key", "-key", "StatesA") [1:1];
Integer("Poll", "-poll", 0, 0, INT_MAX);
EndGroup();
BeginGroup(2);
String("Key robot update", "-keyru", "NAOready") [3:2];
String("Key states", "-keyst", "StatesA") [3:3];
EndGroup();
BeginGroup(2);
String(“Key”, “-keyM0”, “NAOready”) [4:1];
String(“IP address”, “-ip”, “131.155.176.19”) [4:3];
Integer(“Port”, “-port”, 9559, 0, INT_MAX) [4:4];
EndGroup();
The reason that the tabloid is called the GUItabloid -becomes clear here. When clicking on the right upper icon of the “MyNaoRobot2” module in TiViPE the parameter window pops up, and the user will find back a one to one mapping with the given text in the tabloid. The “BeginGroup” and “EndGroup” commands are used to place the elements in a grid, such that the parameters are nicely aligned in columns.
After merging the layout might not be appropriate anymore. In the given parameter list above,
the first group of parameters are obtained from routine 1 “WriteSharedData5D”, the second group (routine 3) are from “SendCommand2” while the third group (routine 4) is from module “NaoRobot”. Let us first reorder them and remove the extra groups that are created because of the different modules:
BeginGroup(2);
Integer("Poll", "-poll", 0, 0, INT_MAX);
String("Key", "-key", "StatesA") [1:1];
String("Key states", "-keyst", "StatesA") [3:3];
String("Key robot update", "-keyru", "NAOready") [3:2];
String("Key", "-keyM0", "NAOready") [4:1];
String("IP address", "-ip", "192.155.176.19") [4:3];
Integer("Port", "-port", 9559, 0, INT_MAX) [4:4];
EndGroup();
It becomes clear that two of these parameters appear to be the same, namely 1:1 and 3:3 and also 3:2 and 4:1. This means that we can overlay these parameters which is done as follows:
BeginGroup(2);
Integer("Poll", "-poll", 0, 0, INT_MAX);
String("Key", "-key", "StatesA") [1:1, 3:3];
String("Key robot update", "-keyru", "NAOready") [3:2, 4:1];
String("IP address", "-ip", "131.155.176.19") [4:3];
Integer("Port", "-port", 9559, 0, INT_MAX) [4:4];
EndGroup();
Note that this modification is very similar to a connection that has been fixated, as described before. All necessary modifications have been made, press the “Ok” button to recompile the module. By re-selecting the module, its appearance has become the same, and also when the documentation is selected it will be the same compared to the “NaoRobot2” module.
Note that if we modify the Key from “StatesA” to “StatesB” both parameters (the first argument of routine 1 and the third argument of routine 3 change). In case the user never modifies a parameter, one can fixate any parameter by adding FIXED. For instance if the Key parameters are never modified one could change
String("Key", "-key", "StatesA") [1:1, 3:3];
to
String("Key", "-key", "StatesA", FIXED) [1:1, 3:3];
The parameter will be moved down in de GUI automatically to the set of FIXED parameters.
We have created a module that is exactly the same we can remove it from TiViPE by selecting:
File->Module->Delete
or Ctrl-D. Select the right module to be deleted as illustrated in Figure 11.
(a) 
(b)
Figure 11: Deleting a module.
Press the Ok button to delete the module, and close the window that has popped up.