Using SCRIMMAGE with GAMS

Overview

SCRIMMAGE provides a means to visualize and control robots en masse when controlled with GAMS. GAMS provides out of the box algorithms, multi agent control architectures, and platforms which efficiently process and store information when combined with MADARA. In an ongoing effort to provide more visualization and simulation tools to demonstrate MADARA and GAMS capabilities, SCRIMMAGE support was added to the GAMS repository.

Installation and Setup:

This will download the SCRIMMAGE repo and link its libraries to GAMS and gams_controller. It will also build the SCRIMMAGE repo and provide access to all its binaries. Using this also assumes a user has already followed the GAMS download and setup guide. However, if not, the only command required prior is:

git clone https://github.com/jredmondson/gams

and then build with SCRIMMAGE support:

cd $GAMS_ROOT ./scripts/linux/base_build.sh gams madara scrimmage cleanenv

Demos

Each time you run the simulator or a new experiment you will want to first run:

scrimmage-viz

Once that is done you can use one of the scripts below to run a demo

Follow the leader algorithm demonstration:

cd $GAMS_ROOT ./scripts/simulation/scrimmage/follow/follow_demo.sh

Spelling a word demonstration:

cd $GAMS_ROOT ./scripts/simulation/scrimmage/spell/spell_demo.sh

Parameters used:

Change these in a *.mf file to configure the simulation: run_simcontrol_threaded: If set to 1, runs SimControl in its own thread for better performance. If 0, runs in the same thread as the Multi-controller and provide more deterministic results. worldfile: The XML file to load into SimControl. Currently GAMS provides default_fixed_wing.xml and default_quadcopter.xml.

Developer Info:

How GAMS controls SCRIMMAGE:

In the below diagram the SCRIMMAGEBasePlatform has 3 functions which interface with SCRIMMAGE.

spawn_entity():

This function will make a call to a SCRIMMAGE topic advertised from SimControl. I could not get this to work with the direct function calls to generate_entity() and generate_entities(). This is the documented method utilized which is unfortunate that it has to go over a network protocol to send the entity description. To spawn an entity with this function, the entity description must be provided in the mission XML file at the time it is loaded into the SimControl object. That entity will take the ID of 0 inside the SCRIMMAGE code, and therefore all subsequent entities spawned will start from 1 and go towards N number of agents as decided by the user. At this time, only a quadcopter with a simple motion model that allows XYZ points as a desired state is supported.

move() & orient():

These functions will set the desired_state_ variable in their respective Entity's autonomy plugin. When the SCRIMMAGE loop next processes the autonomy state, it will take this state and pass it to the SCRIMMAGE Controller which will update the position in the simulator. move() will update the XYZ position, and orient() will update the RPY position.

Configuring the SCRIMMAGE simulator:

All configuration can be done by creating or modifying an XML file. GAMS provides a default one which works with the demos and is located in

$GAMS_ROOT/src/gams/platform/scrimmage/missions/default_world.xml

SCRIMMAGE provides documentation on how to modify and edit this file here.

Customizing an entity:

This will be done by modifying the variables in an tag in the above XML file.

Adding a new entity type:

This will be done by replacing the tag in the default_world.xml file with a new one (having two entities will have undefined behaviour at present) and specifying the variable as 0 so as to prevent an entity from spawning unless we make a call to spawn_entity(). The recommended approach is to copy the existing default_world.xml and create a new tag with decided upon parameters.

Scaling GAMS with SCRIMMAGE:

Specify how many agents to spawn by replacing N with the number of agents.

cd $GAMS_ROOT ./scripts/programs/gams_controller --platform -mc N -nt

Note: When using large amounts of agents (>200) you may need to edit your Linux ulimit variables. See this page for a guide on how to do that.

Using gams_controller directly with scrimmage:

Specifying the platform type as scrimmage will suffice to running the SCRIMMAGEBasePlatform which will spawn 1 agent. At present, it only spawns the default quadcopter agent. Users who want additional support can subclass this platform and create their own.

cd $GAMS_ROOT ./scripts/programs/gams_controller --platform scrimmage -mc 1 -nt

The GAMSAutonomy SCRIMMAGE Plugin:

Currently this is specified in the XML file. However it doesn't do much other than provide a placeholder as an agent is required to have an autonomy otherwise undefined behaviour occurs in the SCRIMMAGE simulator. The set_desired_state() method provided by its parent class is called during the move() & orient() functions. It is loaded dynamically at runtime by SCRIMMAGE and thus it is required this plugin is on the LD_LIBRARY_PATH.

Architecture and Control Flow Diagram:

Environment Variables Provided/Used:

In any case of there being a bug or files not found, first try

source ~/.gams/env.sh

and

source ~/.bashrc

Added environment variables

• SCRIMMAGE_PLUGIN_PATH is set to \$SCRIMMAGE_PLUGIN_PATH:\$GAMS_ROOT/lib/scrimmage_plugins:\$GAMS_ROOT/src/gams/plugins/scrimmage
• SCRIMMAGE_MISSION_PATH is set to \$SCRIMMAGE_MISSION_PATH:\$GAMS_ROOT/src/gams/platforms/scrimmage/missions/
• SCRIMMAGE_GIT_ROOT is set to $INSTALL_DIR/scrimmage (typically $GAMS_ROOT/scrimmage)
• SCRIMMAGE_ROOT is manually set to SCRIMMAGE_ROOT="/opt/scrimmage/x86_64-linux-gnu/" because the SCRIMMAGE maintainers insist on not setting it when downloading their debian package

Modified environment variables

LD_LIBRARY_PATH is modified to include $SCRIMMAGE_GIT_ROOT/build/lib/:$SCRIMMAGE_GIT_ROOT/build/plugin_libs