Creating Platforms (C)

C++ Guides: GAMS Primer | Creating Algorithms | Creating Platforms | Debugging

---

Introduction

GAMS provides an extensible platforms infrastructure for encoding robotics platforms, simulated agents, or software agents. The platforms interface is reasonably expressive, though the more extensible aspects are centered around movement rather than grabbing with arms, kicking, etc. In this wiki, we take a look at how to extend the BasePlatform class and the features that GAMS provides to platform developers.

To simplify the platform creation process, we have written a script called gams_sim_conf.pl that allows quick creation and configuration of not only new user platforms but also custom controllers that utilize your platforms. In this wiki, we'll walk through the process of creating and maintaining new platforms.

---

Creating a new platform with gams_sim_conf.pl

Creating a new platform can be greatly simplified by using the gams_sim_conf.pl tool. To use the tool, decide where you want a custom project to be located. We'll refer to this as a PROGRAM_LOCATION environment variable. A good place for this might be in a folder in your home directory, say HOME/gams_examples. The following examples assume perl is installed on your computer and available in the PATH variable. If perl is installed but not in PATH, you will want to call perl on the gams_sim_conf.pl script to run it.

If you have any questions about usage of gams_sim_conf.pl, pass the script a -h or --help option for guidance and information.

Generating new algorithm in Windows command shell (cmd in Start->Run)

%GAMS_ROOT%\scripts\gams_sim_conf.pl --new-platform my_platform --path %PROGRAM_LOCATION%

Generating new algorithm in Linux terminal

$GAMS_ROOT/scripts/gams_sim_conf.pl --new-platform my_platform --path $PROGRAM_LOCATION

Running these commands will generate a new directory at PROGRAM_LOCATION. Do not create the directory beforehand. Let the tool do that to ensure it doesn't assume the appropriate infrastructure has already been generated. The tool tries to do no harm to your projects when possible, so you can add new algorithms, platforms, simulations, etc. later.

The tool will generate a number of files and a build infrastructure using the MakefileProjectCreator for portability to Windows, Linux, Mac, Android, etc. As far as editing goes, there are only three files that most users may want to edit:

PROGRAM_LOCATION/src/platforms/my_platform.h
PROGRAM_LOCATION/src/platforms/my_platform.cpp
PROGRAM_LOCATION/src/controller.cpp

The my_platform class is found in the my_algorithm.h|cpp files. By default this class is a null implementation of the BasePlatform class with stubs for the required methods outlined in the Methods section. It also contains a factory class that allows a GAMS controller to dynamically allocate new instances of your platform, whenever a user needs to create one for simulations in VREP or other simulated environments. This is going to be where your platform is implemented, preferably as a series of interactions with concurrent threads, software libraries, and hardware interfaces.

The controller.cpp file contains a custom GAMS controller that initializes your platform factory class and allows users to create instances of your platform. This is useful, especially, if you are building a simulated robotics platform for testing in VREP. By default, this controller compiles and links to GAMS, MADARA and ACE as well as using your platform.

Generating/compiling project in Windows command shell (cmd in Start->Run)

cd %PROGRAM_LOCATION%
mwc.pl -type vc12 workspace.mwc
workspace.sln

After opening the Visual Studio project, compile the project with the settings used during compilation of MADARA and GAMS (e.g. 64 bit, Release mode).

Generating/compiling project in Linux terminal

cd %PROGRAM_LOCATION%
mwc.pl -type gnuace workspace.mwc
make

You can speed up compilation by call make with -j , where NUMCORES is the number of cores on your build machine. This essentially will parallelize the build process, but with a project this small, the build process is very quick (should take a few seconds).

Believe it or not, you have already just generated and compiled a GAMS platform with a custom controller!

---

Methods

The GAMS controller directly calls two platform method during normal execution (sense and analyze) and these are the first two methods called at the top of the MAPE-K loop. The majority of calls to platform methods are actually made by algorithms during their analyze and execute phases. Developers will need to provide implementations of each of the methods in the BasePlatform base class, and the intentions of these methods are the following:

