The basic_simulator

The basic-simulator, when compiled, is a self-contained jar capable of running complete simulations. It runs locally on one machine and is therefore well suited for rapid testing and debugging.

Running

After cloning and building the basic-simulator repository, the program can be started using the run.bat or run.sh script inside basic-simulator/install.

The basic-simulator project is a Maven project. It is thus built using mvn clean install -s settings.xml. TODO link to maven tutorial.

The following window should open (a simulation was already loaded in the image):

The browser on the left shows the content of the folders that are alongside the basic-simulator.jar file.

• Visualizing Maps: By selecting a map in the browser, it will be shown and can be navigated as explain in the overlay on the top left. Coordinates can be copied with a right click.
• Running Simulations:
  • When clicking a scenario in the browser, a simulation is directly loaded from it.
  • The controls on the top allow to run the simulation.
    • Realtime vs Full Speed: In Real-time mode, the simulation is run at a virtual time corresponding to the real time (depending on the simulation speed parameter). In full-speed mode, the simulation is computed as fast as possible.
    • Simulation Speed (for real-time mode): Ratio between the virtual simulation time and real time.
    • Reset: Loads the simulation anew.
    • Play/Pause: Start/Stop the simulation.
    • Time: The virtual time in the simulation.
    • delta t: physics tick speed.
    • Sim Speed: Ratio from virtual simulation time to real time that is achieved. (Tries to target the Simulation Speed parameter.)
    • FPS: Frames per second for the visualization.
    • Status: Status of the simulation: RUNNING, SUCCEEDED or FAILED.
  • Below the map view of the simulation are some debugging options:
    • Inspect Autopilot I/O: shows the data at the ports of the autopilot.
    • Show Planned Path: Shows the trajectories planned by the Navigation component of vehicles.
    • Show Trajectory: The Navigation component only sends the next waypoints of the trajectory.
    • Show Actuators: Shows some visualisation of the steering and gas/break status of the vehicle.

CLI

The basic-simulator JAR can be used in a CLI fashion to run simulations without the GUI.

Just pass the path to a scenario file as argument when running the simulator. This can be done with the run script of the install folder or by making the proper underlying java call.

Example:

run.bat cli_test.json

The result (SUCCESS/FAILURE) of the simulation will be printed and the return value will be different than 0 on failure (to use in CI, ...).

<<<<<<< HEAD Next: Simulation Configuration

Debugging (Advanced)

The basic-simulator setup is local and self-contained. This allows you to run the java debugger on the jar.

For this create a Run/Debug configuration that executes the jar and specify a folder in which to run it. (Ex: the install folder inside the basic-simulator project). You can then start the simulator in normal or debug mode, set breakpoints and step through almost the entire code.

This can be done with any editor/debugger. The following sections give examples on how to do this with VSCode and IntelliJ.

It is recommended to run the debugger on the jar and not directly in the editor, since there might be problems with the dependencies otherwise.

Debugging with VSCode

The basic-simulator contains a default launch.json config. This debugging configuration assumes the simulator is built and the jar lies in the install folder (this is the default behavior when running mvn install ...). This launch configuration can be started in the Run and Debug tab of VSCode.

Tip: Setting breakpoints in the classes of dependencies is not trivial in VSCode. A trick to do so involves the following:

• In a class of the basic-simulator project (ex: App.java), create a dummy variable of the class you want to set a breakpoint in.
• Ctrl+click on the type name, this will open the .class file of the class. You can then set your breakpoints.

As example, to set a breakpoint in the constructor or measuredCycle() function of the TCPBackend.java class of the hardware-emulator, you can temporarily create this dummy variable anywhere in the basic-simulator (ex: App.java): TCPBackend dummy;. Then ctrl+clicking on TCPBackend should open the TCPBackend.class file. (If the Java extension for VSCode is installed).

Once the breakpoint is set, the class file and the breakpoint will remain accessible in the breakpoints list in the Run and Debug tab.

Debugging with IntelliJ

IntelliJ configuration example for running the jar in the install folder:

Debugging the hardware_emulator

The hardware_emulator is C++ code run as native-library inside the simulator.

The steps to step through/set breakpoints in the hardware_emulator are a bit more complex:

• Build the hardware_emulator in debug mode.
• Replace the hardware_emulator_lib file alongside the basic-simulator jar with the debug version.
• Start the basic-simulator.
• Attach to the Java thread of the simulator with a C++ debugger.
• Set your breakpoints in the C++ project, run the simulator.
• To return to using the default release version of the hardware_emulator, just delete the library alongside the basic-simulator jar; it will be re-exported.

In Windows environment

This is easily done in the Visual Studio solution for the hardware_emulator. For this, open the hardware_emulator.sln solution in the build directory of the hardware_emulator. Then attach to the simulator thread by going to Debug -> Attach to Process and searching for java in the filter.

Next: JSON-scenarios reference