# System use
📽️ [See video](https://youtu.be/VCplzhRPONY)

## Description
This project uses a Docker container to execute a multilateration algorithm in real-time on a raw dataset, processed offline, while allowing graphical visualization of the results. Everything is managed by a launch script (docker_launch.sh) that automates the process and ensures it runs in a controlled environment.

## Requirements
Before starting, ensure you have the following installed:

- Docker
- Permissions to use X11 on the host system (for graphical visualization)
- Access to the project repository, which contains the necessary scripts.
- MATLAB R2023b or higher versions.

## Project Structure
The project is organized as follows:

```
ROUD_ps/
├── Dataset/
│   ├── experiment_recording.bag
│   ├── raw_data.bag
│   └── Real_JEMERG23.sh
├── Code/
│   ├── SARFIS/
│   │   ├── DEM files/
│   │   ├── Matlab functions/
│   │   │   ├── DEM/
│   │   │   ├── GPX/
│   │   │   ├── GUI/
│   │   │   └── ROS/
│   │   │       ├── experimentRosbag.bag
│   │   │       ├── rawRosbag.bag
│   │   │       └── ROSbag_play.m
│   │   ├── resources/
│   │   ├── works/
│   │   └── SARFIS.prj
│   ├── Multilateration/
│   │   ├── server_ros_bridge.py
│   │   ├── ros_wrapper.py
│   │   ├── data_visualization.py
│   │   ├── positioning_rtt_ils.py
│   │   └── anchors_positions.py
├── Figures/
├── Demo/
│   └── video-demo.mp4
└── docker_launch.sh
```

- `Code/Multilateration/`: contains the multilateration algorithm and workflow to be applied on the provided dataset.
- `Dataset/`: contains the real data from the experiment and raw data to be processed offline.
- `SARFIS/Matlab functions/ROS/`: folder where new recorded rosbags are stored.
- `docker_launch.sh`: shell script used to automate tasks.

## DEM Files

The `Code/SARFIS/DEM_files/` directory is currently empty.

Please download the required Digital Elevation Model (DEM) files and place them inside this folder.  
You can access and download the files from the following link:

🔗 [DEM files](https://uma365-my.sharepoint.com/my?id=%2Fpersonal%2Fjbravo%5Fuma%5Fes%2FDocuments%2FDEM%20files&ga=1)


## Instructions

### 1. Initial Setup

Build the docker image: 
```
docker build -t ros-noetic-multilateration .
```

Before launching the container:

1. Ensure the required files (e.g., `server_ros_bridge.py`, `ros_wrapper.py`, `data_visualization.py`, and `Real_JEMERG23.sh`) are present in the expected paths (see the project's structure).
2. Verify that you have X11 access from Docker:
   ```bash
   xhost +local:root
   ```
3. Stops and removes any previous container with the name `ros1_multilateration`.
   ```
   docker stop ros1_multilateration
   docker rm ros1_multilateration
   ```

### 2. Launch the Container indicating the estimation mode applied in the multilateration algorithm.
1. To launch the container and execute the workflow:

```bash
./docker_launch.sh OLS
```
Where `OLS` is the specified estimation mode. You can replace the Ordinary Least Squares mode (`OLS`) with other estimation methods if supported by the `Real_JEMERG23.sh` script.

2. The user can access the container from other terminals using:
   ```
   docker exec -it ros1_multilateration bash
   ```

### 3. Automated Process
The `docker_launch.sh` script performs the following tasks:

1. Executes the `Real_JEMERG23.sh` script, which includes:
   - Initializing `roscore`.
   - Playing the rosbag 
   - Launching the raw
   - Recording a new rosbag in the `SARFIS/Matlab functions/ROS/` folder.
2. Waits for all processes (e.g., rosbag play, recording) to complete.
3. Automatically detects the recorded rosbag and extracts its start and end times.
4. Executes the `data_visualization.py` script with the detected parameters.

### 4. Resulting Files
Workflow results include:
- A recorded rosbag file in `SARFIS/Matlab functions/ROS/`.
- Graphs generated by `data_visualization.py`.

### 5. Stopping the Container
The container will remain active after the workflow finishes. You can stop it manually with:

```bash
docker stop ros1_multilateration
```

### 6. Troubleshooting

#### Previous Container Still Running
If you see a message indicating the container is already running:

1. Stop it:
   ```bash
   docker rm -f ros1_multilateration
   ```

#### Notification File Not Created
If the script appears to hang waiting for the notification file (`/tmp/rosbag_record_done`):
1. Check the container logs:
   ```bash
   docker logs ros1_multilateration
   ```
2. Ensure that the `Real_JEMERG23.sh` script completes successfully and creates the notification file:
   ```bash
   touch /tmp/rosbag_record_done
   ```

#### Rosbag File Not Found
If the recorded rosbag file is not found:
1. Verify that the output directory is correctly configured:
   ```bash
   ls "SARFIS/Matlab functions/ROS/"
   ```
2. Check the directory permissions and container logs.


### 7. Additional Notes
- To customize the workflow, modify the `Real_JEMERG23.sh` or `data_visualization.py` scripts as needed.
- If you need to add new execution modes or filters, ensure the relevant scripts are updated accordingly.

### 8. Explanation of SARFIS Tool

The SARFIS tool requires two instances of MATLAB:

1. **First Instance:**
   - Start the master ROS node with `rosinit('localhost')`.
   - Create the ROS 1 publishers by executing the `ROSbag_play` function which is in the `SARFIS/Matlab functions/ROS/` folder.
   - Pause execution, waiting for the user to press ENTER after creating the subscribers in the second MATLAB instance.

2. **Second Instance:**
   - Open the SARFIS tool.
   - Connect to the master from the tool's interface (no need to specify the port; it defaults to 11311).
   - Create the 6 default agents using the `add` button. The associated subscribers are configured by default.
   - Create the subscriber associated with geolocation in the `Global Settings` tab.

3. **Final Step:**
   - Return to the first MATLAB instance and press ENTER.
   - Observe the recorded bag being replayed offline in the SARFIS tool.



