System use

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.

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:

   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:

./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:

docker stop ros1_multilateration

6. Troubleshooting

Previous Container Still Running

If you see a message indicating the container is already running:

1. Stop it:

   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:

   docker logs ros1_multilateration

2. Ensure that the Real_JEMERG23.sh script completes successfully and creates the notification file:

   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:

   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.