|
|
![basic-simulator banner](/img/basic-sim-banner.png "Basic-simulator artwork.")
|
|
|
![basic-simulator banner](/img/user-docs/basic-sim-banner.png "Basic-simulator artwork.")
|
|
|
|
|
|
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.
|
|
|
|
... | ... | @@ -8,13 +8,30 @@ After cloning and building the [basic-simulator repository](https://git.rwth-aac |
|
|
|
|
|
> 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:
|
|
|
|
|
|
![basic-simulator GUI](/img/basic-sim-gui.png "Basic-simulator GUI.")
|
|
|
|
|
|
The browser on the left shows the content of the folders that are alongside the `basic-simulator.jar` file. The **OSM maps** can be visualized by selecting them. When selecting a **scenario**, it will immediately load the corresponding simulation and show *simulation controls* at the top. Using these, simulations can be started, paused and reset. The speed at which the simulation should run can also be set.
|
|
|
|
|
|
> The map visualization can be used to copy coordinates (for scenarios).
|
|
|
The following window should open (a simulation was already loaded in the image):
|
|
|
|
|
|
![basic-simulator GUI](/img/user-docs/basic-sim-gui.png "Basic-simulator GUI.")
|
|
|
|
|
|
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
|
|
|
|
... | ... | @@ -31,65 +48,4 @@ 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, ...).
|
|
|
|
|
|
---
|
|
|
Next: [Simulation Configuration](/user-docs/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](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/hardware_emulator/-/blob/master/src/main/java/de/rwth/montisim/hardware_emulator/computer/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:
|
|
|
|
|
|
![Config1](/img/config1.png "Select Edit configurations.")
|
|
|
|
|
|
![Config2](/img/config2.png "Create a new JAR config.")
|
|
|
|
|
|
![Config3](/img/config3.png "Select the jar and the working directory.")
|
|
|
|
|
|
|
|
|
### Debugging the hardware_emulator
|
|
|
|
|
|
The [hardware_emulator](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/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](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/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 (attach inside the hardware_emulator project).
|
|
|
- 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.
|
|
|
|
|
|
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.
|
|
|
|
|
|
For other debuggers, if they require a process id to attach to, this id can easily be found by running `jps` (Java process utility).
|
|
|
|
|
|
|
|
|
---
|
|
|
Next: [Simulation Configuration](/user-docs/Simulation-Configuration) |
|
|
\ No newline at end of file |
|
|
Next: [JSON-scenarios reference](/user-docs/JSON-scenarios-reference) |