Simple and Low-Cost System for Relative Localization

This page is dedicated to present software for the relative localization system based on Gumstix Caspa Camera Module presented in [1]. Additional information about the roundel's detection and localization algorithm and its deployment in various scenarios can be found at http://purl.org/robotics/thales. Note that:

The software is for noncommercial use only. You may not use this work for commercial purposes.
For any reuse or distribution, you must make clear to others the license terms of this work.
If you want to use it in your projects, please cite [1].
Also, please send an email confirming, that you use it. Your email address will not be used for any purposes outside registering users of our software.
Any of these conditions can be waived if you obtain written permission from the copyright holder.

The software support can be divided into four parts:

A supporting library for the building tracker that is called imr-h.lite-common.
The tracker and tracker client applications.
ROS node that encapsulate the tracker protocol and provides information about the tracked pattern to the ROS
The Gumstix Overo environment (installation)

The sources of the library, tracker software and ROS nodes are available in the tarball. The sources are easy to compile by the provided Makefiles (FreeBSD and Linux Ubuntu have been tested). Further information can be found in the provided tarball and bellow. In a case of any problems, feel free to use the contact for additional information. This page is intended to support and share experience on usage of the developed software for relative localization and thus this page is a subject of change.

[1] Jan Faigl, Tomáš Krajník, Jan Chudoba, Libor Přeučil, Martin Saska: Low-Cost Embedded System for Relative Localization in Robotic Swarms, ICRA 2013, pp. 985-990. bibtex

Supporting library

The library provides some instant functions for an easier parsing command line arguments (using boost_program_options) and logging (based on log4cxx). All the used function in the tracker are not mandatory; however, the provide a greater flexibility to set the program options. The library depends on a couple of libraries that are defined in the provided Mk/libs.mk and can be adjusted appropriately if necessary. The adjustment can be particularly useful for cross compiling the sources for deploying the software, e.g., on the Gumstix Overo boards.

Tracker software

The tracker software is split into two parts. The server, which is intended to run on-board the Gumstix Overo board, capture images from the attached Gumstix Caspa camera module, performs the detection of pattern and estimate the relative position of the detected pattern to the camera. The server is accompanied by the second part that acts as a client, which connects to the server. Two client programs are part of the provided software packages. A relatively complex application to interact with the camera model is located in cam_tracker_client directory. This application allows to set various parameters and capture and visualize the image by the camera, which can be useful for calibrating the camera.

In tracker_client_example directory, a simple client is provided, which just connected to the server and print the received information on screen. A used communication protocol is a simple custom message oriented protocol. Particular marshaling and unmarshaling functions (based on XDR) are provided, see serialization.cc file for a further details.

The communication between the server and client is established using TCP messages, which are also used to control the tracker servers. However, for transmitting information about the tracked object short UDP messages are used to avoid transport delays. So, the cam_tracker_client uses TCP while the tracker_client_example uses UDP.

An initial version of the tracker software has been developed under research project COLOS. Although the herein presented software represents a newer version, the main ideas and configuration of the tracker server is same. Therefore, an additional useful information can be found in technical report.

ROS node

The provided ROS node is a bridge between the custom UDP protocol and a bit heavier communication of ROS. The implementation is pretty much straightforward and the source code of the has just about five hundreds lines. The node is called camreloc and provides following parameters, which are basically derived from the server client.

/camreloc/host - the host address of the tracker server.
/camreloc/port - the port of the tracker server.
/camreloc/myip - ip address used for connecting to the server.
/camreloc/myport - UDP port where messages will be send.
/camreloc/blocking_read - enable/disable a blocking read from the server, e.g., during initialization of the communication.

Gumstix Overo Environment

Probably the most important part to use or test the pattern localization algorithm is a setup of working environment on the Gumstix Overo board. An image file for a micro SD card is available at caspa512m-usd.dmp.xz. The image can be replicated using dd command. Notice the image file needs a micro SD card with at least 512 MB size.

An additional way is to create a bootable micro SD card, e.g., according to create a bootable microsd card. If you are using FreeBSD, you can use fdisk-linux in a similar way to create two partitions. Create the first small FAT partition to store the boot loader. To initialize the boot loader properly it is necessary to copy the files in the correct order, e.g.

newfs_msdos -F 32 -L BOOT /dev/da0s1
mount_msdosfs /dev/da0s1 /mnt/boot
cp MLO /mnt/boot/
cp u-boot.bin /mnt/boot
cp uImage /mnt/boot

Then, create a root file system for the operating system, e.g. as follows.

mkfs.ext3 -L LINUX /dev/da0s2
tune2fs -c 0 -i 0d /dev/da0s2
mount_ext2fs /dev/da0s2 /mnt/root

Once you have a prepared file system, you can use the provided rootfs.tar.gz to create an initial version of the system, which contains the tracking server. All the relevant files are located in the /opt directory, except the system files enabling the particular services at the boot time, which are obviously in the /etc directory. The tracker is started according to the /etc/init.d/tracker file and all the relevant configuration files are located at the /opt/tracker directory. After that, you can customize the server WiFi connection, which monitored by a custom system service wifid initiated by the /etc/init.d/wifi_monitor script. This service use a specific configuration located in /opt/wlan_config, which is actually a symbolic link to a particular configuration. A couple of configuration files is provided; hence, use them as a source of inspiration. Notice, that sometimes configuring WiFi under Linux can tricky and commands iwconfig and ifconfig have to be called with particular parameters in a correct order.