[中文](Usage.zh-CN.md) | English

# Usage of SimART

## 1. Load visual scene map

Click on `Load Scene Mesh` to load the scene map and you will be able to preview the scene in 3D view window.

## 2. Sionna simulation settings

Click `Simulation Settings` to open the simulation setting window. The window contains some simulation setting items.

- ### Environment
Python environment is the python environment you use while running Sionna simulation. Please make sure that the environment you select has installed the `sionna` package.

The simulation scene XML is the XML file you exported from Blender, which is a simplified version of the scene, for Sionna simulation. The RF information is in fact, calculated from this scene file. The scene file you loaded in step 1 was just for visual purpose.

- ### SYS over RT

If you want to run Sionna SYS link adaptation on top of the RT results and obtain serving base-station and link/channel metrics, enable the check box of `Enable Sionna SYS link adaptation on top of RT` and fill the parameters or just use the default values. A rostopic named `sys_observations` will be shown.

- ### Beamforming_Beam selection

If you want to do the beamforming, enable the check box of `Enable TX beam codebook generation and selection`. The default mode will enable each TX antenna to transmit one of 8 beams listed in the codebook generated by Sionna and provide the oracle beam every moment. Rostopics named `beam_observations` and `codebook` will be shown.

## 3. Coordinate frames settings

Click on `Coordinate Frames`, load the JSON files indicating the transformation between the ROS frame, the 3D scene frame and the AirSim frame.

There are 3 coordinate frames used in the GUI:

- ROS frame: The frame used in the UAV pose topic. The start point of the UAV in this frame is `(0,0,0)`. Usually, it is an NED frame.

- 3D frame: The frame used in the 3D scene. It can be obtained in Blender while loading the 3D scene in it. Or it can also be obtained in Unreal Engine. In Unreal Engine, check the coordinate of the item `PlayerStart`. The coordinate shown in Unreal Engine is in the 3D frame while its corresponding coordinate in the ROS frame is `(0,0,0)`. The translation relationship between the ROS frame and 3D frame can be obtained. The axes shown in 3D view window indicates the direction of the 3D frame. The rotation relationship between the ROS frame and 3D frame can also be obtained.

- AirSim frame: The coordinate shown in Unreal Engine is also in the AirSim frame. Therefore, the 3D frame and AirSim frame are the same under most circumstances.

## 4. Add base stations

In the `Controls/Live info` panel, click `Add` in the `Base Stations` section and then click the desired location in the scene. After selecting a base station, you can edit its coordinates and `TX power`. Each base station stores its own transmit power. A legacy base-station JSON entry without `tx_power_dbm` uses the `10 dBm` default.

To delete a base station, select it and click `Delete selected`.

To save all base-station settings to a JSON file, click `Save JSON`. To load a base-station JSON file, click `Load JSON`.

## 5. Select compulsory topics for sionna simulation

The compulsury input topic for Sionna simulation is the UAV pose topic. After starting the external simulation software, such as AirSim (recommended), Gazebo, or other software, find the UAV pose topic. In ROS1 input topics window, select the UAV pose topic in box `Pose topic`.

## 6. Start the sionna simulation

Click `Start Simulation`, and the simulation will be started. You can view it in the 3D view window.

## 7. UE Live view

Tired of watching the simulation in the 3D mesh? Unreal Engine provides better visual experience! This requires that the UAV is running on AirSim.

Run the UAV simulation in Unreal Engine and AirSim, then switch to the `UE Live View` window in the GUI. Start the UE Live View by clicking `Start Live View` at the bottom, the drone, trajectory, base stations and the rays can be displayed in the UE scene.

Select the base stations in `UE Live View` window, the image of the cameras of selected base stations will be displayed.

## 8. Rosbag tools

Rosbags can also be recorded and replayed in the GUI. In `Rosbag Recording` window, a rosbag can be recorded by clicking `Start Recording` and output to the path you assigned.

Open the `Rosbag Tools` panel, a rosbag can be replayed. The names of the RF, SYS and beam topics in the rosbag should be given. The types of replayed topics can be assigned while the clock topic is recommended to be chosen. Click `Start Playback` to replay the rosbag.

If the rosbag contains any of the RF, SYS, beam and UAV pose topics, the RF, SYS or beam data in the rosbag will be played automatically. If none of the 3 kinds of the topics is contained but UAV pose topic is present, the UAV pose topic will be played and you can click `Start Simulation` to start simulation based on the UAV positions in the rosbag.

The re-sim wireless function provides an approach to add RF, SYS and beam topics into a rosbag without one or some of these topics, or to increase the frequency of the messages in those topics.

## 9. Config file save

The parameters set in the GUI can be saved to a config file. Click `Save Config` to save all the parameters into a config file. When loading a config file, all the parameters saved will be loaded to the GUI.

## 10. RF data, SYS data and beam data previewing

These kinds of data can be reached in the corresponding rostopics. To preview the data, you can open `Wireless Data` and `Sionna SYS` panel.