Design Document

This page will contain all design decisions that went into the creation of our robot soccer system

Required software

• Ubuntu 12.04+: This operating system was chosen given the simple install interface (if anything goes wrong, it's easy to completely reinstall the system) and availability of programming tools.
• ROS Hydro Full: Chosen as the robot framework that will provide communication, simulation, logging and other features.
• OpenCV 2.4.8: Default the computer vision library due to its performance.
• Gazebo 1.9.3: Default simulator for validating strategy code.
• Libfreenect: Kinect camera and depth sensor driver. Although OpenNI provides more functionality, since Apple bought its developer, PrimeSense, the software should go down by April 2014. Therefore, libfreenect was chosen thinking in the future development.

ROS packages

• vision_opencv: Integration with OpenCV
• gazebo_ros_pkgs: Integration with Gazebo
• freenect_stack: Integration with Libfreenect

Project structure

The project is composed by several modules, each containing one ROS node that executes one specific task. The nodes communicate to each other by publishing ROS topics and subscribing to them.

If a node or module is performing several tasks, the developers are allowed to break it into two or more pieces as long as it does not require to restructure other nodes.

• camera: Connects to the camera drivers and publishes an image of the current view of the game.
• dummy_camera: Sends images for testing purposes.
• vision: Processes images and extract information about the current state of the game.
• strategy: Generates actions based on the state of the game.
• control: Sends commands to the robots using the communication drivers.
• simulation: Uses Gazebo to simulate a game for strategy validation. It communicates directly with the strategy node.

Each module should have one subdirectory in the src/unball directory, containing the node and all necessary sources and header files. For instance, the vision module is in src/unball/vision and may have the files vision_node.cpp, vision.cpp, and vision.hpp.

Module structure

Each module should have a clear and well defined structure consisting of:

• A node with an infinite loop: Each node should be a source file with {module name}_node in its name and .cpp extension, for example: strategy_node.cpp. This file must implement an infinite loop where it will call the run() method of the main class, and publish and receive messages, if any. Example for the infinite loop:

while (ros::ok())
{
    strategy.run();
    
    publishRobotsVelocities(publisher);
    
    ros::spinOnce();
    loop_rate.sleep();
}

• Main class: The main class should have a run() method, preferably with no arguments, to be called by the node file. This method should run the whole algorithm of the module, which can be divided in other methods and classes, if necessary.

Communication scheme

While in online operation, i.e., when working with the robots, the message flow is camera -> vision -> strategy -> control.

In offline mode, messages flow in the pipe strategy <-> simulation.

Messages structure

In order to facilitate improvements and readability, each node should have its own message type instead of building workarounds with standard messages. For instance, a strategy message containing robots linear and angular velocities should be

float32[6] lin_vel
float32[6] rot_vel

In contrast, one should not try appending these velocities to a string, separating by comma.

All message description files must have .msg extension and be placed in the msg/ directory.

Launch files

It may be useful to have launch files, which can start multiple nodes at the same time. Then, for example, instead of running dummy camera, vision, and strategy one by one in different terminals, one can launch roslaunch unball dummy_vision_strategy.launch.

All launch files must have .launch extension and be placed in the launch/ directory.

Configuration files

Every module may require a configuration file, with parameters that are evaluated in run time (instead of compilation time). By default, ROS uses YAML format for configuration files. An example of configuration file is presented below.

vision:
    # Indicates whether the vision module will process RGB images or ignore them.
    # true: process RGB images.
    # false: ignore RGB images.
    using_rgb: true

    # Indicates whether the vision module will process depth images or ignore them.
    # true: process depth images.
    # false: ignore depth images.
    using_depth: true

    segmenter:
        # Show trackbars to manually set the minimum saturation and value for HSV segmentation.
        # true: Show trackbars.
        # false: Don't show trackbars.
        hsv_adjust: false

        # Minimum saturation for HSV segmentation.
        hsv_min_s: 100

        # Minimum value for HSV segmentation.
        hsv_min_v: 190

Configurations are loaded in launch files by using the rosparam tag. For instance: <rosparam command="load" file="$(find unball)/config/vision.yaml" />.

The C++ method ros::param::get is used to fetch a configuration value and store it into a variable, maintaining the variable type. For example:

bool using_rgb;
ros::param::get("/vision/using_rgb", using_rgb);

All configuration files must have .yaml extension and be placed in the config/ directory.