Swarmathon-ROSThis repository is a ROS (Robot Operating System) controller framework for the Swarmie robotsused in the NASA Swarmathon, a national swarm robotics competition. This particular framework isa ROS implementation of the CPFA (central-place foraging algorithm) developed for iAnt robotswarms at the University of New Mexico.

This repository contains:

Source code for ROS libraries (i.e. packages) that control different aspects of the Swarmie robot,1.including localization, mapping, mobility, and obstacle and target detection3D .STL models for the physical Swarmie build2.Bash shell scripts for initializing simulated Swarmies in the Gazebo simulator, as well as physical3.Swarmies

Please submit bug reports for Swarmathon-ROS through GitHub's Issues system. For all other●

questions regarding the Swarmathon-ROS code base, please visit the forums on the NASASwarmathon website.Please consult git best practices for guidelines on the most effective approaches to maintaining●

code. Teams will be expected to commit new code at least every two weeks, and ideally commitone or more times per week. Consult the NASA Swarmathon Timeline for specifics on how oftencode should be committed, as well as the cutoff date for final code revision before thecompetition.

Quick Start Installation Guide

Swarmathon-ROS is designed and tested exclusively on Ubuntu 14.04 LTS (Trusty Tahr) and ROSIndigo Igloo. This framework may compile and run correctly under other versions of Ubuntu andROS, but NOTE that these other systems are untested and are therefore not supported at this time.

1. Install ROS Indigo

Follow the detailed instructions for installing ROS Indigo under Ubuntu 14.04 here. We recommendthe Desktop-Full installation, which includes the Gazebo 2 simulator.

2. Install additional ROS plugins

Our simulated and physical Swarmies use existing ROS plugins, external to this repo, to facilitatenon-linear state estimation through sensor fusion and frame transforms. These plugins arecontained in the robot_localization package, which should be installed using the apt-get packagemanagement tool:

sudo apt-get install ros-indigo-robot-localization

3. Install additional Gazebo plugins

Our simulated Swarmies use existing Gazebo plugins, external to this repo, to replicate sonar, IMU,and GPS sensors. These plugins are contained in the hector_gazebo_plugins package, which shouldbe installed using the apt-get package management tool:

sudo apt-get install ros-indigo-hector-gazebo-plugins

Our Swarmies can receive mobility commands from the right thumb stick on a Microsoft Xbox 360controller. The ROS joystick_drivers package, which contains a generic Linux joystick drivercompatible with this controller, should also be installed using the apt-get tool:

sudo apt-get install ros-indigo-joystick-drivers

4. Install git (if git is already installed, skip to step 5):

sudo apt-get install git

5. Install Swarmathon-ROS

Clone this GitHub repository to your home directory (~):cd ~1.git clone https://github.com/BCLab-UNM/Swarmathon-ROS.git

Rename the downloaded repo so it can be properly identified by ROS and catkin: mv2.~/Swarmathon-ROS ~/rover_workspace

Change your current working directory to the root directory of the downloaded repo: cd3.~/rover_workspace

Set up ublox GPS submodule: git submodule init4.git submodule update

Compile Swarmathon-ROS as a ROS catkin workspace: catkin_make5.Update your bash session to automatically source the setup file for Swarmathon-ROS: echo6."source ~/rover_workspace/devel/setup.bash" >> ~/.bashrcsource ~/.bashrc

Update your bash session to automatically export the enviromental variable that stores the7.location of Gazebo's model files: echo "exportGAZEBO_MODEL_PATH=~/rover_workspace/misc/models" >> ~/.bashrcsource ~/.bashrc

6. Run the Swarmathon-ROS simulation:

Change the permissions on the simulation run script to make it exectuatable: cd1.~/rover_workspacechmod +x ./run.sh

Start the simulation ./run.sh2.

The GUI will now launch. The run script kills a number of gazebo and ROS processes. Killing theseprocesses is suggested by gazebosim.com as the best way to clean up the gazebo environment at

the moment.

This is the first screen of the GUI:

Click the simulation paramenters tab:

Choose the ground texture, whether this is a preliminary or final round (3 or 6 robots), and thedistribution of targets.

