This repository contains the code to control and operate a custom cable-driven robot built at GRAB laboratory.

It relies on EtherCAT network system and requires a Real Time Linux Operating System. Both robot controller and human interface are handled by the same working station, i.e. a standard PC with RT characteristic, and covered here.

Follow these instructions thoroughly to get you a copy of the project up and running on your local machine for development and testing purposes. Please contact a maintaner if you incur any trouble.

To clone this repository, open a terminal, cd to where you want this local copy to be downloaded and type the following commands:

git clone git@github.com:UNIBO-GRABLab/cable_robot.git
git submodule update --init

The second command is absolutely necessary to download the latest versions of the submodules on which this repository relies on.

This application depends on grabcommon libraries. Keeping this in mind, the user is free to build it as desired.

We provide here a Qt project file and instructions for compiling this package using QtCreator. Please note that this builing process requires a compiled version of both state_machine and grabcommon static libraries.

If not yet present on your machine, please install QtCreator together with Qt. To do so, open a terminal a type the following commands:

sudo apt-get install build-essential libgl-dev libicu-dev
sudo apt-get install qtcreator
sudo apt-get install qt5-default

Because this application relies on etherlab libraries and real-time scheduling, it needs admin access to your system at run time. To do so you can simply start your application from terminal with administrator privliges, such as:

sudo qtcreator

To avoid to open a new terminal every time you want to work on this project, we suggest to use a shortcut using gksudo:

1. Install gksudo:

sudo apt-get install gksu

2. Open Qt launcher with your preferred editor, such as:

sudo gedit /usr/share/applications/qt59creator.desktop

Be aware that your Qt .desktop file might have slightly different name. 3. In the Exec field, prepend the following command to what is already written: gksudo -k -u root . For instance, Exec=opt/qt59/bin/qtcreator %F becomes Exec=gksudo -k -u root opt/qt59/bin/qtcreator %F.

Now whenever you will click on Qt icon you will be prompted to a window asking for administrator password.

1. Open QtCreator.
2. In the Welcome side tab, in Projects group, select Open Project, browser to your local copy this repository and open cable_robot.pro.
3. Click the hammer button on the bottom left to build it and the green play button right above to run the application.

Please refer to this wiki section for more details about how to use this application.

To auto-generate an user-friendly documentation straight out of the source code, we make use of well-known software tool Doxygen. On the official website you can find all the details about how to use it, install it and build it. While we provide here a short tutorial on how to integrate it in our Qt-based framework, we leave to the user the task of reading the manual on the format to be employed when writing documentation within the code. Bear in mind that in this project we opted for JavaDoc style, so please comply with it.

First of all, you need to download the tool itself (you can skip this step if it is already installed in your machine). To do so, open a terminal and type the following commands:

sudo apt-get install doxygen doxygen-gui

That's it. Now Doxygen is installed and ready to be used.

Next, you need to setup a Doxyfile, which yields all the instructions to generate the documentation out of your code. Instead of compiling this file yourself, Doxygen provides a nice wizard to walk you throug all the necessary step: doxywizard. To start it, just type doxywizard in a terminal and a small GUI will appear. Feel free to adapt the settings to your specific need, but the minimal setup for this library should include the following:

• In Step 1, select $MYPROJECTPATH, where $MYPROJECTPATH is the absolute path to your project root directory.
• In Step 2, in the tab Wizard, select Project under Topics and do the following:
  • Fill project information, such as Project name, as desired
  • Select $MYPROJECTPATH as Source code directory and tick Scan recursively option below
  • Select $MYPROJECTPATH/doc as Destination directory (make directory if it does not exist yet)
• In Step 2, in the tab Wizard, select Output under Topics and untick LaTeX option unless desired.
• In Step 2, in the tab Expert, select HTML under Topics and tickUSE_MATHJAX option to display mathematical formulas.
• In Step 2, in the tab Expert, select Input under Topics, go to FILE_PATTERNS and remove all extensions except *.c, *.cc, *.cpp, *.c++, *.h, *.hh, *.hpp, *.h++ by selecting them and clicking the minus button. Look below for EXCLUDE_PATTERNS and add tests and doc by clicking the plus button. In the EXCLUDE list right above you should also add any build folder which is inside the source code directory. Finally add the following words to the EXCLUDE_SYMBOLS list:
  • STATE_DEFINE
  • GUARD_DEFINE
  • ENTRY_DEFINE
  • EXIT_DEFINE
• To test your configuration, in Step 2, go to tab Run and click Run doxygen button. In the integrated console you will see your documentation building up. When it is done, click on Show HTML output and you will be prompted to a web page on your favourite browser, which you can navigate on.
• Close the window. You will be asked to save the Doxyfile in the project directory. Do it as it suggests and you are done! Obviously, you can edit your configuration file with your favourite text editor in a later stage.

Assuming the code you want to document already belongs to a Qt project, open it with QtCreator and go to Projects tab. In the Build Settings, under the Build Steps section, click on Add Build Step button and select Custom Process Step. In the Command field type doxygen, while in the Arguments field you need to write the absolute path to the Doxyfile we just created, i.e. $MYPROJECTPATH/Doxyfile.

That's it! On your next build, Doxygen will parse all the files present in the project, look for documented lines within the code and generate an html file with all the information found nicely arranged. The main file you want to open is index.html, which you will find in the specified doc folder.

Note that Doxygen may generates a lots of warning, especially the first times you use it, because your code is probably not yet compliant with all the formatting rules. These warnings do not affect the performance or outcome of your application, but can hide serious ones generated because of specific user-specific errors, unrelated to documentation. Our suggestion is to lose some time at the beginning to solve them one-by-one, and add compliant comments while developing new code right away as you move forward. It is a good practise which makes life easier for you and especially for your future and present colleagues! :)

• Edoardo Idà - Initial work - edoardo.ida2@unibo.it
• Simone Comari - simone.comari2@unibo.it

• Simone Comari - simone.comari2@unibo.it