19  Tutorial - Global Positioning System (GPS) and Ultra Wide Band (UWB)

In this tutorial we will understand GPS and UWB sensors and how to visualize the data using a web application.

After completing this tutorial, you will be able to:

19.1 Getting Started

We will be using the same repository as the previous tutorial. Once the previous tutorial deadline is over, your instructor will update the upstream repository with the necessary files for this tutorial and raise a pull request on your team repository. You will need to pull in the changes from the upstream repository to your team repository to start this tutorial. The instructions to pull in the changes are given in Appendix B.

After you complete the steps shown in Appendix B to synchronize your repository with the upstream repository, navigate to the root directory of your repository. Pull the latest changes made to your team repository onto your local machine.

cd <your-repository-name>
git pull origin main

The relevant folder structure of the repository for this tutorial is shown below.

<your-repository-name>
├── ros2_ws/
│   ├── src/
│   │   ├── student/
│   │   │   ├── tut_02/
│   │   │   ├── tut_03/
│   │   │   ├── tut_04/
│   │   │   ├── tut_05/
│   │   │   ├── tut_06/
│   │   │   └── tut_07/
│   │   │       └── Tutorial_07.md
├── README.md
├── ros2_run_devdocker.sh
├── ros2_run_devdocker.bat
└── LICENSE

Start your own branch from the main branch.

git checkout -b <your-name>

All your group members can work independently on their own branches. However, you will have to merge your branches back to the main branch before the end of the tutorial. We learnt how to do this in Chapter 14 using pull requests.

First start docker desktop and then follow the instructions below to run the course docker container. Make sure to navigate in the terminal to the root folder of your repository.

For Windows:

./ros2_run_devdocker.bat

For Ubuntu (or MacOS):

./ros2_run_devdocker.sh

Source the ROS 2 environment by running the following command:

sros2

Notice that this is an alias for sourcing your ROS 2 workspace as well as the ROS 2 installation in the docker container. Remember that every time you perform a colcon build on your workspace, you need to source the ROS 2 environment again with the command above.

19.2 GPS Sensor

The Global Positioning System (GPS) is a satellite-based navigation system that provides location and time information anywhere on Earth where there is an unobstructed line of sight to four or more GPS satellites. The system consists of three main segments:

  1. Space Segment:
    • A constellation of approximately 30 satellites orbiting Earth
    • Satellites transmit radio signals containing their location and precise time from atomic clocks
    • Arranged in six orbital planes to ensure global coverage
  2. Control Segment:
    • Network of ground stations that monitor and control the satellites
    • Updates satellite positions and clock corrections
    • Ensures accuracy of the system
  3. User Segment:
    • GPS receivers that calculate their position using the signals from satellites
    • Common in smartphones, vehicles, and marine navigation systems

19.2.1 Working Principle

GPS works on the principle of trilateration using precise timing and distance measurements:

  1. Signal Transmission:
    • Each satellite continuously broadcasts radio signals containing:
      • Precise time the signal was sent (from atomic clock)
      • Satellite’s exact orbital position
      • Status information and approximate orbits of other GPS satellites
  2. Position Calculation:
    • The receiver measures the time delay between signal transmission and reception
    • Using the speed of light (\(c \approx 3 \times 10^8\) m/s), it calculates distance to each satellite
    • Minimum of 4 satellites needed for accurate 3D position:
      • Three satellites for \(x\), \(y\), \(z\) coordinates
      • Fourth satellite for time synchronization and error correction
    • The position on the surface of the Earth is reported as latitude, longitude and altitude.
  3. Accuracy and Error Sources:
    • Typical civilian GPS accuracy: 5-10 meters
    • Error sources include:
      • Atmospheric delays
      • Signal multipath
      • Satellite clock errors
      • Orbital errors
      • Receiver noise

19.2.2 Marine Applications

In marine vehicles, GPS is crucial for:

  1. Navigation:
    • Real-time position tracking
    • Course plotting and waypoint navigation
    • Speed over ground measurements
  2. Safety:
    • Emergency position reporting
    • Collision avoidance
    • Search and rescue operations
  3. Integration:
    • Often combined with other sensors (IMU, UWB) for enhanced accuracy
    • Important component in marine autopilot systems
    • Used in dynamic positioning systems

The GPS sensor provides essential absolute positioning information that complements relative positioning sensors like IMUs systems, making it a fundamental component in marine navigation and control systems.

19.3 UWB Sensor

Ultra-Wideband (UWB) technology has emerged as a powerful alternative to GPS for indoor and GPS-denied environments. UWB sensors provide high-precision positioning capabilities through radio frequency signals, making them particularly valuable for applications like wave basin testing where GPS signals are unavailable or unreliable.

