Software page

From WikIRI

back to main page of the robotics lab

At this moment the Robotics Lab Service can only provide support if you are using an Ubuntu Linux variant.

Software repositories

In order to manage the software developed at the Robotics lab, a dedicated SVN repository is created for each software driver or application. Currently, new repositories can be created in two different directories:

• drivers: This directory is intended for all low level drivers of both robots and sensors, as well as other hardware devices. In general, the software in this directory will generate a shared library that may be installed and used by other applications.
• applications: This directory is intended for higher level software which may use or not one or more of the software drivers and perform a specific task.

In order to create a new repository, it is necessary to contact the computer center (incidencia@iri.upc.edu) and request it, providing the following information:

• Directory in which to create it (one of the directories listed above).
• Name of the new repository.

All users at the robotics group can have developer access (read and write privileges) to all the repositories already created. To access them, first go to the local directory where you want to download it and execute:

> svn checkout https://devel.iri.upc.edu/labrobotica/<drivers or application directory>/<desired repository name>

There exist also an anonymous access to some of the repositories which only has read privileges. To access them,

> svn checkout https://devel.iri.upc.edu/pub/labrobotica/<drivers or application directory>/<desired repository name>

The desired repository name must coincide with one of the existing repositories. Once checked out, it is possible to add and remove files

> svn add <filename or directory> or svn remove <filename or directory>

commit new changes (only for developers) with

> svn commit

check the current status of the local repository with the remote repository for updates with

> svn status

and also update the local repository to the latest version on the server with

> svn update

Deprecated: Old (and really old) CVS repositories are still accessible. Access_to_the_software/papers_repositories

Tips

Disable cleartext storing of passwords

By default, the subversion client svn keeps a cache to store passwords so that it only asks once for each repository, and it does in plain text files.

To avoid this you should instruct the client to use a more secure schema such as gmone-keyring or kwallet.

• Edit the config file ${HOME}/.subversion/config and edit or add the following lines:

[auth]
password-stores = gnome-keyring, kwallet

• Clear any preexisting cached clear text password removing all files in the ${HOME}/.subversion/auth/svn.simple/ directory.

Project structure

The suggestions provided here are only guidelines to make the software more easily usable to all people, but they are NOT hard constraints.

By default three folders are created when a new project is created using the scripts: trunk, branches and tags. The default working copy of the project is placed in the trunk folder and the other folder are empty.

When doing changes to the project, to avoid breaking other projects that may depend on it, it is recommended to copy the current project inside the branches folder and develop and test all the changes there. To do that, execute the followinf command:

svn copy <remote repository>/trunk <remote repository>/branches/<branch name>

The remote repository is the https://haydn.upc.es/labrobotica/drivers/<repository name> and the branch name is the desired name of the branch. It is recommended to give a meaningful name to the branch so that it can be easily identified.

When the changes have been tested and are ready to be used, the branch has to be merged with the main project tree. To do that, execute the following command:

svn merge -r<trunk version>:<branch version> <remote repository>/branches/<branch name>

The trunk version is the version of the repository when the branch was created. To get this version, execute the following command:

svn log --stop-on-copy

The branch version is the last revision of the repository, and therefore of the branch. To get this version, execute the following command:

svn udpate

If there are no problems, the branch should be integrated into the trunk keeping all the revisions in between. Some times, there may be conflicts in some files between the branch and the trunk versions, that must be solved before merging the two revisions.

The provided structure for each project in the trunk folder is as follows:

• /doc: This directory must contain the documentation for the project. By default this folder contains a generic doxygen configuration file. If several output formats are selected, each them must be placed in a separate directory inside this one (/html or /latex for example). To generate an iri-style documentation, please follow the instructions here.

• /doc/images: Folder of your project documentation images. This folder is already included in the doxygen configuration file both with the generic and iri-style documentation.
• /doc/files: Recommended folder of your project documentation files, such as datasheets, etc.
• /bin: This directory must have all the executable files generated as a result of compiling the code.
• /lib: This directory must have all the shared library files generated as a result of compiling the code.
• /src: This directory must have all the source code, both header (*.h) and source (*.c or *.cpp) files. As many directories as necessary can be created inside this one to better organize the code.
• /src/examples: This directory must have the source code for all the example applications of the code. Example applications are those which shows how to use the software. As many directories as necessary can be created inside this one to better organize the code.
• /src/test: This directory must have the source code for all the test applications of the code. Test applications are those which test the correct operation of the software. As many directories as necessary can be created inside this one to better organize the code.
• /build: This directory must have all the temporary files creates when the source code is built, such as object files (*.o), etc.
• CMakeLists.txt: This file is a script that tells the cmake application what needs to be compiled and linked, and also how it should be done, in order to generate the Makefile fle. There exist one of this files for each subdirectory in the /src directory.
• ReadMe.txt This file must have information on any library dependencies of the project, as well as information on how to compile and install the code (if necessary), and a short description of all the test and example programs. This file may be written in Latex.

For some instructions and guidelines on how to create the cmake scripts (CMakeLists.txt) go here

There exist a template of a standard project with all the directory structure shown here which can be used to start new projects. Go here to get it.

Coding style

Text Style

Line weight

• 80 columns

Tabulation

• 2 spaces
• NO TABS!

Be coherent with function names

• always_with_same_style()
• dontChangeTheStyleInTheSameClass()

Coding

Dependences

• minimize use of external libraries

Class

• A driver should do just the communication with a device and receive, if its necessary, its results.
• A driver/algorithm should not do things not assigned to it like write the information into files, create folders, etc
• A driver/algorithm has to be able to work with several devices at same time (recommended get_DEVICE_id() , get_NEWEVENT_id() )
• It must not stops the program execution, this can be achieved using Threads (CThreadServer) and Events (CEventServer) ( start(), stop(), get_RESULT(), save_RESULT() )
• It has to be configurable, with attributes or a structure ( get_config(), set_config(CONF) )
• If there are shared resources they will have to be protected using Mutex (CMutex), this is very important in case your driver needs a driver_server
• Use standards such as std::string instead of char *.
• Use a debugger(ddd) better than log files
• Use init() and close() functions outside the constructor and destructor
• Use gets and sets in order to give useful pieces of information to the user
• Use exceptions to manage the errors (CException)
• Create a test program with a simple program working with the driver (DEVICE_test)
  

Documentation

• Add extended documentation for critical functions
• Add manufacturer information if this could be interesting for the user (links to datasheets, add images...)
• Add Related Pages into documentation such as: how to use the driver and device, important information (reference systems, values, units...), documentation (datasheets, pdf...)
• Use Todo Lists
• Add this information also into this wiki (uploading the datasheets and images)
  
• Add author and disclaimers