1. analyze: Analyzes the state of the platform
2. home: Returns to a home location
3. get_id: Returns the unique id of the platform. This should be alphanumeric with no special characters or spaces. This id is used in creating underlying platform variables in the knowledge base.
4. get_name: Returns the name of the platform. This can be a verbose name with capitalization.
5. get_min_sensor_range: Returns the minimum sensor range of sensor payloads. This is used for discretization of search regions, generally.
6. get_move_speed: Returns the maximum move speed of the platform
7. get_sensor: Override-able method for getting sensor information
8. get_sensor_names: Override-able method for retrieving all sensors on the platform
9. land: Lands the platform. Can be left stubbed for vehicles that cannot take off
10. move: Moves the platform to a position in a x, y, z coordinate system (can be GPS)
11. pause_move: Pauses an ongoing movement
12. sense: Polls the sensors and records any useful information
13. set_move_speed: Sets the movement speed of the platform
14. stop_move: Cancels an ongoing movement
15. takeoff: Lifts the platform into the air. Can be left stubbed for vehicles incapable of lifting off.

analyze

Analyze inspects the raw data available and generates higher-level information. An example of this is settings a low battery flag.

move

move must be non-blocking. Platforms must be resilient to multiple successive calls to move with the same arguments. One way to do this is to launch a thread in the platform constructor that can be queried for current movement status and ordered a new movement location.

---

Method implementations: Blocking vs. Non-Blocking

All methods should be non-blocking to allow for platform.sense (), platform.analyze (), and algorithm.analyze () to be called frequently and for updates to the knowledge base to be sent out to other agents or human overseers. If you must use blocking calls, the best way to support them is to create a polling class/infrastructure that launches a thread for the blocking operation and provides a polling mechanism for checking if the blocking operation has completed.

For instance, if you already have a move function for your robotic platform that currently blocks until the movement is finished, you can still use this function. However, you will probably want to launch a thread that can be polled from the analyze method to see if the movement is complete and immediate return control back to the GAMS controller to perform its next task.

---

Provided Variables

GAMS provides pre-configured variables based on the invocation of init_vars on the BaseController. The init_vars function provides the id of the agent along with the estimated number of processes, and this information is used to populate a set of variables in the knowledge base for usage in algorithms and platforms.

The key variables you should know about are the following:

• self_: the Self class is a self-referencing variable based on the id of the agent. self_->agent is a container for all variables that begin with agent.{.id} in the knowledge base (where .id is the id passed in through init_vars). self_->id is an Integer container that directly maps to .id in the knowledge base.
• status_: PlatformStatus is a set of flags that may be useful for algorithms, especially ones implemented as finite state machines. There are flags here that may be enabled to let other agents know you are deadlocked, waiting, ok, etc.
• sensors_: Sensor is a facade for representing sensor readings, typically over a geographic area. Sensors can be configured with ranges to aid with discretization of search spaces, for instance.

---

Controller Platform Factory

A factory class must be added for each new platform. This class must inherit from PlatformFactory. The only method that must be overwritten is create. The create method can check the arguments for reasonable values if required. If the arguments are valid, then create shall construct the algorithm and return a pointer to it.

The new derived Platform_Factory class must be added to the Controller_Platform_Factory. There are two options to add new Platform_Factory classes. The first option is to add the platform to the list of default options in initialize_default_mappings. Resize the aliases variables to the number of commands selected for the new algorithm. Populate the variable. Add the new Platform with the new Factory. For example, here is how the VREP_Summit platform (ControllerPlatformFactory) is added:

aliases.resize (2);
aliases[0] = "vrep-summit";
aliases[1] = "vrep_summit";

add (aliases, new VREP_Summit_Factory ());

Multiple additions of the same name will overwrite previous additions.

The other option is to use the add function. This allows other algorithms to be added after the Controller_Platform_Factory has been created.

C++ Guides: GAMS Primer | Creating Algorithms | Creating Platforms