19.3.1 Working Principle

UWB operates on fundamentally similar principle as the GPS:

  1. Time-of-Flight Measurements:
    • UWB devices transmit ultra-short pulses across a wide frequency spectrum (>500 MHz bandwidth)
    • Anchors (fixed reference points) and tags (mobile devices) exchange signals
    • System measures precise time-of-flight between devices
    • Position calculated using Time Difference of Arrival (TDoA)
  2. Position Calculation:
    • Minimum of 3 anchors needed for 2D positioning
    • 4 or more anchors required for 3D positioning
    • Uses multilateration algorithms similar to GPS
    • Achieves centimeter-level accuracy in ideal conditions
  3. Key Advantages:
    • Immune to multipath effects due to short pulse duration
    • Low power consumption
    • Works reliably indoors
    • Unlike IMU that relies on compass, UWB is not affected by electromagnetic interference

19.3.2 Wave Basin Applications

UWB technology is particularly valuable for marine testing facilities:

  1. Model Testing:
    • Precise tracking of scaled vessel models
    • Real-time position measurement
  2. System Integration:
    • Often combined with IMU for enhanced accuracy
    • Provides absolute position reference
    • Enables validation of navigation algorithms
  3. Practical Considerations:
    • Anchor placement crucial for optimal coverage
    • Requires careful calibration
    • System redundancy recommended for critical tests

The combination of high accuracy, reliable indoor operation, and resistance to environmental factors makes UWB technology an ideal choice for wave basin testing and other marine research applications where traditional GPS cannot be used.

19.4 Bag File

We will be using the bag file from Chapter 17 to simulate the UWB sensor. The bag file contains the /makara_00/uwb_00 topic which was obtained from a real UWB sensor on a marine vehicle. The bag file is located in the data folder inside the tut_05 folder.

The bag folder contains the directory 09_free which contains the bag file 09_free_0.db3. For our ease of understanding, the data from the bag file is also extracted into csv files hosted inside the directory /workspaces/mavlab/ros2_ws/src/student/tut_05/bag/09_free/. The following CSV files are present:

  • actuator_cmd.csv
  • imu_data.csv
  • odom.csv
  • uwb_data.csv
  • uwb_velocities.csv

The folder also contains a plots folder which contains the plots of the data. You are encouraged to look at the plots to understand the data.

The metadata of the bag file is present in the file metadata.yaml. Feel free to open the file in any text editor to view the metadata.

To play the bag file, run the following command inside the docker container:

ros2 bag play -l /workspaces/mavlab/ros2_ws/src/student/tut_05/bag/09_free/09_free_0.db3

19.5 UWB Message

The UWB sensor on our marine vehicle publishes data to the /makara_00/uwb_00 topic. The message type is geometry_msgs/PoseWithCovarianceStamped.

Open a new terminal and connect to the container by running the following command:

docker exec -it oe3036 bash

We can use the ros2 topic echo command to view the data on the new terminal connected to the container.

sros2
ros2 topic echo /makara_00/uwb_00

The geometry_msgs/PoseWithCovarianceStamped message type has the following fields:

  • header: The header of the message.
  • pose: The pose of the sensor.
  • pose_covariance: The covariance of the pose.

19.6 Create a new ROS2 package

Create a new ROS2 package inside /workspaces/mavlab/ros2_ws/src/student/tut_07

cd /workspaces/mavlab/ros2_ws/src/student/tut_07
ros2 pkg create --build-type ament_python mav_uwb_visualizer --dependencies rclpy std_msgs nav_msgs sensor_msgs geometry_msgs --license MIT

19.7 Create a new launch file

Create a new launch file inside /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer/launch

cd /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer
mkdir launch
cd launch
touch mav_uwb_visualizer_launch.py

Copy the following code into the mav_uwb_visualizer_launch.py file:

Code 
from launch import LaunchDescription
from launch.actions import ExecuteProcess, IncludeLaunchDescription
from launch.launch_description_sources import AnyLaunchDescriptionSource
from launch_ros.substitutions import FindPackageShare
from launch.substitutions import PathJoinSubstitution

def generate_launch_description():
    # Path to the rosbridge launch file
    rosbridge_launch = PathJoinSubstitution([
        FindPackageShare('rosbridge_server'),
        'launch',
        'rosbridge_websocket_launch.xml'
    ])

    # Path to the built web directory
    web_build_dir = PathJoinSubstitution([
        FindPackageShare('mav_uwb_visualizer'),
        'web'
    ])

    return LaunchDescription([
        # Start the HTTP server to serve web files
        ExecuteProcess(
            cmd=['python3', '-m', 'http.server', '8000', '--directory', web_build_dir],
            name='http_server',
            output='screen'
        ),
        # Start the rosbridge server
        IncludeLaunchDescription(
            AnyLaunchDescriptionSource(rosbridge_launch)
        ),        
    ])