Click the "build simulation" button when ready.

The gazebo physics simulator will open.

Click back to the Swarmathon GUI and select the "sensor display" tab.

Any active rovers, simulated or real will be displayed in the rover list on the left side.

Select a rover to view its sensor outputs.

There are four sensor display frames:

The camera output. This is a rover eye's view of the world.

The ultrasound output is shown as three white rays, one for each ultrasound. The length of the raysindicates the distance to any objects in front of the ultrasound. The distance in meters is displayedin text below these rays. The maximum distance reported by the ultrasounds is 3 meters.

The IMU sensor display consists of a cube where the red face is the bottom of the rover, the blueface is the top of the rover, and the red and blue bars are the front and back of the rover. The cubeis viewed from the top down. The cube is positioned according to the IMU orientation data. Forexample, if the rover flips over, the red side will be closest to the observer. Accelerometer data isshown as a 3D vector projected into 2D space pointing towards the sum of the accelerations in 3Dspace.

The map view shows the path taken by the currently selected rover. Green is the encoder positiondata. In simulation, the encoder position data comes from the odometry topic being published byGazebo's skid steer controller plugin. In the real robots, it is the encoder output. GPS points areshown as red dots. The EKF is the output of an extended Kalman filter which fuses data from theIMU, GPS, and encoder sensors.

To close the simulation and the GUI, click the red exit button in the top left-hand corner.

Software Documentation

Source code for Swarmathon-ROS can be found in the ~/rover_workspace/src directory. Thisdiretory contains severals subdirectories, each of which contain a single ROS package. Here wepresent a high-level description of each package.

abridge: A serial interface between Swarmathon-ROS and the A-Star 32U4 microcontroller●

onboard the physical robot. In the Swarmathon-ROS simulation, abridge functionality issupplanted by gazebo_ros_skid_steer_drive (motor and encoders) and hector_gazebo_plugins(sonar and IMU; see step 3 of the Quick Start guide).mobility: The top-level controller class for the physical and simulated robots. This package●

receives messages on the status of targets and/or obstacles in front of the robot andautonomously makes decisions based on these factors. This packages also receives pose updatesfrom robot_localization (see step 2 of the Quick Start guide) and commands from joystick_drivers(see step 3 of the Quick Start guide).obstacle_detection: A logic processor that converts sonar signals into a ternary collision value.●

This package receives sonar messages from abridge (for physical robots) orhector_gazebo_ros_sonar (for simulated robots), and returns a status message to differentiatebetween three possible cases:

No collision1.A collision on the right side of the robot2.A collision in front or on the left side of the robot3.

rqt_rover_gui: A Qt-based graphical interface for the physical and simulated robots. See How to●

use Qt Creator for details on this package.target_detection: An image processor that detects AprilTag fiducial markers in the onboard●

camera's video stream. This package receives images from the usbCamera class (for physicalrobots) or gazebo_ros_camera (for simulated robots), and, if an AprilTag is detected in the image,returns the integer value encoded in the tag.ublox: A serial interface to the ublox GPS receiver onboard the physical robot. This package is●

installed as a git submodule in the Swarmathon-ROS repo. See the ublox ROS wiki page for more

information.

How to use Qt Creator to edit the simulation GUI

Install Qt Creator: sudo apt-get install qtcreator1.sudo apt-get install python-catkin-tools

Build the workspace: catkin clean -a2.catkin build

Run Qt Creator: qtcreator &3.Choose "Open File or Project" from the File menu4.Navigate to ~/rover_workspace/src/rqt_rover_gui/5.Select CMakeLists.txt6.Click "Yes" to creating a .pro file7.Enter ~/rover_workspace/build as the default build path8.Click Configure Project9.Click on the Projects icon on the left toolbar10.Enter -DCMAKE_INSTALL_PREFIX=../install -DCATKIN_DEVEL_PREFIX=../devel in the CMake11.arguments text boxClick the "Edit" toolbox icon on the left12.Double-click CMakeLists.txt13.Click the "Build Now" button to build the project14.

Qt Creator can now be used to build the rover_workspace