DEECo Playgrond is a framework for simulation and visualization of scenarios for smart Cyber-Physical Systems (sCPS). Its goal is to help in prototyping and testing of software for sCPS. In particular, it can be used for developing and testing scenarios featuring autonomous mobile entities (like robots or autonomous vehicles) that cooperate with each other, with other smart objects placed in the environment and with the environment itself.
In order to run the application you need to have Java 8 or newer installed.
There are three prepared and ready-to-run example scenarions. They can be executed with shell scripts (on Linux systems) or batch files (on Windows), which are in the demos-linux resp. demos-windows directories.
There are always two scripts for each scenario, simulation and visualization. Each scenario has to be simulated before it can be visualized, i.e., the correct sequence of execution is :
./name-of-scenario-simulate.sh
./name-of-scenarion-visualize.sh
The *-simulate.sh script launches the simulator. It continuously outputs information about simulation progress and in the end, it prints statistics about the simulation.
The *-visualize.sh script launches the visualizer configured with data produced by the simulator. It opens a window, in which the visualization runs. It can be controlled via the following keys:
- space - pause/resume visualization
- left arrow - skip several steps back
- right arrow - skip several steps forward
- up arrow - increase the speed of visualization
- up arrow - decrease the speed of visualization
- enter - restart visualization from the beginning
The scenario features two types of robots. There is a one robot of the type PredatorRobot, which moves along its predefined path through the field. All the other robots are of the type PreyRobot, and are programmed to run away from the predator, if it appears near them. These robots receive the information about the position of the predator through an ensemble. The scenario is visualized with the default configuration without any additional layers or other adjustments.
Its scenario configuration can be found in the file examples/scenarios/predator.xml; and its visualization configuration is in the file examples/configs/config.xml.
The Firefighters scenario presents a case in which a team of firefighter robots has an objective to extinguish fires appearing on the field. The leader of the firefighter team collects information about each robot's situation, and issues orders to its teammates based on that information. The scenario shows usage of an additional layer of the environment, the temperature layer, in which the fires appear. Robots in this scenario are equipped with additional temperature sensors and fire extinguishers to interact with this layer. There is also the charging station recharging the robots' batteries (which power their wheels and fire extinguishers).
Its scenario configuration can be found in the file examples/scenarios/firefighters.xml; and its visualization configuration is in the file examples/configs/firefighters-config.xml.
In the Competition scenario, two teams of robots compete with each other for items appearing on the screen. The items are interactive objects programmed to disappear when a robot shows up near them, and to reappear later at a different location. A team receives a point for each item collected in this way. The simulation stops when a team receives a defined number of points. In this scenario, robots' movements consume energy from their batteries, which can be recharged at charging stations of each team.
Its scenario configuration can be found in the file examples/scenarios/competition.xml; and its visualization configuration is in the file examples/configs/competition-config.xml.
In order to make launching of the project as simple as possible, we have prepared a virtual machine image (for VirtualBox) that can be downloaded here. It contains a Linux installation with the project and all of its dependencies already installed, along with IDE and documentation files. On the desktop of the VM you can find a readme file with instructions on running the project, using IDE, etc.
To run one of the described above scenarios
- double-click on the corresponding simulation script (on the desktop), e.g. "Firefighters Scenario Simulation". It will run the simulation of the scenario in a terminal.
- once the simulation is finished, double-click on the corresponding visualization script, e.g. "Firefighters Scenario Visualization". It will open the window with the visualization of the scenario.
If you have Apache Ant installed, you can run simulations and visualizations with the following commands (run from the project root directory):
ant run.simulation -Dargs="arguments"
ant run.visualization -Dargs="arguments"
In the case of simulation the arguments are scenario files (more than one can be specified). For visualization, the first argument has to be a simulation logs file, the second one is an optional configuration file.
The ant build file also allows to generate javadoc with the command ant doc and to clean the generated files from the directory with ant clean.
The project directory can be opened as an IntelliJ IDEA project. As such it will contain several predefined run configurations. For each existing scenario, there are two of them: one for simulation, and one for visualization. In order to run the visualization of the scenario you need to simulate it first (since the simulation produces the logs, which are then supplied to the visualization).
These launch configurations are available in the combo-box on the top toolbar in IDE. You can just choose the desired configuration in the combo-box and then hit the launch button (the green triangle on the right side of the combo-box).
There are also .project and .classpath files in the project directory, that can be used to import the project to Eclipse or NetBeans. The runnable classes are cz.cuni.mff.d3s.deeco.playground.simulation.Main and cz.cuni.mff.d3s.deeco.playground.visualization.Main for simulation and visualization respectively.
There are three main documents.
Guide.pdf contains the Scenario Creation Guide. It is a step-by-step tutorial illustrating the process of a scenario creation on two examples.
Architecture.pdf describes the architecture of the playground framework and its internal structures and detailes the implementation.
manual.html page contains a technical description of scenario creation and configuration. It describes the formats of scenario files and configuration files. Also it provides an overview of the classes (i.e., components and ensembles) that a user needs to create in the process of scenario creation, explaining the meaning and behavior of all their methods and fields. The links in the file may refer to the javadoc documentation (you need to generate javadoc with the ant doc command in order to make them work).
The source code of the framework and the example scenarios can be found in the src/java folder.
The XSD schemas for scenario files and visualization configuration files are located in the src/resources folder.
Folder examples contains the scenario files, the configuration files, the textures and the bitmaps of obstacles used in all the example scenarios.