This launch file will start a HTTP server to serve the web files and a rosbridge server to communicate with the ROS 2 nodes. As we will be using javascript to visualize the data in our web application, we need to start the rosbridge server to communicate with the ROS 2 nodes.

19.8 Create a new web directory

Create a new web directory inside /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer/ to house the web application.

cd /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer
mkdir web

Create a new index.html file inside /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer/web

cd /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer/web
touch index.html

Copy the following code into the index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Live UWB Visualization</title>
  <!-- Include Chart.js (from CDN or your local node_modules build) -->
  <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
  <!-- Include ROSLIBJS (from your node_modules or a CDN) -->  
  <script src="https://cdnjs.cloudflare.com/ajax/libs/roslibjs/1.1.0/roslib.min.js" integrity="sha512-x2Owc9WayRcRj80Znkau58shVfXN2OIX+gQAlrx6KPugZBKrIC6AwgEWQQCI06p2Q8RB4ilxD+y+1BdNd+1fQA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
  <style>
    body {
      font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
      max-width: 1200px;
      margin: 0 auto;
      padding: 20px;
      background-color: #f5f5f5;
    }
    
    h1, h2 {
      color: #2c3e50;
      text-align: center;
      margin-top: 30px;
    }

    h1 {
      font-size: 2.5em;
      margin-bottom: 40px;
      border-bottom: 2px solid #3498db;
      padding-bottom: 10px;
    }

    .chart-container {
      background: white;
      border-radius: 10px;
      box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
      padding: 20px;
      margin: 20px auto;
      max-width: 800px;
    }

    canvas {
      max-width: 100%;
      height: auto;
      margin: 10px auto;
      display: block;
    }
  </style>
</head>
<body>
  <h1>UWB Data Visualization</h1>

  <div class="chart-container">
    <h2>UWB Position (m)</h2>
    <canvas id="uwbChart"></canvas>
  </div>

  <!-- Main JavaScript file -->
  <script src="main.js"></script>
</body>
</html>

This file is a simple HTML file that will be used to visualize the UWB data. It contains a header with the title of the web application and a main section with a chart to visualize the UWB position.

Create a new main.js file inside /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer/web

cd /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer/web
touch main.js

Copy the following code into the main.js file:

// Connect to rosbridge websocket (adjust the URL as needed)
var ros = new ROSLIB.Ros({
    url: 'ws://localhost:9090'
  });
  
  ros.on('connection', function () {
    console.log('Connected to rosbridge.');
  });
  ros.on('error', function (error) {
    console.error('Error connecting to rosbridge: ', error);
  });
  
  // Create a subscriber to the /makara_00/uwb_00 topic
  var uwbTopic = new ROSLIB.Topic({
    ros: ros,
    name: '/makara_00/uwb_00',
    messageType: 'geometry_msgs/PoseWithCovarianceStamped'
  });
  
  // Set up Chart.js charts
  function createChart(ctx, label, borderColor) {
    return new Chart(ctx, {
      type: 'line',
      data: {
        labels: [], // time or sample index
        datasets: [{
          label: label,
          data: [],
          borderColor: borderColor,
          fill: false,
          tension: 0.1,
        }]
      },
      options: {
        animation: false,
        responsive: true,
        scales: { x: { display: false } }
      }
    });
  }
  
  // Get canvas contexts
  var uwbCtx = document.getElementById('uwbChart').getContext('2d');
  
  // Create charts for each data type.
  // For acceleration and angular velocity, we use one chart per topic (each with three datasets for x, y, z).
  var uwbChart = new Chart(uwbCtx, {
    type: 'line',
    data: {
      labels: [],
      datasets: [
        { label: 'X', data: [], borderColor: 'red', fill: false },
        { label: 'Y', data: [], borderColor: 'green', fill: false },
        { label: 'Z', data: [], borderColor: 'blue', fill: false },
      ]
    },
    options: { animation: false, responsive: true, scales: { x: { display: false } } }
  });
  
  var sampleIndex = 0;
  
  function updateUwbChart(x, y, z) {
    uwbChart.data.labels.push(sampleIndex);
    uwbChart.data.datasets[0].data.push(x);
    uwbChart.data.datasets[1].data.push(y);
    uwbChart.data.datasets[2].data.push(z);
    if (uwbChart.data.labels.length > 100) {
      uwbChart.data.labels.shift();
      uwbChart.data.datasets.forEach(ds => ds.data.shift());
    }
    uwbChart.update();
  }
  
  // Subscribe to the /makara_00/uwb_00 topic
  uwbTopic.subscribe(function (message) {
    // Increment our sample index for the x-axis
    sampleIndex++;
  
    // Extract accelerations and angular velocities
    var uwb = message.pose.pose.position; // {x, y, z}
    
    // Update the charts
    updateUwbChart(uwb.x, uwb.y, uwb.z);
  });

This file is a javascript file that will be used to visualize the UWB data. It contains a subscriber to the /makara_00/uwb_00 topic and a function to update the charts with the latest data.

19.9 Modify the setup.py file

Modify the setup.py file to include the chart.js and roslib packages.

cd /workspaces/mavlab/ros2_ws/src/student/tut_07/mav_uwb_visualizer

Overwrite the existing setup.py file with the following code:

Code 
from setuptools import find_packages, setup
import os
from glob import glob

package_name = 'mav_uwb_visualizer'

setup(
    name=package_name,
    version='0.0.0',
    packages=find_packages(exclude=['test']),
    data_files=[
        ('share/ament_index/resource_index/packages',
            ['resource/' + package_name]),
        ('share/' + package_name, ['package.xml']),
        (os.path.join('share', package_name, 'launch'), glob('launch/*.py')),
        (os.path.join('share', package_name, 'web'), glob('web/*.html')),
        (os.path.join('share', package_name, 'web'), glob('web/*.js')),
        (os.path.join('share', package_name, 'web', 'node_modules', 'roslib', 'build'), 
         glob('web/node_modules/roslib/build/*')),
        (os.path.join('share', package_name, 'web', 'node_modules', 'chart.js', 'dist'), 
         glob('web/node_modules/chart.js/dist/*.js')),
    ],
    install_requires=['setuptools'],
    zip_safe=True,
    maintainer='Abhilash Somayajula',
    maintainer_email='abhilash@iitm.ac.in',
    description='MAV Lab - UWB Data Visualizer',
    license='MIT',
    tests_require=['pytest'],
    entry_points={
        'console_scripts': [
        ],
    },
)

This will include the chart.js and roslib packages in the ROS2 package.

19.10 Build the ROS2 package

cd /workspaces/mavlab/ros2_ws
rm -rf build install log
colcon build
sros2

19.11 Run the ROS2 package

ros2 launch mav_uwb_visualizer mav_uwb_visualizer_launch.py

19.12 Open the web application

Navigate to the web page http://localhost:8000 in your browser

You should see the UWB data visualizer. If you are running the bag file from the previous section, you will see the UWB data getting plotted in the web application.

During the evaluation, the instructor will launch the UWB sensor. You will then open the web application in your browser and see the UWB data in real-time.

19.13 Instructions for the day of the tutorial

  • Connect to the mavlab network (ask the instructor for the password)
  • Launch the mav_uwb_visualizer ROS2 package as instructed above
  • Open the web application in your browser
  • The instructor will launch the UWB sensor and you will see the UWB data in real-time in the web application

19.14 Evaluation

The evaluation of the tutorial will be performed in the classroom. Notice that this is a group activity. You will be working in a group of 4 students. The evaluation will be performed on the group level. In order to pass the tutorial, the group must pass all the tests in the GitHub Actions workflow and also be able to answer all the questions during the evaluation in the classroom. Those who are not present in the classroom on the day of evaluation will not be able to participate in the evaluation and will automatically fail the tutorial.

While one of the objectives of these tutorials is to give you hands on experience with coding and practical implementation, the more important goal is to help you relate what you are doing in your tutorials to the underlying concepts discussed in the class. Therefore, while you are working on the implementation tasks, make sure you are also thinking about the underlying concepts and how they are being applied in the code.

Some questions to think about while you are working on the implementation tasks:

  • Is your code able to pass all the tests in the GitHub Actions workflow?
  • Are you able to show plotting of the live UWB data during the evaluation?
  • When echoing the /makara_00/uwb_00 topic, what is the message type?
  • What is a covariance matrix? What does it tell us about the measurement?
  • Do you think the covariance has any practical significance in real life applications of the UWB?
  • What is the size of the covariance matrix corresponding to the position? Is this consistent with the measurement being reported?
  • If you were asked to choose between two UWB sensors, how would you compare them?
  • What is meant by the term trilateration? How does the UWB sensor use this principle to determine the position of the sensor?
  • How does the UWB sensor differ from the GPS sensor?
  • Why are 4 anchors required for 3D positioning?

19.15 Instructor Feedback through Pull Requests

Commit your changes to the remote repository often. This will help you to track your progress and also help you to revert to a working version if you make a mistake. In addition, the instructor and TA will be able to provide you with feedback on your code through the Feedback pull request available in your repository. Please do not close this pull request.